Getting Started with the Windows Azure Toolkit for iOS
IMPORTANT UPDATE:
Since the initial launch of the Windows Azure Toolkit for iOS, we’ve not only updated & changed the library, but we’ve also renamed the repository. For the latest information, please visit our github repository at http://github.com/microsoft-dpe/ – from here you can get access to the iOS library, Android library, and all the additional tools we’ve made available.
I am extremely excited to announce the immediate availability of the Windows Azure Toolkit for iOS!
This first release of the Windows Azure Toolkit for iOS provides an easy and convenient way of accessing Windows Azure storage from iOS-based applications. As with the Windows Azure Toolkit for Windows Phone 7 we will continue to bring additional capabilities to the toolkit, such as push notifications, Access Control Service, and more.
You can get the toolkit—and all the source code—on github:
- Source code & zip: https://github.com/microsoft-dpe/watoolkitios-lib
- Sample application: https://github.com/microsoft-dpe/watoolkitios-samples
- Documentation: https://github.com/microsoft-dpe/watoolkitios-doc
The toolkit works in two ways: the toolkit can be used to access Windows Azure storage directly, or alternatively, can go through a proxy service. The proxy service code is the same code as used in the Windows Azure Toolkit for Windows Phone 7 and negates the need for the developer to store the Azure storage credentials locally on the device.
The release of the Windows Azure Toolkit for iOS is a significant milestone, and reinforces my opinion that Windows Azure is a great place to run services for mobile applications.
Setting up your Windows Azure services
To quickly get your mobile services up and running in Windows Azure, take a look at the Cloud Ready Package for Devices (found under downloads in https://github.com/microsoft-dpe/watoolkitios-lib).
The Cloud Ready Package for Devices is designed to make it easier for you to build mobile applications that leverage cloud services running in Windows Azure. Instead of having to open up Visual Studio and compile a solution with the services you want to use, we provide you with the Windows Azure CSPKG and CSCFG files prebuilt – all you need to do is update the configuration file to point to your account.
In this video, you’ll see how easy it is to deploy this package to Windows Azure regardless of your operating system (e.g. Windows 7 or OSX) and target device (e.g. Windows Phone 7, iOS, or Android).
Unpacking the v1.0.0 library zip file
You can download the compiled storage library on github (found under downloads in https://github.com/microsoft-dpe/watoolkitios-lib). When you upzip the zip file, you’ll find several folders:
- /4.3-device – the library binary for iOS 4.3 (device)
- /4.3-simulator – the library binary for iOS 4.3 (simulator)
- /include – the headers for the library
Creating your first project using the toolkit
If you are not familiar with XCode, this is a short tutorial for getting your first project up and running. Launch XCode 4 and create a new project:
![clip_image002[4]_thumb](http://images.wadewegner.com/wordpress/2011/05/clip_image0024_thumb.jpg "clip_image002[4]_thumb")
Select a View-based application and click Next.
Give the project a name and company. For the purposes of this walkthrough, we’ll call it “FirstAzureProject”. Do not include Unit Tests.
![clip_image004[4]_thumb](http://images.wadewegner.com/wordpress/2011/05/clip_image0044_thumb.jpg "clip_image004[4]_thumb")
Pick a folder to save the project to, and uncheck the source code repository checkbox.
When the project opens, right click on the Frameworks folder and select “Add Files to…”
![clip_image006[4]_thumb](http://images.wadewegner.com/wordpress/2011/05/clip_image0064_thumb.jpg "clip_image006[4]_thumb")
Locate the libwatoolkitios.a library file from the download package folder (from either the simulator or device folder), and add it to the Frameworks folder.
Now, click on the top most project (FirstAzureProject) in the left hand column. Click on the target in the second column. Click on the “Build Settings” header in the third column. Ensure that the “All” button is selected to show all settings.
In the search box, type in “header search” and look for an entry called “Header Search Paths”:
Double-click on this line (towards the right of the line), and click on the “+” button in the lower left.
Add the path to where the folder containing the header files are located (this is the include folder from the download). For example, "~/Desktop/v1.0.0/include" if you have extracted the folder on your desktop. Be sure to encapsulate in quotes if you have spaces in the path.
Now, click on the “Build Phases” tab and expand the “Link Binary with Libraries” section:
Click on the “+” button in the lower left, and scroll down until you find a library called “libxml2.2.7.3.dylib”. Add this library to your project.
Testing Everything Works
Now that you’ve added all of the required references, let’s test that the library can be called. To do this, double click on the [ProjectName]AppDelegate.m file (e.g. FirstAzureProjectAppDelegate.m), and add the following imports to the class:
#import "AuthenticationCredential.h"
#import "CloudStorageClient.h"
Perform a build. If the build succeeds, the library is correctly added to the project. If it fails, it is recommended to go back and check the header search paths.
Assuming it builds, in the .m file, add the following declarations after the @synthesize lines:
AuthenticationCredential *credential;
CloudStorageClient *client;
Now, add the following lines after the [self.window makeKeyAndVisible] line in the didFinishLaunchingWithOptions method:
credential = [AuthenticationCredential credentialWithAzureServiceAccount:@"ACCOUNT_NAME" accessKey:@"ACCOUNT_KEY"];
client = [CloudStorageClient storageClientWithCredential:credential];
[client getBlobContainersWithBlock:^(NSArray* containers, NSError* error)
{
if (error)
{
NSLog(@"%@",[error localizedDescription]);
}
else
{
NSLog(@"%i containers were found…",[containers count]);
}
}];
Be sure to replace ACCOUNT_NAME and ACCOUNT_KEY with your Windows Azure storage account name and key, available on the Windows Azure portal (http://windows.azure.com).
Build and run the project. You should something similar to the following output in the debug window:
- 2011-05-06 18:18:46.001 FirstAzureProject[27456:207] 2 containers were found…
The last line shows that this account has 2 containers. This will of course vary, depending on how many blob containers you have setup in your own Windows Azure account.
Doing more with the toolkit
Feel free to explore the class documentation to explore more of the toolkit API. To help, here are some additional examples:
In [ProjectName]AppDelegate.m class, add the following headers:
#import "AuthenticationCredential.h"
#import "CloudStorageClient.h"
#import "BlobContainer.h"
#import "Blob.h"
#import "TableEntity.h"
#import "TableFetchRequest.h"
In the didFinishLaunchingWithOptions method, after the [self.window makeKeyAndVisible] line, try testing a few of the following commands. Again, running the project will return results into the debugger window.
To authenticate using account name and key:
credential = [AuthenticationCredential credentialWithAzureServiceAccount:@"ACCOUNT_NAME" accessKey:@"ACCOUNT_KEY"];
To authenticate instead using the proxy service from the Windows Phone 7 toolkit, you can use the following:
credential = [AuthenticationCredential authenticateCredentialWithProxyURL:[NSURL URLWithString:@"PROXY_URL"] user:@"USERNAME" password:@"PASSWORD" withBlock:^(NSError *error)
{
if (error)
{
NSLog(@"%@",[error localizedDescription]);
}
else
{
NSLog(@"Successfully logged in");
}
}];
Replace the PROXY_URL, USERNAME, and PASSWORD with the information required to access your proxy service.
To create a new client using the credentials:
client = [CloudStorageClient storageClientWithCredential:credential];
To list all blob containers (this method is not supported via the proxy server):
// get all blob containers
[client getBlobContainersWithBlock:^(NSArray *containers, NSError *error)
{
if (error)
{
NSLog(@"%@",[error localizedDescription]);
}
else
{
NSLog(@"%i containers were found…",[containers count]);
}
}];
To get all blobs within a container (this also is not supported by the proxy):
// get all blobs within a container
[client getBlobs:@"images" withBlock:^(NSArray *blobs, NSError *error)
{
if (error)
{
NSLog(@"%@",[error localizedDescription]);
}
else
{
NSLog(@"%i blobs were found in the images container…",[blobs count]);
}
}];
To get all tables from storage (this works with both direct access and proxy):
// get all tables
[client getTablesWithBlock:^(NSArray* tables, NSError* error)
{
if (error)
{
NSLog(@"%@",[error localizedDescription]);
}
else
{
NSLog(@"%i tables found",[tables count]);
}
}];
To create a table (works with both direct access and proxy):
// create table
[client createTableNamed:@"wadestable" withBlock:^(NSError *error)
{
if (error)
{
NSLog(@"%@",[error localizedDescription]);
}
else
{
NSLog(@"Table created");
}
}];
To delete a table (works with both direct access and proxy):
//delete a table
[client deleteTableNamed:@"wadestable" withBlock:^(NSError *error)
{
if (error)
{
NSLog(@"%@",[error localizedDescription]);
}
else
{
NSLog(@"Table was deleted");
}
}];
To get entities for a table (works with both account key and proxy):
// get entities for table developers
TableFetchRequest* fetchRequest = [TableFetchRequest fetchRequestForTable:@"Developers"];
[client getEntities:fetchRequest withBlock:^(NSArray *entities, NSError *error)
{
if (error)
{
NSLog(@"%@",[error localizedDescription]);
}
else
{
NSLog(@"%i entities found in the developer table",[entities count]);
}
}];
To get entities for a table using predicate (works with both account key and proxy):
// get entities for table developers with predicate request
NSError* error = nil;
NSPredicate* predicate = [NSPredicate predicateWithFormat:@"Name = 'Wade' || Name = 'Vittorio' || Name = 'Nathan'"];
TableFetchRequest* anotherFetchRequest = [TableFetchRequest fetchRequestForTable:@"Developers" predicate:predicate error:&error];
[client getEntities:anotherFetchRequest withBlock:^(NSArray *entities, NSError *error)
{
if (error)
{
NSLog(@"%@",[error localizedDescription]);
}
else
{
NSLog(@"%i entities returned by this request",[entities count]);
}
}];
Doing even more with the toolkit
If you are looking to explore the toolkit further, I recommend looking at the sample application that can be found in the watoolkitios-samples project. This project demonstrates all of the functionality of the toolkit, including creating, uploading, and retrieving entities from both table and blob storage.
[...] Wade Wegner’s blog: Getting Started with the Windows Azure Toolkit for iOS [...]
Are there plans o support SQL Azure on this toolkit?
What kind of support are you looking to have for SQL Azure? Something beyond showing how to create a service (e.g. OData) that proxies to SQL Azure? If you can help me understand the use case I can look into prioritizing it in a future release. Thanks!
We are developing a web based accounting application built on Azure, with multi tenanted data stored on SQL Azure. A typical iOS use case would be to provide a application to view customer account data, or provide a mechanism to enter a transaction on the device that would synch up to the SQL Azure Database.
I agree that SQL Azure would be at the top of my list in terms of need.
Initial requirements are basic support for Selects with joins output to a recordset and ability to iterate through. Basic CRUD support. Management of tables and DB’s can be deferred for later release.
Good stuff!
I assume this is an alpha version and that a proper prefix will be added to the classes in the lib for the final release?
Thanks, Fredrik!
What proper prefix are you looking for? Teach me!
Objective-C is but a thin layer on top of C, so most things missing from C is also lacking on Objective-C. Most notable namespaces. That means that any symbol name (globals, classes, etc.) you define is globally defined and may/will clash with any other library or class your users may use.
The more common a name you choose, the more likely it is that your name will clash with something else in the future. This means that for example the class Queue is a very common name, and the Azure toolkit has now claimed it as it’s own.
This is why all names in Objective-C use a prefix, a simple workaround for the lack of namespaces. Foundation uses for example NS, as in NSObject, NSArray, etc. And UIKit use UI as in UIView, UISwitch, etc. Then we have CA for Core Animation, CG for Core Graphics, and I could continue for ever.
Apple recommends that two letter prefixes are reserved to platform API:s, and that third party devs use three letter prefixes.
Windows Azure Toolkit could use for example WAT as a prefix. Thus Queue would be WATQueue, and the likelihood for a clash is minimal. Unless another dev decides to use the same prefix, but then you just duel for it
.
Fabulous details – thank you. We’re going to change this in the next drop.
. . . another approach to the Objective-C namespace problem is to place a @compatibility_alias at the bottom of the header file. We’re using this approach on the expanz iOS SDK – soon to be public. We find that it works well.
As well as avoiding namespace collisions, It also helps to group API documentation into sections.
Here’s an example:
@interface expanz_model_ActivityDefinition : NSObject
@property(nonatomic, readonly) NSString* name;
@property(nonatomic, readonly) NSString* title;
@property(nonatomic, readonly) ExpanzActivityStyle style;
- (id) initWithName:(NSString*)name title:(NSString*)title style:(ExpanzActivityStyle)style;
@end
/* ================================================================= */
@compatibility_alias ActivityDefinition expanz_model_ActivityDefinition;
[...] [...]
[...] Comment démarrer avec iOs : http://www.wadewegner.com/2011/05/windows-azure-toolkit-for-ios/ [...]
[...] are available for developers seeking additional information: Getting Started with the iOS Toolkit and Deploying the Cloud Ready Package for [...]
[...] No post no blog do Wade Wegner há também a demonstração da criação de um projeto IOS usando o XCode e referenciando o Windows Azure Toolkit para IOS. [...]
[...] Wade Wegner [...]
[...] [...]
[...] are available for developers seeking additional information: Getting Started with the iOS Toolkit and Deploying the Cloud Ready Package for Devices. Windows Azure Technical Evangelist Wade [...]
[...] So what does Microsoft provide? I will let Wade Wenger explain. [...]
[...] Released today, the Windows Azure Toolkit for iOS is designed to help developers targeting iOS to use Windows Azure services. It includes an open source Objective-C library to interface with Windows Azure services, documentation, and a sample application using the library. You can download the samples and documentation from github, along with the library and its source, or learn more about the details. [...]
[...] [...]
[...] also includes full source code for the aforementioned Objective-C library with Xcode project files. Click here to get more details on Azure Toolkit for iOS. Well, It is expected that the Android toolkit will be [...]
[...] Wade Wegner’s blog: Getting Started with the Windows Azure Toolkit for iOS [...]
This is, potentially, very cool. I have a very large Azure(Blob and SQL Azure), WCF, Silverlight project. If this is secure and there is support for SQL Azure it would be much easier than converting the WCF based interface for the IPhone/iPad.
As a pretty rank IOs newbie (and havn’t started on the Android at all yet) I’m a bit concerned about compiling:
credential = [AuthenticationCredential credentialWithAzureServiceAccount:@"ACCOUNT_NAME" accessKey:@"ACCOUNT_KEY"];
into the app.
1. Android/IoS experts, a question for you. Do we have any possibility of the credentials being hacked.
With the turn around time for changes in iphone apps to make it through the AppStore approval, we have a bit of an issue if we have to change credentials. It could be a couple of weeks from the time we get a new credential, before we can release code with it. With no limit to the number of different release schedules (SL, IoS [Iphone and iPad], android versions [who knows how many versions of that beast you could have to code around]), we could have usage contentions with only 2 sets of credentials to work with.
2. Do we see any issus with that? It would look like we would need a primary and secondary credential for each version of our app.
3. Fredrick’s point is excellent. Do you expect a prefix change in response?
Sorry, but one more concern on item #2. If we do execute a credential change, there’s no way to ensure all IoS clients have the most current version with the correct credential. Thoughts?
Regarding the question about compiling your storage account name and key into your binaries..
This is exactly why there is the concept of a proxy, should you choose to use it. With a proxy, a user on the iOS device sends a name and password to your server located in Azure, which then connects the user to the appropriate storage account. No Azure credentials are actually stored on the device at all.
Check the – (IBAction)login:(id)sender selector in RootViewController.m in the samples for an example of this.
Regardling your question about the storage account name/key, Chris has it right. For any resource that needs to remain secure, use the proxy that’s provided as part of the kit.
Regarding the prefix change – yes, we will update soon.
Thanks!
[...] a contrast to the Doxyfile docs for the iOS toolkit and its few samples, though Wade Wegner has a walkthrough. One comment asks reasonably enough why the toolkit does not use a two or three letter prefix for [...]
[...] are available for developers seeking additional information: Getting Started with the iOS Toolkit and Deploying the Cloud Ready Package for Devices. Links to access the free toolkits are [...]
[...] Getting Started with the Windows Azure Toolkit for iOS [...]
[...] and modify the services.Screencasts are available for developers seeking additional information: Getting Started with the iOS Toolkit and Deploying the Cloud Ready Package for Devices. Links to access the free toolkits are below: [...]
[...] [...]
[...] Getting Started with the Windows Azure Toolkit for iOS : Details how to get started using the Windows Azure Toolkit for iOS [...]
Hi, thanks for the toolkit. I downloaded the sample and ran it. the sample app ran into EXC_BAD_ACCESS at NSURLConnection(NSURLConnectionReallyInternal) sendDidfinishLoading. Are you realeasing any resource while it is still being used in your library?
[...] has put together a walkthrough for the toolkit, showing [...]
[...] http://www.wadewegner.com/2011/05/windows-azure-toolkit-for-ios/ d912fb65-a9e4-42d6-98fa-ee5e0f932a79|0|.0 [...]
[...] Wade Wegner’s blog: Getting Started with the Windows Azure Toolkit for iOS [...]
[...] Empezando con las herramientas para iOS [...]
There’s an error in your setup walkthrough that I think you should change.
In your walkthrough, you specify to link against the library file “libxml2.2.7.3.dylib”. However, if you do this, you’ll get an error similar to the following: ld: warning: ignoring file /Users/chrisw/Source/test/libwatoolkitios.a, missing required architecture i386 in file
In the sample project, it links against the library file “libxml2.2.dylib”, which is also what the source is built against. If you follow the walkthough and substitute “libxml2.2.dylib” instead of “libxml2.2.7.3.dylib”, you’ll be able to build without errors.
Hi Chris,
I had the error you described: ignoring file /Users/chrisw/Source/test/libwatoolkitios.a, missing required architecture i386 in file. However, even i uses “libxml2.2.dylib”, it still doesn’t work. Any suggestion?
For bugs and/or issues, I recommend you log them on github so that we can actively track it: https://github.com/microsoft-dpe/watoolkitios-lib/issues
mingfeiy, please make sure you’re using a correct *.a file. If you’re building your project for the simulator, you should use the one from “simulator” folder. Hope this helps!
[...] Getting Started with the Windows Azure Toolkit for iOS : Details how to get started using the Windows Azure Toolkit for iOS [...]
Are there any plans to support continuation tokens in the future (i.e. x-ms-continuation-NextPartitionKey and x-ms-continuation-NextRowKey)? As it is, the lib only seems to support retrieving the initial 1000 entities. Even though it’s a mobile device, I can easily see pulling down more than 1000 entities per query into my app.
Question, Wade.
The SSL required: the documentation seems to imply it can be any SSL certificate I have laying around? It says to go to http://msdn.microsoft.com/library/gg981937.aspx but that is very opaque. The service is hosted in the Cloud and not on my local IIS server so how does requesting an SSL Cert for my local IIS Server help.
Thanks!
Apologies for the confusion. I’m updating the wiki documentation right now for tomorrow’s release – hopefully it will be more complete. Thanks!
[...] you can easily use the Windows Azure Toolkit for iOS to work with this service running in Windows [...]
[...] to subscribe to the RSS feed for updates on this topic.The WIndows Phone 7 guys just released the Windows Azure Toolkit for Windows Phone 7 (v1.2) in time for TechEd North America 2011. This release includes some important new features, [...]
[...] [...]
[...] Wade Wegner » Blog Archive » Getting Started with the Windows Azure Toolkit for iOS [...]
[...] ver la información en detalle en este enlace (inglés). Share | Tags: Azure, Puch, Push Notification, SQL Azure, Windows Azure Posted 17 May [...]
[...] 0 Microsoft launched the Windows Azure Toolkit for iOS, as part of TechEd North America 2011, Microsoft have released the Windows Azure Toolkit for [...]
[...] [...]
[...] [...]
[...] Windows Phone 7, iOS, or Android). See Wade Wegner’s posts for more information on the Windows Azure Toolkit for iOS and the Windows Azure Toolkit for Windows Phone [...]
[...] Getting Started with the Windows Azure Toolkit for iOS [...]
[...] Getting Started with the Windows Azure Toolkit for iOS [...]
[...] For details on how to get started, see Wade Wegner’s post on Getting Started with the Windows Azure Toolkit for iOS. [...]
Question for Wade:
I’m trying to use the proxy feature. What is the format of the proxy URL? Can you give me an example? Thx
[...] [...]
[...] about the same time, the team (and Wade specifically) released a version of the same toolkit tailored to iOS developers. That first iOS version integrated with the core Windows Azure services, but didn’t take [...]
[...] cette raison que les équipes Windows Azure proposent un kit de développement pour Windows Phone, iPhone/iOS, et Android (prévu [...]
[...] May 16, 2011 at 10:29 am The WIndows Phone 7 guys just released the Windows Azure Toolkit for Windows Phone 7 (v1.2) in time for TechEd North America 2011. This release includes some important new features, [...]
Any suggestion on how to create a predicate with date time or boolean values?
I am adding a certificate to the Azure Hosting Service, and it’s not completely clear in the docs of the CloudReady packages whether the form of the certificate’s Common Name should be either something like ‘www.mydomainname.xxx’, or that of the Hosted Service, i.e. ‘mydomainname.cloudapp.net’. In the Azure books-on-line docs it indicates not to use ‘*cloudapp.net’, but not sure if this applies here.
If you’re using your own custom domain then use it (not *.cloudapp.net).
[...] http://www.wadewegner.com/2011/05/windows-azure-toolkit-for-ios/ [...]
links to github are broken
[...] Getting Started with Windows Azure Toolkit for iOS: Again, not a recent article (May 2011), but updated with new information this week. [...]
Hello,
I’ve downloaded the new WA Toolkit for iOS and tried but the authentication isn’t work. I’ve tried with same storage name and password that works fine with a WorkerRole and ServerRole.
The error message:
“Server failure to authenticate the request. Make sure the value of Authorization header is formed correctly including the signature.”
Could you help me?
[...] 8, 2011] – Windows Azure Toolkit for iOS Now Supports the Access Control Service [July 25, 2011] – Getting Started with the Windows Azure Toolkit for iOS [May 6, 2011] – Windows Azure Toolkit for Windows Phone 7 [March 23, 2011] Like this:TetszikJelezd [...]
Is there an updated version of the toolkit that works with iOS5? After reviewing github, it looks like the installation instructions reference iOS 4.x. If anyone could point in the direction of any resource or build that would be great.