Exercise 2: Using PowerShell to Manage Windows Azure Applications

Typically, during its lifetime, an application undergoes changes that require it to be re-deployed. In the previous exercise, you saw how to use the Windows Azure Management Portal to deploy applications. As an alternative, the Service Management API provides programmatic access to much of the functionality available through the Management Portal. Using the Service Management API, you can manage your storage accounts and hosted services, your service deployments, and your affinity groups.

The Windows Azure Service Management PowerShell Cmdlets wrap the Windows Azure Service Management API. These cmdlets make it simple to automate the deployment, upgrade, and scaling of your Windows Azure application. By pipelining commands, you compose complex scripts that use the output of one command as the input to another.

In this exercise, you will learn how to deploy and upgrade a Windows Azure application using the Azure Services Management Cmdlets.

Task 1 – Generating a Self-Signed Certificate (Optional)

To ensure that access to the Service Management API is secure, you must first associate a certificate with your subscription. The management service uses the certificate to authenticate requests. You can use a self-signed certificate or one signed by a certification authority. Any valid X.509 v3 is suitable as long as its key length is at least 2048 bits.

In this task, you generate a certificate that you can upload to the Windows Azure Management Portal. This step is optional if you already have a certificate signed by a certificate authority.

Open a Visual Studio Command Prompt as administrator from Start | All Programs | Microsoft Visual Studio 2010 | Visual Studio Tools | Visual Studio Command Prompt (2010) by right-clicking the Visual Studio 2010 Command Prompt shortcut and choosing Run as administrator.
Change the current directory to the location where you wish to store your certificate file.
At the prompt, type the following command to generate a local certificate file.
Visual Studio Command Prompt
```
makecert -r -pe -n "CN=AzureMgmt" -a sha1 -len 2048 -ss My "AzureMgmt.cer"
```
Note:
This command creates a new self-signed certificate with a key length of 2048 bits, writes it to the "AzureMgmt.cer" file in the current directory and saves it to the My certificate store for the current user.

Task 2 – Preparing the Windows Azure Account

To use the Windows Azure Service Management API, you need to upload the certificate to your Windows Azure account to provide the required authentication. In addition, the management API, and the PowerShell cmdlets that wrap it, require you to provide several pieces of information, including the name of your service, the thumbprint of the certificate, and the subscription ID of your Windows Azure account.

In this task, you upload the certificate to your Windows Azure Account and obtain the required information, including the certificate thumbprint and the subscription ID.

Navigate to https://windows.azure.com using a Web browser and sign in using your Windows Live ID.
Click Hosted Services, Storage Accounts & CDN, and then click on Management Certificates on the left pane. Click the Add Certificate button on the Ribbon.
Figure 35
Managing API certificates in the Windows Azure Management Portal
Select your subscription and upload the new certificate from your local storage. To do this, select Browse, locate the certificate file in your local disk and then click OK.
Figure 36
Adding a new Management Certificate
Note:
The Service Management API accepts any valid X.509 v3 certificate for authentication purposes provided its key length is at least 2048 bits. You can use the self-signed certificate you created in the previous task or one signed by a certificate authority.
If you submit a self-signed certificate immediately after you generate it, the Windows Azure Management Portal could reject it due to timing differences with your computer if the server’s time is ahead of the Valid From date of the certificate. If you receive a ”Certificate is not yet valid” error when you upload the certificate, you can either wait a few minutes to account for the time skew and re-submit the certificate or use makecert to generate a new certificate that specifies a validity period with a start date that is in the past.
Make a note of the value shown in the Thumbprint for the certificate that you just installed. In addition, make a note of the value shown in Subscription Id for the Subscription where you installed the certificate. You can do this by clicking the Subscription root node.
Figure 37
Certificate Properties
Figure 38
Subscription Properties
Select Hosted Services on the left pane. Click on the MyTodo service v1.0. You can retrieve the service name from the DNS name link shown in Properties, which has the format http://<SERVICE_NAME>.cloudapp.net.
Figure 39
Retrieving the DNS name of the hosted service
Note:
You will use the certificate Thumbprint, account Subscription ID, and Service Name in the next task, when you deploy the service package.
You may want to copy these values and paste them into Notepad for easy access.

Task 3 – Uploading a Service Package Using Windows PowerShell

