Introducing the Azure API Apps Tools for Visual Studio 2013
With the Azure SDK 2.5.1 Release we took the opportunity to combine existing Web Publishing techniques with the new Azure Resource Management APIs to support Azure’s newest feature for Web, Mobile, and API developers – Azure App Service. We’ve added Azure API Apps as a publishing target for the ASP.NET developer, so you can make use of concepts like Resource Groups and App Hosting Plans in the new Azure portal, right within Visual Studio.
Enable Developers with One-click Strongly-typed REST API Clients
For developers who consistently need to consume REST APIs from various vendors or services, a component of the Azure App Service – Azure API Apps – exposes metadata formats like Swagger and WADL to describe REST API endpoints. Included is a new Azure API App template that provides dynamic Swagger generation from ASP.NET Web API controllers. Additionally, there is a new consumption system in Visual Studio that provides one-click C# code generation features to make it easier than ever to consume REST APIs without needing to write repetitive HTTP calls or JSON or XML parsing. The generated client code is also supported in Portable Class Library projects, so you can use them from any platform supporting PCL, like Windows Phone 8.1 and Universal apps, as well as apps written targeting Android and iOS with Xamarin. Read more about the Azure App Service on the Microsoft blog announcing the availability of Azure App Services and Azure blog announcing Azure App Service. You can also watch recording of the webcast announcement to learn more.
Access to a Rich Marketplace of Third-party APIs
The Azure Marketplace now contains dozens of APIs for existing Microsoft services and products, and includes other APIs from partners such as Twilio, Salesforce, and Dropbox. The REST API consumption features available for custom APIs are also available for APIs installed via the Azure Management Portal’s interface, so you’ll be able to access strongly-typed clients for any of the APIs in the rapidly-growing Azure marketplace.
End-to-end Experience of Developing, Deploying, and Consuming an Azure API App
Now let’s walk-through the new Azure API Apps tools. To start, we’ll create a new Azure API App using the new project templates available in the 2.5.1 release. Then, we’ll deploy that Azure API App to the cloud. Once it’s deployed we’ll create a simple client application that will consume the deployed API App using the strongly-typed auto-generated client code.
Getting Started: the Azure API App Template
Create a new Web Application project using Visual Studio 2013 named TodoListApi.
When the One ASP.NET dialog opens, select the Azure API Apps template. The Azure API Apps template is a bare-bones Web API project, including the Azure API Apps SDK NuGet and the Swashbuckle NuGet package, which provides support for dynamic Swagger generation for Web API controllers.
Note the project readme for the API Apps template. It includes helpful links to documentation articles which will describe in greater detail how to write, deploy, debug, and consume Azure API Apps.
Add a custom model and controller that makes use of that model. The screenshot below demonstrates the project’s structure after adding a TodoItem model and TodoController class.
Next, create a new Azure API App in your Azure subscription by using the right-click > Publish feature for Web Projects.
Select the new Microsoft Azure API Apps (Preview) publish target.
The Azure API Apps publishing dialog will open. Click the New button to create a new Azure API App in your Azure subscription.
The Azure API App creation dialog will open. Now, select an existing App Service Plan and Resource Group into which your API App will be deployed. For the purpose of this demonstration, create a new App Service Plan and Resource Group using the convenient options in the dialog.
Once you click OK, the Azure API App provisioning begins. This process can take 1-2 minutes, so you will receive a warning that the provisioning process will complete. Once it completes, execute the publish action once more to publish your code to the API App instance.
The Azure App Service Activity window will reflect the process of creating the new Azure API App in your subscription. You’ll be notified when the creation process has completed.
Once the creation process completes, execute the right-click > Publish gesture on the API App project, and see that the publish settings file is resident and that the code is ready to be published to Azure.
Note: You must execute the publish process twice to ensure your code was published to the newly-provisioned site. The first publish process creates the Azure API App resources in your subscription but does not publish the code once the creation has completed, so you need to execute Publish a second time to deploy your code.
Once you click the Publish button, the API App code will be deployed to your running Azure API App instance.
Viewing the Azure API App Definition in the Azure Management Portal
Following deployment, you can open up the Azure Management Portal in your web browser and navigate to the API App you just deployed. By clicking on the API Definition button in the portal blade for the API App you’ll see the REST API endpoints for your Web API TodoController and for the default ValuesController (unless you deleted the ValuesController.cs file from the project).
Now that the Azure API App has been deployed, we’ll consume it from a Windows Desktop Console application.
One-click API App Client Code Generation in Visual Studio
API App consumption is available for most C# project types, and more will be added in future releases. For the purpose of this demo, we’ll just roll a simple Console application to call the Azure API App to verify it can be consumed. To get started consuming the API add a new project to your solution in Visual Studio.
Next, select the Console Application project template from the dialog and name the project TodoListApiClient.
Once the project is loaded in Visual Studio, right-click the project node and select the Add > Azure API App Client context menu item to open up the Azure API Apps Client generation dialog. Once it opens, select the radio button labeled Download from Microsoft Azure API App and select the TodoListApi API App you just published to Azure. Then, click the OK button. Note, you can also provide a custom namespace for the API App client code if you’d like, but the default namespace is equivalent to the base namespace of your Console Application project.
Once you click the OK button, Visual Studio will pull down the Swagger metadata exposed by your Azure API App and generate client code to make it easier for your Console Application to call your Azure API App endpoints. Once the Azure API App client code is generated, you will see it added to the Console Application project.
Now, open up the Program.cs file in the Console Application project. The generated code makes it easier than ever to use strongly-typed classes and methods to call your Azure API endpoints. The code below will reach out to the API and call its Get method, which returns the list of TodoItems from the API.
Once you hit F5 to launch the Console Application in the Visual Studio debugger, it will call the Azure API running live in the cloud, pull down the list of TodoItems, and display them in the Console window.
It’s never been easier to develop, deploy, and consume data presented via REST APIs. Download the Azure SDK for Visual Studio to try the new tooling for Azure API Apps.
Get in Touch!
Community feedback is imperative to the success of the Visual Studio Web Tools Extensions, and we value your feedback. Feedback is welcome via Send-a-Smile and Send-a-Frown UI within Visual Studio, or you can file a bug through the Visual Studio Connect site. If you have ideas on how to enhance the functionality of the Azure API Apps tools we’ve introduced, please share them on the Visual Studio UserVoice or ASP.NET UserVoice sites. The Azure API Apps resource and tools are in preview as of the 2.5.1 release. We have more to come and welcome your feedback during the preview period. Also, please check the Azure SDK for .NET Release Notes for a full list of features and known issues.
|Brady Gaster, Program Manager, Web Tools Extensions Team|
Brady Gaster helps create tools and SDKs to make it easier for developers to party in the cloud, like Azure Tools in the Web Tools Extensions for Visual Studio, the Azure Management Libraries for .NET, and the Azure Management Libraries for Java. He likes to talk about his favorite technologies – Azure, ASP.NET, Web API, SignalR in sessions and on his blog. You can find Brady on Twitter at @bradygaster when he’s not tinkering with the ASP.NET stack, Azure, devices running the .NET Micro Framework, or making music in his basement.