Managing Azure Hosted Services with the Service Management API

Exclusive offer: get 50% off this eBook here
Microsoft Windows Azure Development Cookbook

Microsoft Windows Azure Development Cookbook — Save 50%

Over 80 advanced recipes for developing scalable services with the Windows Azure platform with this Microsoft Azure book and eBook

$29.99    $15.00
by Neil Mackenzie | August 2011 | Cookbooks Enterprise Articles Microsoft

This article by Neil Mackenzie, author of Microsoft Windows Azure Development Cookbook, shows how to use the Windows Azure Service Management REST API to manage a Windows Azure hosted service. It shows how to create and upgrade deployments of a hosted service, including retrieval of the properties of a hosted service.

In this article, we will cover:

  • Creating a Windows Azure hosted service
  • Deploying an application into a hosted service
  • Upgrading an application deployed to a hosted service
  • Retrieving the properties of a hosted service

 

Microsoft Windows Azure Development Cookbook

Microsoft Windows Azure Development Cookbook

Over 80 advanced recipes for developing scalable services with the Windows Azure platform

        Read more about this book      

(For more resources on this subject, see here.)

Introduction

The Windows Azure Portal provides a convenient and easy-to-use way of managing the hosted services and storage account in a Windows Azure subscription, as well as any deployments into these hosted services. The Windows Azure Service Management REST API provides a programmatic way of managing the hosted services and storage accounts in a Windows Azure subscription, as well as any deployments into these hosted services. These techniques are complementary and, indeed, it is possible to use the Service Management API to develop an application that provides nearly all the features of the Windows Azure Portal.

The Service Management API provides almost complete control over the hosted services and storage accounts contained in a Windows Azure subscription. All operations using this API must be authenticated using an X.509 management certificate. We see how to do this in the Authenticating against the Windows Azure Service Management REST API recipe in Controlling Access in the Windows Azure Platform.

In Windows Azure, a hosted service is an administrative and security boundary for an application. A hosted service specifies a name for the application, as well as specifying a Windows Azure datacenter or affinity group into which the application is deployed. In the Creating a Windows Azure hosted service recipe, we see how to use the Service Management API to create a hosted service.

A hosted service has no features or functions until an application is deployed into it. An application is deployed by specifying a deployment slot, either production or staging, and by providing the application package containing the code, as well as the service configuration file used to configure the application. We see how to do this using the Service Management API in the Deploying an application into a hosted service recipe.

Once an application has been deployed, it probably has to be upgraded occasionally. This requires the provision of a new application package and service configuration file. We see how to do this using the Service Management API in the Upgrading an application deployed to a hosted service recipe.

A hosted service has various properties defining it as do the applications deployed into it. There could, after all, be separate applications deployed into each of the production and staging slots. In the Retrieving the properties of a hosted service recipe, we see how to use the Service Management API to get these properties.

An application deployed as a hosted service in Windows Azure can use the Service Management API to modify itself while running. Specifically, an application can autoscale by varying the number of role instances to match anticipated demand. We see how to do this in the Autoscaling with the Windows Azure Service Management REST API recipe.

We can use the Service Management API to develop our own management applications. Alternatively, we can use one of the PowerShell cmdlets libraries that have already been developed using the API. Both the Windows Azure team and Cerebrata have developed such libraries. We see how to use them in the Using the Windows Azure Platform PowerShell Cmdlets recipe.

Creating a Windows Azure hosted service

A hosted service is the administrative and security boundary for an application deployed to Windows Azure. The hosted service specifies the service name, a label, and either the Windows Azure datacenter location or the affinity group into which the application is to be deployed. These cannot be changed once the hosted service is created. The service name is the subdomain under cloudapp.net used by the application, and the label is a humanreadable name used to identify the hosted service on the Windows Azure Portal.

The Windows Azure Service Management REST API exposes a create hosted service operation. The REST endpoint for the create hosted service operation specifies the subscription ID under which the hosted service is to be created. The request requires a payload comprising an XML document containing the properties needed to define the hosted service, as well as various optional properties. The service name provided must be unique across all hosted services in Windows Azure, so there is a possibility that a valid create hosted service operation will fail with a 409 Conflict error if the provided service name is already in use. As the create hosted service operation is asynchronous, the response contains a request ID that can be passed into a get operation status operation to check the current status of the operation.