In the previous exercise, you uploaded the service package for the myTODO application using the Windows Azure Management Portal. In this task, you deploy the package using the Windows Azure Service Management PowerShell cmdlets instead.

If it is not already open, launch Microsoft Visual Studio 2010 as administrator. To do this, in Start | All Programs | Microsoft Visual Studio 2010, right-click the Microsoft Visual Studio 2010 shortcut and choose Run as administrator.
In the File menu, choose Open and then Project/Solution. In the Open Project dialog, browse to Ex2-DeployingWithPowerShell\Begin in the Source folder of the lab, select MyTodo.sln in the folder for the language of your preference (Visual C# or Visual Basic) and click Open.
Configure the storage account connection strings. To do this, expand the Roles node in the MyTodo project and double-click the MyTodo.WebUX role. In the role properties window, select the Settings tab, select the DataConnectionString setting, ensure that the Type is set to ConnectionString, and then click the button labeled with an ellipsis.
Figure 40
Defining storage account connection settings
In the Storage Connection String dialog, choose the Enter storage credentials option. Complete your storage Account Name and storage Account Key and click OK.
Figure 41
Configuring the storage account name and account key
Note:
This information is available in the Summary section of your storage account in the Windows Azure Management Portal. You used the same settings in Exercise 1, when you deployed and configured the application. In that instance, because you were running the application in Windows Azure, you updated the configuration at the Management Portal.
Repeat the previous steps to configure the Microsoft.WindowsAzure.Plugins.Diagnostics.ConnectionString setting using the same account information.
To create a service package, right-click the cloud service project and select Package. In the Package Windows Azure Application dialog, click Package and then wait until Visual Studio creates it. Once the package is ready, Visual Studio opens a window showing the folder that contains the generated files. Close the window after you see the package.
Open a Windows PowerShell command prompt. On Windows Vista, Windows Server 2008, and later versions of Windows, in the Start menu, open All Programs | Accessories | Windows PowerShell, and then select Windows PowerShell. On Windows XP and Windows Server 2003, in the Start menu, open Programs | Accessories | Windows PowerShell, and then select Windows PowerShell.
At the PowerShell prompt, enter the following command to add support for the Azure Services Management cmdlets to the current session.
PowerShell Console
```
Add-PSSnapin AzureManagementToolsSnapIn
```
Change the current directory to the location where you generated the service package for the myTODO application in Step 6.

Next, enter the command shown below. Use the following command line arguments ensuring that you replace the parameter placeholders with the settings that apply to your service account, which you determined in Task 1 of this exercise.

PowerShell Console

New-Deployment -serviceName <YOUR_SERVICE_NAME_LOWER_CASE> -subscriptionId <YOUR_SUBSCRIPTION_ID> -certificate (get-item cert:\CurrentUser\MY\<YOUR_CERTIFICATE_THUMBPRINT>) -slot staging –package <PACKAGE_LOCATION> -configuration <CONFIGURATION_LOCATION> -label "v2.0" –storageServiceName <YOUR_STORAGE_SERVICE_NAME_LOWER_CASE>

<YOUR_SERVICE_NAME_LOWER_CASE>	The service name chosen when configuring the hosted service URL in Exercise 1, not its Service Label.
<YOUR_SUBSCRIPTION_ID>	The subscription ID of the Windows Azure account where the service will be deployed.
<YOUR_CERTIFICATE_THUMBPRINT>	The thumbprint value (in upper case) for the certificate uploaded previously.
< PACKAGE_LOCATION>	A path to a local file or the URL of the blob in Azure Storage that contains the service package.
< CONFIGURATION_LOCATION>	A path to a local file or the public URL of the blob that contains the service configuration file.
<YOUR_STORAGE_SERVICE_NAME_LOWER_CASE>	The storage account name.

Note:

The command shown above uses the New-Deployment cmdlet to upload a service package and create a new deployment in the staging environment. It assigns a "v2.0" label to identify this deployment.

Note that the certificate parameter expects a certificate object. In order to retrieve the required certificate, you can use get-item and the PowerShell certificate provider to obtain the certificate given its thumbprint value. Be aware that you need to specify the thumbprint in upper case for this method to succeed.

Note:

Important: The New-Deployment cmdlet assumes that the compute service and storage service names are the same. If this is not the case, specify an additional parameter -StorageServicename <YOUR_SERVICE_NAME_LOWER_CASE>, replacing the placeholder with the name of the storage service name.

For example, to deploy a hosted service named “yournametodo”, using an account with a subscription ID of 12abb234-45c9-4b37-8179-e7d88617cb5e, a certificate thumbprint 6062B026CF12FE6CD1E3A2CE22893E5CD1DA59C7, for a package named MyTodo.cspkg and a configuration file named ServiceConfiguration.cscfg stored in the current directory, and to assign this deployment a label v2.0, use the following command.

Figure 42

New-Deployment command line

Press ENTER to execute the command. Because New-Deployment is an asynchronous operation, the command returns immediately. Meanwhile, the operation continues in the background.
Figure 43
Deploying a new service package to Windows Azure using PowerShell
In the Windows Azure Management Portal, open the Summary page and notice how the deployment for the staging environment shows its status with the message "Updating deployment..." in the UI. It may take a few seconds for the service status to refresh. Wait for the deployment operation to complete and display the status as Stopped.
Note:
Normally, you will not use the management portal to view the status and determine the outcome of your deployment operations. Here, it is shown to highlight the fact that you can use the management API to execute the same operations that are available in the management portal. In the next task, you will see how to use a cmdlet to wait for the operation to complete and retrieve its status.
Keep Microsoft Visual Studio and the PowerShell console open. You will need them for the next task.

Task 4 – Upgrading a Deployment Using Windows PowerShell

In this task, you use the Windows Azure Service Management PowerShell cmdlets to upgrade an existing deployment. First, you change the original solution by making minor changes to its source code to produce an updated version of the application. Next, you build the application and create a new service package that contains the updated binaries. Finally, using the management cmdlets, you re-deploy the package to Windows Azure.

Go back to Microsoft Visual Studio.
Open the master page of the application for editing. To do this, in Solution Explorer, double-click Site.Master in the Views\Shared folder of the MyTodo.WebUx project. Switch to source mode.

Insert a new caption in the footer area of the page. Go to the bottom of the master page and update the copyright notice with the text “(Deployed with the PowerShell CmdLets)” as shown below.

HTML

...

    </div>

    <div id="footer">

      <hr />

      <p class="copyright">

         &copy; 2009 Microsoft Corporation.  All rights reserved. (Deployed with the PowerShell CmdLets)</p>

      <p class="powered"><a href="http://www.microsoft.com/azure/windowsazure.mspx"><img src="<%=Url.Content("~/Content/images/powered-by-azure.png")%>" width="188" height="38" alt="Powered by Windows Azure" /></a></p>

    </div>

    <asp:ContentPlaceHolder ID="ScriptsContent" runat="server" />

  </div>

</body>

</html>

Generate a new service package. To do this, in Solution Explorer, right-click the cloud service project and select Package. In the Package Windows Azure Application dialog, click Package and then wait until Visual Studio creates it. Once the package is ready, Visual Studio opens a window showing the folder that contains the generated files.

Switch to the PowerShell console and enter the command shown below, specifying the settings that apply to your service account where indicated by the placeholder parameters. Do not execute the command yet.

PowerShell Console

Get-HostedService -serviceName <YOUR_SERVICE_NAME> -subscriptionId <YOUR_SUBSCRIPTION_ID> -certificate (get-item cert:\CurrentUser\MY\<YOUR_CERTIFICATE_THUMBPRINT>) |

  Get-Deployment staging |

  Set-Deployment -package <PACKAGE_LOCATION> -configuration <CONFIGURATION_LOCATION> -label "v2.1"

<YOUR_SERVICE_NAME_LOWER_CASE>	The service name chosen when configuring the hosted service URL in Exercise 1, not its Service Label.
<YOUR_SUBSCRIPTION_ID>	The subscription ID of the Windows Azure account where the service will be deployed.
<YOUR_CERTIFICATE_THUMBPRINT>	The thumbprint value (in upper case) for the certificate uploaded previously.
< PACKAGE_LOCATION>	A path to a local file or the URL of the blob in Azure Storage that contains the service package.
<CONFIGURATION_LOCATION>	A path to a local file or the public URL of the blob that contains the service configuration file.

Note:

The command line shown above concatenates a sequence of cmdlets. First, it obtains a reference to the hosted service using Get-HostedService, then it uses Get-Deployment to retrieve its staging environment, and finally it uploads the package using Set-Deployment. This is done to illustrate how to compose a complex command using the PowerShell pipeline. In fact, in this particular case, you could instead provide all the required information to Set-Deployment to achieve the same result. For example:

Set-Deployment -subscriptionId <YOUR_SUBSCRIPTION_ID> -certificate <YOUR_CERTIFICATE> -serviceName <YOUR_SERVICE_NAME_LOWER_CASE> -slot staging -package <PACKAGE_LOCATION> -label <LABEL>

Note:

Important: The Set-Deployment cmdlet assumes that the compute service and storage service names are the same. If this is not the case, specify an additional parameter -StorageServicename <YOUR_SERVICE_NAME_LOWER_CASE>, replacing the placeholder with the name of the storage service name.

If you were to run the command as described above, the operation runs asynchronously. To show the operation’s progress while the deployment is taking place, you can pipe the output of the command into the Get-OperationStatus cmdlet and specify the WaitToComplete parameter. Add this cmdlet to the end of the command line entered previously making sure that you include the pipeline character ‘|’, as shown below.
PowerShell Console
```
Get-HostedService <YOUR_SERVICE_NAME_LOWER_CASE> -subscriptionId <YOUR_SUBSCRIPTION_ID> -certificate (get-item cert:\CurrentUser\MY\<YOUR_CERTIFICATE_THUMBPRINT>) |
```
```
  Get-Deployment staging |
```
```
  Set-Deployment -package <PACKAGE_LOCATION> -configuration <CONFIGURATION_LOCATION> -label "v2.1" |
```
```
Get-OperationStatus -WaitToComplete
```
Figure 44
Using the PowerShell pipeline to upgrade a deployment
Press ENTER to execute the command. Wait until the deployment process finishes, which may take several minutes. When the operation ends, it displays a message with the outcome of the operation; if the deployment completed without errors, you will see the message “Succeeded”.
Figure 45
PowerShell console showing the status of the package deployment operation
Note:
Deploying a package using the steps described above does not change its state. If the service is not running prior to deployment, it will remain in that state. To start the service, you need to update its deployment status using the Set-DeploymentStatus cmdlet.

To change the status of the service to a running state, in the PowerShell console, enter the following command.

PowerShell Console

Get-Deployment staging -serviceName <YOUR_SERVICE_NAME_LOWER_CASE> -subscriptionId <YOUR_SUBSCRIPTION_ID> -certificate (get-item cert:\CurrentUser\MY\<YOUR_CERTIFICATE_THUMBPRINT>) |

  Set-DeploymentStatus running |

  Get-OperationStatus –WaitToComplete

Finally, swap the deployments in the staging and production environments. To do this, in the PowerShell console, use the Get-Deployment and Move-Deployment cmdlets, as shown below, ensuring that you replace the placeholder parameters, <YOUR_SERVICE_NAME>, <YOUR_SUBSCRIPTION_ID>, and <YOUR_CERTIFICATE_THUMBPRINT> with the same values used previously, when you deployed the package.
PowerShell Console
```
Get-HostedServices -subscriptionId <YOUR_SUBSCRIPTION_ID> -certificate (get-item cert:\CurrentUser\MY\<YOUR_CERTIFICATE_THUMBPRINT>) |
```
```
  where {$_.ServiceName –eq “<YOUR_SERVICE_NAME>”} |
```
```
  Get-Deployment staging |
```
```
  Move-Deployment | 
```
```
  Get-OperationStatus –WaitToComplete
```

Verification

Now that you have deployed your updated solution to Window Azure, you are now ready to test it. You will launch the application to determine if the deployment succeeded and ensure that the service is working correctly and is available at its production URL.

In the Summary page of the management portal, under the Hosted Service section, click the Web Site URL link to open the production site in a browser window. Notice the footer of the page. It should reflect the updated text that you entered in the last task.
Figure 46
New deployment showing the updated footer text
Note:
If you visit the production site shortly after its promotion, the DNS name might not be ready. If you encounter a DNS error (404), wait a few minutes and try again. Keep in mind that Windows Azure creates DNS name entries dynamically and that the changes might take few minutes to propagate.

< previous | next >

Downloads

Download The Offline Training Kit
Download Hands-on Lab Document (DOCX)
Download Hands-on Lab Source Files

Advertise Here