In this recipe, we will learn how to use the Service Management API to create a Windows Azure hosted service.

Getting ready

The recipes in this article use the ServiceManagementOperation utility class to invoke operations against the Windows Azure Service Management REST API. We implement this class as follows:

  1. Add a class named ServiceManagementOperation to the project.
  2. Add the following assembly reference to the project:

    System.Xml.Linq.dll

  3. Add the following using statements to the top of the class file:

    using System.Security.Cryptography.X509Certificates;
    using System.Net;
    using System.Xml.Linq;
    using System.IO;

  4. Add the following private members to the class:

    String thumbprint;
    String versionId = "2011-02-25";

  5. Add the following constructor to the class:

    public ServiceManagementOperation(String thumbprint)
    {
    this.thumbprint = thumbprint;
    }

  6. Add the following method, retrieving an X.509 certificate from the certificate store, to the class:

    private X509Certificate2 GetX509Certificate2(
    String thumbprint)
    {
    X509Certificate2 x509Certificate2 = null;
    X509Store store =
    new X509Store("My", StoreLocation.LocalMachine);
    try
    {
    store.Open(OpenFlags.ReadOnly);
    X509Certificate2Collection x509Certificate2Collection =
    store.Certificates.Find(
    X509FindType.FindByThumbprint, thumbprint, false);
    x509Certificate2 = x509Certificate2Collection[0];
    }
    finally
    {
    store.Close();
    }
    return x509Certificate2;
    }

  7. Add the following method, creating an HttpWebRequest, to the class:

    private HttpWebRequest CreateHttpWebRequest(
    Uri uri, String httpWebRequestMethod)
    {
    X509Certificate2 x509Certificate2 =
    GetX509Certificate2(thumbprint);
    HttpWebRequest httpWebRequest =
    (HttpWebRequest)HttpWebRequest.Create(uri);
    httpWebRequest.Method = httpWebRequestMethod;
    httpWebRequest.Headers.Add("x-ms-version", versionId);
    httpWebRequest.ClientCertificates.Add(x509Certificate2);
    httpWebRequest.ContentType = "application/xml";
    return httpWebRequest;
    }

  8. Add the following method, invoking a GET operation on the Service Management API, to the class:

    public XDocument Invoke(String uri)
    {
    XDocument responsePayload;
    Uri operationUri = new Uri(uri);
    HttpWebRequest httpWebRequest =
    CreateHttpWebRequest(operationUri, "GET");
    using (HttpWebResponse response =
    (HttpWebResponse)httpWebRequest.GetResponse())
    {
    Stream responseStream = response.GetResponseStream();
    responsePayload = XDocument.Load(responseStream);
    }
    return responsePayload;
    }

  9. Add the following method, invoking a POST operation on the Service Management API, to the class:

    public String Invoke(String uri, XDocument payload)
    {
    Uri operationUri = new Uri(uri);
    HttpWebRequest httpWebRequest =
    CreateHttpWebRequest(operationUri, "POST");
    using (Stream requestStream =
    httpWebRequest.GetRequestStream())
    {
    using (StreamWriter streamWriter =
    new StreamWriter(requestStream,
    System.Text.UTF8Encoding.UTF8))
    {
    payload.Save(streamWriter,
    SaveOptions.DisableFormatting);
    }
    }

    String requestId;
    using (HttpWebResponse response =
    (HttpWebResponse)httpWebRequest.GetResponse())
    {
    requestId = response.Headers["x-ms-request-id"];
    }
    return requestId;
    }

How it works...

In steps 1 through 3, we set up the class. In step 4, we add a version ID for service management operations. Note that Microsoft periodically releases new operations for which it provides a new version ID, which is usually applicable for operations added earlier. In step 4, we also add a private member for the X.509 certificate thumbprint that we initialize in the constructor we add in step 5.

In step 6, we open the Personal (My) certificate store on the local machine level and retrieve an X.509 certificate identified by thumbprint. If necessary, we can specify the current user level, instead of the local machine level, by using StoreLocation.CurrentUser instead of StoreLocation.LocalMachine.

In step 7, we create an HttpWebRequest with the desired HTTP method type, and add the X.509 certificate to it. We also add various headers including the required x-ms-version.

In step 8, we invoke a GET request against the Service Management API and load the response into an XML document which we then return. In step 9, we write an XML document, containing the payload, into the request stream for an HttpWebRequest and then invoke a POST request against the Service Management API. We extract the request ID from the response and return it.

How to do it...

We are now going to construct the payload required for the create hosted service operation, and then use it when we invoke the operation against the Windows Azure Service Management REST API. We do this as follows:

  1. Add a new class named CreateHostedServiceExample to the WPF project.
  2. If necessary, add the following assembly reference to the project:

    System.Xml.Linq.dll

  3. Add the following using statement to the top of the class file:

    using System.Xml.Linq;

  4. Add the following private members to the class:

    XNamespace wa =
    "http://schemas.microsoft.com/windowsazure";
    String createHostedServiceFormat =
    "https://management.core.windows.net/{0}/services/hostedservices";

  5. Add the following method, creating a base-64 encoded string, to the class:

    private String ConvertToBase64String(String value)
    {
    Byte[] bytes = System.Text.Encoding.UTF8.GetBytes(value);
    String base64String = Convert.ToBase64String(bytes);
    return base64String;
    }

  6. Add the following method, creating the payload, to the class:

    private XDocument CreatePayload(
    String serviceName, String label, String description,
    String location, String affinityGroup)
    {
    String base64LabelName = ConvertToBase64String(label);

    XElement xServiceName =
    new XElement(wa + "ServiceName", serviceName);
    XElement xLabel =
    new XElement(wa + "Label", base64LabelName);
    XElement xDescription =
    new XElement(wa + "Description", description);
    XElement xLocation =
    new XElement(wa + "Location", location);
    XElement xAffinityGroup =
    new XElement(wa + "AffinityGroup", affinityGroup);
    XElement createHostedService =
    new XElement(wa +"CreateHostedService");

    createHostedService.Add(xServiceName);
    createHostedService.Add(xLabel);
    createHostedService.Add(xDescription);
    createHostedService.Add(xLocation);
    //createHostedService.Add(xAffinityGroup);
    XDocument payload = new XDocument();
    payload.Add(createHostedService);
    payload.Declaration =
    new XDeclaration("1.0", "UTF-8", "no");
    return payload;
    }

  7. Add the following method, invoking the create hosted service operation, to the class:

    private String CreateHostedService(String subscriptionId,
    String thumbprint, String serviceName, String label,
    String description, String location, String affinityGroup)
    {
    String uri =
    String.Format(createHostedServiceFormat, subscriptionId);

    XDocument payload = CreatePayload(serviceName, label,
    description, location, affinityGroup);
    ServiceManagementOperation operation =
    new ServiceManagementOperation(thumbprint);
    String requestId = operation.Invoke(uri, payload);
    return requestId;
    }

  8. Add the following method, invoking the methods added earlier, to the class:

    public static void UseCreateHostedServiceExample()
    {
    String subscriptionId = "{SUBSCRIPTION_ID}";
    String thumbprint = "{THUMBPRINT}";
    String serviceName = "{SERVICE_NAME}";
    String label = "{LABEL}";
    String description = "Newly created service";
    String location = "{LOCATION}";
    String affinityGroup = "{AFFINITY_GROUP}";
    CreateHostedServiceExample example =
    new CreateHostedServiceExample();
    String requestId = example.CreateHostedService(
    subscriptionId, thumbprint, serviceName, label,
    description, location, affinityGroup);
    }

How it works...

In steps 1 through 3, we set up the class. In step 4, we add private members to define the XML namespace used in creating the payload and the String format used in generating the endpoint for the create hosted service operation. In step 5, we add a helper method to create a base-64 encoded copy of a String.

We create the payload in step 6 by creating an XElement instance for each of the required and optional properties, as well as the root element. We add each of these elements to the root element and then add this to an XML document. Note that we do not add an AffinityGroup element because we provide a Location element and only one of them should be provided.

In step 7, we use the ServiceManagementOperation utility class , described in the Getting ready section, to invoke the create hosted service operation on the Service Management API. The Invoke() method creates an HttpWebRequest, adds the required X.509 certificate and the payload, and then sends the request to the create hosted services endpoint. It then parses the response to retrieve the request ID which can be used to check the status of the asynchronous create hosted services operation.

In step 8, we add a method that invokes the methods added earlier. We need to provide the subscription ID for the Windows Azure subscription, a globally unique service name for the hosted service, and a label used to identify the hosted service in the Windows Azure Portal. The location must be one of the official location names for a Windows Azure datacenter, such as North Central US. Alternatively, we can provide the GUID identifier of an existing affinity group and swap the commenting out in the code, adding the Location and AffinityGroup elements in step 6. We see how to retrieve the list of locations and affinity groups in the Locations and affinity groups section of this recipe.

There's more...

Each Windows Azure subscription can create six hosted services. This is a soft limit that can be raised by requesting a quota increase from Windows Azure Support at the following URL:

http://www.microsoft.com/windowsazure/support/

There are also soft limits on the number of cores per subscription (20) and the number of Windows Azure storage accounts per subscription (5). These limits can also be increased by request to Windows Azure Support.

Locations and affinity groups

The list of locations and affinity groups can be retrieved using the list locations and list affinity groups operations respectively in the Service Management API. We see how to do this in the Using the Windows Azure Platform PowerShell Cmdlets recipe.

As of this writing, the locations are:

  • Anywhere US
  • South Central US
  • North Central US
  • Anywhere Europe
  • North Europe
  • West Europe
  • Anywhere Asia
  • Southeast Asia
  • East Asia

The affinity groups are specific to a subscription.

Microsoft Windows Azure Development Cookbook Over 80 advanced recipes for developing scalable services with the Windows Azure platform with this Microsoft Azure book and eBook
Published: August 2011
eBook Price: $29.99
Book Price: $49.99
See more
Select your format and quantity:
        Read more about this book      

(For more resources on this subject, see here.)

Deploying an application into a hosted service

An application is deployed into a Windows Azure hosted service to provide its features and functionality. The deployment comprises the package containing the code to be deployed into the instances of the roles in the application, as well as the service configuration file specifying the configuration for the application. Each deployment is into either the production or staging slot of the hosted service. The result of a deployment is the creation of all the roles and instances specified in the service configuration file. By default, these instances are initially in the stopped state.

The Windows Azure Service Management REST API exposes a create deployment operation. The REST endpoint for the create deployment operation specifies the subscription ID, the name of the hosted service, and the deployment slot into which the application is to be deployed. The operation requires a payload comprising an XML document specifying the Windows Azure blob containing the application package and a base-64 encoded version of the service configuration file. Each deployment has a name used to distinguish it from other deployments into the same-hosted service. As the create deployment operation is asynchronous, the response contains a request ID that can be passed into a get operation status operation to check the current status of the operation.

In this recipe, we will learn how to use the Windows Azure Service Management REST API to deploy an application into a hosted service.

How to do it...

We are going to construct the payload required for the create deployment operation and then use it when we invoke the operation against the Windows Azure Service Management REST API. Then, we invoke a get operation status operation to retrieve the status of the asynchronous create deployment operation. We do this as follows:

  1. Add a new class named CreateDeploymentExample to the project.
  2. If necessary, add the following assembly reference to the project:

    System.Xml.Linq.dll

  3. Add the following using statements to the top of the class file:

    using System.Xml.Linq;
    using System.IO;

  4. Add the following private members to the class:

    XNamespace wa = "http://schemas.microsoft.com/windowsazure";
    String createDeploymentFormat =
    "https://management.core.windows.net/{0}/services/
    hostedservices/{1}/deploymentslots/{2}";
    String getOperationStatusFormat =
    "https://management.core.windows.net/{0}/operations/{1}";

  5. Add the following method, creating a base-64 encoded String, to the class:

    private String ConvertToBase64String(String value)
    {
    Byte[] bytes = System.Text.Encoding.UTF8.GetBytes(value);
    String base64String = Convert.ToBase64String(bytes);
    return base64String;
    }

  6. Add the following method, creating the payload, to the class:

    private XDocument CreatePayload(
    String deploymentName, String packageUrl,
    String pathToConfigurationFile, String label)
    {
    String configurationFile =
    File.ReadAllText(pathToConfigurationFile);
    String base64ConfigurationFile =
    ConvertToBase64String(configurationFile);

    String base64Label = ConvertToBase64String(label);

    XElement xName = new XElement(wa + "Name", deploymentName);
    XElement xPackageUrl =
    new XElement(wa + "PackageUrl", packageUrl);
    XElement xLabel = new XElement(wa + "Label", base64Label);
    XElement xConfiguration =
    new XElement(wa+"Configuration", base64ConfigurationFile);
    XElement xStartDeployment =
    new XElement(wa + "StartDeployment", "true");
    XElement xTreatWarningsAsError =
    new XElement(wa + "TreatWarningsAsError", "false");
    XElement createDeployment =
    new XElement(wa + "CreateDeployment");

    createDeployment.Add(xName);
    createDeployment.Add(xPackageUrl);
    createDeployment.Add(xLabel);
    createDeployment.Add(xConfiguration);
    createDeployment.Add(xStartDeployment);
    createDeployment.Add(xTreatWarningsAsError);

    XDocument payload = new XDocument();
    payload.Add(createDeployment);
    payload.Declaration =
    new XDeclaration("1.0", "UTF-8", "no");

    return payload;
    }

  7. Add the following method, invoking the create deployment operation, to the class:

    private String CreateDeployment( String subscriptionId,
    String thumbprint, String serviceName,
    String deploymentName, String deploymentSlot,
    String packageUrl, String pathToConfigurationFile,
    String label)
    {
    String uri = String.Format(createDeploymentFormat,
    subscriptionId, serviceName, deploymentSlot);

    XDocument payload = CreatePayload( deploymentName,
    packageUrl, pathToConfigurationFile, label);
    ServiceManagementOperation operation =
    new ServiceManagementOperation(thumbprint);
    String requestId = operation.Invoke(uri, payload);
    return requestId;
    }

  8. Add the following method, retrieving the operation status, to the class:

    public String GetOperationStatus(
    String subscriptionId, String thumbprint, String requestId)
    {
    String uri = String.Format(
    getOperationStatusFormat, subscriptionId, requestId);

    ServiceManagementOperation operation =
    new ServiceManagementOperation(thumbprint);
    XDocument operationStatus = operation.Invoke(uri);

    String status = operationStatus.Element(
    wa + "Operation").Element(wa + "Status").Value;
    return status;
    }

  9. Add the following method, invoking the methods added earlier, to the class:

    public static void UseCreateDeploymentExample()
    {
    String subscriptionId = "{SUBSCRIPTION_ID}";
    String thumbprint = "{THUMBPRINT}";
    String serviceName = "{SERVICE_NAME}";
    String deploymentName = "{DEPLOYMENT_NAME}";
    String deploymentSlot = "{SLOT_NAME}";
    String packageUrl = "{PACKAGE_URL}";
    String pathToConfigurationFile =
    "{CONFIGURATION_FILE_PATH}";
    String label = "{DEPLOYMENT_LABEL}";

    CreateDeploymentExample example =
    new CreateDeploymentExample();
    String requestId = example.CreateDeployment(
    subscriptionId, serviceName, deploymentName,
    deploymentSlot, packageUrl, pathToConfigurationFile,
    label);
    String operationStatus =
    example.GetOperationStatus(subscriptionId, thumbprint,
    requestId);
    }

How it works...

In steps 1 through 3, we set up the class. In step 4, we add private members to define the XML namespace used in creating the payload and the String formats used in generating the endpoints for the create deployment and get operation status operations. In step 5, we add a helper method to create a base-64 encoded copy of a String.

We create the payload in step 6 by creating an XElement instance for each of the required and optional properties, as well as the root element. We load the service configuration file from disk and add a base-64 encoded version of its content to the Configuration element. We add each of these elements to the root element and then add this to an XML document. We specify that the deployed application should be started and that warnings should not be treated as errors.

In step 7, we use the ServiceManagementOperation utility class, described in the Getting ready section of the Creating a Windows Azure hosted service recipe in this article, to invoke the create deployment operation on the Service Management API. The Invoke() method creates an HttpWebRequest, adds the required X.509 certificate and the payload, and then sends the request to the create deployment endpoint. It then parses the response to retrieve the request Id. In step 8, we again use the ServiceManagementOperation utility class to invoke the get operation status operation. We parameterize this operation with the request ID, so that we can find the current status of the asynchronous create deployment operation.

In step 9, we add a method that invokes the methods added earlier. We need to provide the subscription ID for the Windows Azure subscription, the name of the hosted service, a name identifying this deployment, the deployment slot (production or staging) in which the deployment is created, as well as a label identifying this deployment in the Windows Azure Portal. We have to specify the complete URL to the application package, which is contained in a blob hosted by a storage account under the Windows Azure subscription. We also need to provide the file-system path to the service configuration file for the application.

There's more...

The Windows Azure Service Management REST API exposes a get operation status operation that can be used to retrieve the current status of an asynchronous operation using the API. The REST endpoint for the get operation status operation specifies the subscription ID and the request ID for the asynchronous operation. The request has no payload. The response contains an XML document specifying the current status of the specified operation, as well as any error information.

Microsoft Windows Azure Development Cookbook Over 80 advanced recipes for developing scalable services with the Windows Azure platform with this Microsoft Azure book and eBook
Published: August 2011
eBook Price: $29.99
Book Price: $49.99
See more
Select your format and quantity:
        Read more about this book      

(For more resources on this subject, see here.)

Upgrading an application deployed to a hosted service

An application deployed into a Windows Azure hosted service can be upgraded using the Windows Azure Service Management REST API. The upgrade includes both the application package and the service configuration file. Although the entire application package must be uploaded, it is possible to specify that only a single role be upgraded.

The Service Management API exposes an upgrade deployment operation. The REST endpoint for the upgrade deployment operation specifies the subscription ID, the name of the hosted service, and the slot of the application to be deployed. The operation requires a payload comprising an XML document specifying the Windows Azure blob containing the application package and a base-64 encoded version of the service configuration file. Each deployment upgrade has a name used to distinguish it from other deployments into the same-hosted service. As the upgrade deployment operation is asynchronous, the response contains a request ID that can be passed into a get operation status operation to check the current status of the operation.

In this recipe, we will learn how to use the Windows Azure Service Management REST API to upgrade an application in a hosted service.

How to do it...

We are going to construct the payload required for the upgrade deployment operation and then use it when we invoke the operation against the Windows Azure Service Management REST API. We do this as follows:

  1. Add a new class named UpgradeDeploymentExample to the project.
  2. If necessary, add the following assembly reference to the project:

    System.Xml.Linq.dll

  3. Add the following using statements to the top of the class file:

    using System.Xml.Linq;
    using System.IO;

  4. Add the following private members to the class:

    XNamespace wa = "http://schemas.microsoft.com/windowsazure";
    String upgradeDeploymentFormat =
    "https://management.core.windows.net/{0}/services/hostedservices/
    {1}/deploymentslots/{2}/?comp=upgrade";

  5. Add the following method, creating a base-64 encoded String, to the class:

    private String ConvertToBase64String(String value)
    {
    Byte[] bytes = System.Text.Encoding.UTF8.GetBytes(value);
    String base64String = Convert.ToBase64String(bytes);
    return base64String;
    }

  6. Add the following method, creating the payload, to the class:

    private XDocument CreatePayload(
    String roleName, String packageUrl,
    String pathToConfigurationFile, String label)
    {
    String configurationFile =
    File.ReadAllText(pathToConfigurationFile);
    String base64ConfigurationFile =
    ConvertToBase64String(configurationFile);

    String base64Label = ConvertToBase64String(label);

    XElement xMode = new XElement(wa + "Mode", "auto");
    XElement xPackageUrl =
    new XElement(wa + "PackageUrl", packageUrl);
    XElement xConfiguration = new XElement(
    wa + "Configuration", base64ConfigurationFile);
    XElement xLabel = new XElement(wa + "Label", base64Label);
    XElement xRoleToUpgrade =
    new XElement(wa + "RoleToUpgrade", roleName);
    XElement upgradeDeployment =
    new XElement(wa + "UpgradeDeployment");

    upgradeDeployment.Add(xMode);
    upgradeDeployment.Add(xPackageUrl);
    upgradeDeployment.Add(xConfiguration);
    upgradeDeployment.Add(xLabel);
    upgradeDeployment.Add(xRoleToUpgrade);

    XDocument payload = new XDocument();
    payload.Add(upgradeDeployment);
    payload.Declaration =
    new XDeclaration("1.0", "UTF-8", "no");

    return payload;
    }

  7. Add the following method, invoking the upgrade deployment operation , to the class:

    private String UpgradeDeployment(String subscriptionId,
    String thumbprint, String serviceName,
    String deploymentSlot, String roleName, String packageUrl,
    String pathToConfigurationFile, String label )
    {
    String uri = String.Format(upgradeDeploymentFormat,
    subscriptionId, serviceName, deploymentSlot);

    XDocument payload = CreatePayload(roleName, packageUrl,
    pathToConfigurationFile, label);
    ServiceManagementOperation operation =
    new ServiceManagementOperation(thumbprint);
    String requestId = operation.Invoke(uri, payload);
    return requestId;
    }

  8. Add the following method, invoking the methods added earlier, to the class:

    public static void UseUpgradeDeploymentExample()
    {
    String subscriptionId = "{SUBSCRIPTION_ID}";
    String thumbprint = "{THUMBPRINT}";
    String serviceName = "{SERVICE_NAME}";
    String deploymentSlot = "{SLOT_NAME}";
    String roleName = "{ROLE_NAME}";
    String packageUrl = "{PACKAGE_URL}";
    String pathToConfigurationFile =
    "{CONFIGURATION_FILE_PATH}";
    String label = "{DEPLOYMENT_LABEL}";

    UpgradeDeploymentExample example =
    new UpgradeDeploymentExample();
    String requestId = example.UpgradeDeployment(
    subscriptionId, thumbprint, serviceName, deploymentSlot,
    roleName, packageUrl, pathToConfigurationFile, label );
    }

How it works...

In steps 1 through 3, we set up the class. In step 4, we add private members to define the XML namespace used in creating the payload and the String formats used in generating the endpoints for the upgrade deployment operation. In step 5, we add a helper method to create a base-64 encoded copy of a String.

We create the payload in step 6 by creating an XElement instance for each of the required and optional properties, as well as the root element. We load the service configuration file from disk and add a base-64 encoded version of its content to the Configuration element. We add each of these elements to the root element and then add this to an XML document. We specify that the deployed application should be started and that warnings should not be treated as errors. We also specify which role in the package should be upgraded.

In step 7, we use the ServiceManagementOperation utility class , described in the Getting ready section of the Creating a Windows Azure hosted service recipe, to invoke the upgrade deployment operation on the Windows Azure Service Management REST API. The Invoke() method creates an HttpWebRequest, adds the required X.509 certificate and the payload, and then sends the request to the upgrade deployment endpoint. It then parses the response to retrieve the request ID.

In step 8, we add a method that invokes the methods added earlier. We need to provide the subscription ID for the Windows Azure subscription, the name of the hosted service, the name of the role to upgrade, a name identifying this deployment, the deployment slot (production or staging) of the deployment to be upgraded, as well as a label used to identify this upgraded deployment in the Windows Azure Portal. We have to specify the complete URL to the application package, which is contained in a blob hosted by a storage account under the subscription. We also need to provide the filesystem path to the service configuration file for the application.

Retrieving the properties of a hosted service

The Windows Azure Service Management REST API exposes a get hosted service properties operation that can be used to retrieve the properties of a Windows Azure hosted service and any deployments to it. The REST endpoint for the get hosted service properties operation specifies the subscription ID and the name of the hosted service. The URL can be parameterized to specify that information about all deployments in the hosted service should also be returned. The request has no payload. The response contains an XML document comprising the properties of the hosted service, as well as information on the current status of all deployments in the hosted service.

In this recipe, we will learn how to use the Windows Azure Service Management REST API to retrieve the full set of properties for a hosted service.

How to do it...

We are going to invoke the get hosted service properties operation of the Windows Azure Storage Management REST API to retrieve the deployment status, as well as the role count and the instance count of a hosted service. We do this as follows:

  1. Add a new class named GetHostedServicePropertiesExample to the project.
  2. If necessary, add the following assembly reference to the project:

    System.Xml.Linq.dll

  3. Add the following using statement to the top of the class file:

    using System.Xml.Linq;

  4. Add the following private members to the class:

    XNamespace wa = "http://schemas.microsoft.com/windowsazure";
    String serviceOperationFormat =
    "https://management.core.windows.net/{0}/
    services/hostedservices/{1}?embed-detail=true";

  5. Add the following method, retrieving the desired properties, to the class:

    private void GetHostedServiceProperties(
    String subscriptionId, String thumbprint,
    String serviceName)
    {
    String uri = String.Format(
    serviceOperationFormat, subscriptionId, serviceName);
    ServiceManagementOperation operation =
    new ServiceManagementOperation(thumbprint);
    XDocument hostedServiceProperties = operation.Invoke(uri);
    var deploymentInformation =
    (from t in hostedServiceProperties.Elements()
    select new
    {
    DeploymentStatus = (
    from deployments in
    t.Descendants(wa + "Deployments")
    select deployments.Element(
    wa + "Deployment").Element(
    wa + "Status").Value).First(),
    RoleCount = (
    from roles in t.Descendants(wa + "RoleList")
    select roles.Elements()).Count(),
    InstanceCount = (
    from instances in
    t.Descendants(wa +"RoleInstanceList")
    select instances.Elements()).Count()
    }).First();

    String deploymentStatus =
    deploymentInformation.DeploymentStatus;
    Int32 roleCount = deploymentInformation.RoleCount;
    Int32 instanceCount = deploymentInformation.InstanceCount;
    }

  6. Add the following method, using the method we added previously, to the class:

    public static void UseGetHostedServicePropertiesExample()
    {
    String subscriptionId = "{SUBSCRIPTION_ID}";
    String thumbprint = "{THUMBPRINT}";
    String serviceName = "{SERVICE_NAME}";
    GetHostedServicePropertiesExample example =
    new GetHostedServicePropertiesExample();

    example.GetHostedServiceProperties(
    subscriptionId, thumbprint, serviceName);
    }

How it works...

In steps 1 through 3, we set up the class. In step 4, we add private members to define the XML namespace used in processing the response and the String format used in generating the endpoint for the get hosted service properties operation. Note that we append a parameter to this endpoint indicating that we want the complete list of properties for the hosted service.

In step 5, we use the ServiceManagementOperation utility class , described in the Creating a Windows Azure hosted service recipe, to invoke the get hosted service properties operation on the Service Management API. The Invoke() method creates an HttpWebRequest, adds the required X.509 certificate, and then sends the request to the get hosted services properties endpoint. It then loads the response into an XML document and returns it. We then invoke a LINQ-to-XML query on the document to retrieve the deployment status, as well as the number of roles and instances in the hosted service. This query fails if there is no application deployed into the hosted service.

In step 6, we add a method that invokes the methods added earlier. We need to provide the subscription ID for the Windows Azure subscription, the thumbprint of a management certificate, and the service name for the hosted service for which we want the properties.

There's more...

The Windows Azure Service Management REST API exposes an operation named list subscription operations that can be used to retrieve information on the operations performed on the subscription. The REST endpoint for the list subscription operations operation specifies the subscription ID. It can be parameterized by a timeframe used to filter the list of operations retrieved. The request has no payload. The response contains an XML document describing the operations performed on the subscription in the specified timeframe.

Summary

This article showed how to use the Windows Azure Service Management REST API to manage a Windows Azure hosted service. It showed how to create and upgrade deployments of a hosted service, including retrieval of the properties of a hosted service.


Further resources on this subject:


About the Author :


Neil Mackenzie

Neil Mackenzie has worked with computers for nearly three decades. He started his computer career doing large-scale numerical simulations for scientific research and business planning. Since then, he has been involved primarily in healthcare software, developing electronic medical records systems. He has been using Windows Azure since PDC 2008 and has used nearly all parts of the Windows Azure platform – including those that no longer exist. Neil is very active in the online Windows Azure community – in particular, helping to solve many of the questions raised in the MSDN Windows Azure Forums. He is a Microsoft MVP for Windows Azure.

Books From Packt


Microsoft SQL Azure Enterprise Application Development
Microsoft SQL Azure Enterprise Application Development

Getting Started with Microsoft Application Virtualization 4.6
Getting Started with Microsoft Application Virtualization 4.6

Microsoft Azure: Enterprise Application Development
Microsoft Azure: Enterprise Application Development

Applied Architecture Patterns on the Microsoft Platform
Applied Architecture Patterns on the Microsoft Platform

Microsoft Windows Communication Foundation 4.0 Cookbook for Developing SOA Applications
Microsoft Windows Communication Foundation 4.0 Cookbook for Developing SOA Applications

Microsoft Silverlight 4 and Windows Azure Enterprise Integration: RAW
Microsoft Silverlight 4 and Windows Azure Enterprise Integration: RAW

Microsoft SharePoint 2010 and Windows PowerShell 2.0: Expert Cookbook
Microsoft SharePoint 2010 and Windows PowerShell 2.0: Expert Cookbook

Least Privilege Security for Windows 7, Vista and XP
Least Privilege Security for Windows 7, Vista and XP


Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software