News

Photos

Articles

Components

Applications

Kleinkunst

.NET - Azure Management Libraries

Date:
Author: Stefan Cruysberghs

.NET

Azure

Some months ago I was creating some tools at my work to automate the creation of branches in Team Foundation Server, together with namespaces, build definitions and Azure environments. To create and delete Azure clouds services, databases, storage, websites, services busses, … I used the Azure Management Libraries.

The Microsoft Azure Management Libraries (MAML) are a great collection of .NET NuGet packages which allow you to automate, deploy, and test cloud infrastructure easily. Each package provides client .NET classes for an individual area of the Windows Azure REST services. These classes provide a lot properties and methods which are fully await/async.

There are not that many examples and documentation on the internet yet. So I decided to write a simple article about it with a lot of C# examples. All examples in this article will use the synchronous calls but all methods also have an async version. I hope they can be useful to get started with the Azure Management Libraries.

NuGet packages
Authentication and certificates
Azure cloud services and certificates
Azure storage
Azure SQL databases
Azure websites, webspaces and settings
Azure service bus and queues
Azure virtual machines

NuGet packages

So first of all you need to install the Azure Management Library NuGet packages for all Azure areas you need:

You will see that your project will reference the Microsoft.WindowsAzure.Management assemblies.

Authentication & certificates

All requests to the Azure Management services must be authenticated. Currently there are 2 ways to authenticate; Azure Active Directory and Management Certificate. If you want to use Azure Active Directory then you have install the Active Directory Authentication Library NuGet package. In this article I will show how authentication with a certificate works.

/// <summary>
/// Gets the Azure subscription credentials from a PFX certificate.
/// </summary>
/// <returns>CertificateCloudCredentials object.</returns>
private static SubscriptionCloudCredentials GetCredentials()
{
    var subscriptionId = "MyAzureSubscriptionId";
    var certificateKey = "MyCertificateKey";
    var certificateFullPath = @"D:\Certificates\MyAzureAccountCertificate.pfx";
 
    var x509Cert = new X509Certificate2(
        certificateFullPath, certificateKey, X509KeyStorageFlags.MachineKeySet);
 
    return new CertificateCloudCredentials(subscriptionId, x509Cert);
}

The steps to access one of the Azure Management API's are always to same. First you have make sure that you have the credentials and then you can create one of the clients included in CloudContext.Clients. Each client gives you access to an individual area of the Windows Azure platform. All operations in the clients are based on the HttpClient which will call the REST services of Azure.

Azure cloud services & certificates

List all Azure cloud services

This first example will list all Azure hosed cloud services and show their name, description, affinity group and status. Therefore you need to create a ComputeManagementClient.

/// <summary>
/// List all Azure cloud services.
/// </summary>
public void ListAzureCloudServices()
{
    var credentials = GetCredentials();
 
    var computeManagementClient = CloudContext.Clients.CreateComputeManagementClient(credentials);
    var hostedServices = computeManagementClient.HostedServices.List();
    foreach (var hostedService in hostedServices)
    {
        var hostedServiceName = hostedService.ServiceName;
        var hostedServiceDescription = hostedService.Properties.Description;
        var hostedServiceAffinityGroup = hostedService.Properties.AffinityGroup;
        var hostedServiceStatus = hostedService.Properties.Status;
    }
}

Create a new Azure cloud service

Creating an Azure cloud service is very easy, you only have to pass a HostedServiceCreateParameters object to the Create method. These parameters contain some basic info like name, description and affinity group.

/// <summary>
/// Create a new Azure cloud service.
/// </summary>
public void CreateAzureCloudService()
{
    var affinityGroup = "MyAffinityGroup";
    var serviceName = "MyAzureCloudService";
    var description = "My Azure Cloud Service";
 
    var credentials = GetCredentials();
 
    var computeManagementClient = CloudContext.Clients.CreateComputeManagementClient(credentials);
 
    try
    {
        var hostedService = computeManagementClient.HostedServices.Get(serviceName);
        if (hostedService != null)
        {
            throw new Exception(string.Format("The Azure cloud service {0} already exists", serviceName));
        }
    }
    catch (Exception)
    {
    }
 
    var hostedServiceCreateParams = new HostedServiceCreateParameters();
    hostedServiceCreateParams.ServiceName = serviceName;
    hostedServiceCreateParams.Description = description;
    hostedServiceCreateParams.AffinityGroup = affinityGroup;
    computeManagementClient.HostedServices.Create(hostedServiceCreateParams);
}

Delete an Azure cloud service

When you want to delete a hosted service, you also have to delete the Deployments. In this example I try to delete all production and staging deployments slots before deleting the host service.

/// <summary>
/// Delete an Azure cloud service.
/// </summary>
public void DeleteAzureCloudService()
{
    var serviceName = "MyAzureCloudService";
 
    var credentials = GetCredentials();
 
    var computeManagementClient = CloudContext.Clients.CreateComputeManagementClient(credentials);
 
    // Delete the production deployment if there is one
    try
    {
        computeManagementClient.Deployments.DeleteBySlot(serviceName, DeploymentSlot.Production);
    }
    catch (Exception)
    {
    }
 
    // Delete the staging deployment if there is one
    try
    {
        computeManagementClient.Deployments.DeleteBySlot(serviceName, DeploymentSlot.Staging);
    }
    catch (Exception)
    {
    }
 
    computeManagementClient.HostedServices.Delete(serviceName);
}

Uploads a certificate to an Azure cloud service

After creating a new Azure Cloud Service, you also have to upload some certificates. This can be done by converting the PFX files to an array of bytes and passing this to the Create method of ServiceCertificates.

/// <summary>
/// Load certificate pfx file and return it as array of bytes.
/// </summary>
/// <param name="fileName">Name of the file.</param>
/// <returns>Array of bytes.</returns>
private byte[] GetCertRawBytes(string fileName)
{
    var fileStream = File.OpenRead(fileName);
    byte[] rawCert;
    using (var stream = fileStream)
    {
        rawCert = new byte[stream.Length];
        stream.Read(rawCert, 0, rawCert.Length);
    }
    return rawCert;
}
 
/// <summary>
/// Uploads a certificate to an Azure cloud service.
/// </summary>
/// <returns></returns>
public void UploadCertificateToAzureCloudService()
{
    var serviceName = "MyAzureCloudService";
    var certificateFullPath = @"D:\Certificates\MyAzureAccountCertificate.pfx";
    var certificateKey = "MyCertificateKey";
            
    var rawCert = GetCertRawBytes(certificateFullPath);
 
    var credentials = GetCredentials();
    var computeManagementClient = CloudContext.Clients.CreateComputeManagementClient(credentials);
 
    var certificateCreateParameters = new ServiceCertificateCreateParameters()
    {
        Data = rawCert,
        CertificateFormat = CertificateFormat.Pfx,
        Password = certificateKey
    };
 
    computeManagementClient.ServiceCertificates.Create(serviceName, certificateCreateParameters);
}

Deletes the certificates from an Azure cloud service

This method will try to delete all certificates of the specified Azure Cloud Service.

/// <summary>
/// Deletes the certificates from an Azure cloud service.
/// </summary>
public void DeleteCertificatesFromAzureCloudService()
{
    var serviceName = "MyAzureCloudService";
 
    var credentials = GetCredentials();
    var computeManagementClient = CloudContext.Clients.CreateComputeManagementClient(credentials);
 
    var certificates = computeManagementClient.ServiceCertificates.List(serviceName);
    foreach (var certificat in certificates)
    {
        var certificateDeleteParams = new ServiceCertificateDeleteParameters();
        certificateDeleteParams.ServiceName = serviceName;
        certificateDeleteParams.Thumbprint = certificat.Thumbprint;
        certificateDeleteParams.ThumbprintAlgorithm = certificat.ThumbprintAlgorithm;
 
        try
        {
            computeManagementClient.ServiceCertificates.Delete(certificateDeleteParams);
        }
        catch (Exception ex)
        {
        }
    }
}

Azure storage

Create new Azure storage

When you want to access the Azure storage account, then you have to creat another client. This can be done with the CreateStorageManagementClient method. Same steps here for creating an intance; first create a StorageAccountCreateParameters object and pass it to the Create method.

/// <summary>
/// Create new Azure storage.
/// </summary>
public void CreateAzureStorage()
{
    var affinityGroup = "MyAffinityGroup";
    var storageName = "MyAzureStorage";
    var description = "My Azure Storage";
 
    var credentials = GetCredentials();
 
    var storageManagementClientstorage = CloudContext.Clients.CreateStorageManagementClient(credentials);
 
    try
    {
        var storage = storageManagementClientstorage.StorageAccounts.Get(storageName);
        if (storage != null)
        {
            throw new Exception(string.Format("The Azure storage {0} already exists", storageName));
        }
    }
    catch (Exception)
    {
    }
 
    var storageCreateParams = new StorageAccountCreateParameters();
    storageCreateParams.Name = storageName;
    storageCreateParams.Description = description;
    storageCreateParams.AffinityGroup = affinityGroup;
    storageCreateParams.AccountType = "Standard_GRS";
    storageManagementClientstorage.StorageAccounts.Create(storageCreateParams);
}

Delete an Azure storage

/// <summary>
/// Delete an Azure storage.
/// </summary>
public void DeleteAzureStorage()
{
    var storageName = "MyAzureStorage";
    var credentials = GetCredentials();
 
    var storageManagementClientstorage = CloudContext.Clients.CreateStorageManagementClient(credentials);
    storageManagementClientstorage.StorageAccounts.Delete(storageName);
}

Get the Azure storage keys

Once an Azure Storage account is created, you can access to storage keys. You will need the primary key if you want to upload files to Azure storage.

/// <summary>
/// Get the Azure storage primary key.
/// </summary>
public string GetAzureStoragePrimaryKey(string storageName)
{
    var credentials = GetCredentials();
 
    var storageManagementClientstorage = CloudContext.Clients.CreateStorageManagementClient(credentials);
 
    var storageKeys = storageManagementClientstorage.StorageAccounts.GetKeys(storageName);
 
    return storageKeys.PrimaryKey;
}

Azure SQL databases

Following examples will create and delete an Azure SQL database in the given database server.

Create a new Azure SQL database

/// <summary>
/// Create a new Azure SQL database.
/// </summary>
public void CreateAzureSqlDatabase()
{
    var serverName = "MyAzureSqlDatabaseServer";
    var databaseName = "MyAzureSqlDatabase";
 
    var credentials = GetCredentials();
 
    var sqlManagementClient = CloudContext.Clients.CreateSqlManagementClient(credentials);
 
    try
    {
        var sqlDatabase = sqlManagementClient.Databases.Get(serverName, databaseName);
        if (sqlDatabase != null)
        {
            throw new Exception(string.Format("The SQL database {0} already exists", databaseName));
        }
    }
    catch (Exception)
    {
    }
 
    var sqlDatabaseCreateParams = new DatabaseCreateParameters();
    sqlDatabaseCreateParams.Name = databaseName;
    sqlManagementClient.Databases.Create(serverName, sqlDatabaseCreateParams);
}

Delete an Azure SQL database

/// <summary>
/// Delete an Azure SQL database.
/// </summary>
public void DeleteAzureSqlDatabase()
{
    var serverName = "MyAzureSqlDatabaseServer";
    var databaseName = "MyAzureSqlDatabase";
 
    var credentials = GetCredentials();
 
    var sqlManagementClient = CloudContext.Clients.CreateSqlManagementClient(credentials);
    sqlManagementClient.Databases.Delete(serverName, databaseName);
}

Azure websites, webspaces & settings

Create a new Azure website

When you want to create an Azure Website, then you need a WebHostingPlan and a WebSpace. So following example will look for an existing WebSpace and create a new Website in it.

/// <summary>
/// Create a new Azure website.
/// </summary>
public void CreateAzureWebsite()
{
    var websiteName = "MyAzureWebsite";
    var regionName = "West Europe";
 
    var credentials = GetCredentials();
 
    var websiteManagementClient = CloudContext.Clients.CreateWebSiteManagementClient(credentials);
 
    var webSpaces = websiteManagementClient.WebSpaces.List();
    var webSpace = webSpaces.FirstOrDefault(x => x.GeoRegion == regionName);
    if (webSpace == null)
    {
        throw new Exception(string.Format("No webspace for region {0} found", regionName));
    }
 
    var webHostingPlans = websiteManagementClient.WebHostingPlans.List(webSpace.Name);
    var webHostingPlan = webHostingPlans.FirstOrDefault();
    if (webHostingPlan == null)
    {
        throw new Exception(string.Format("No webhostingplan found"));
    }
 
    try
    {
        var website = websiteManagementClient.WebSites.Get(webSpace.Name, websiteName, null);
 
        if (website != null)
        {
            throw new Exception(string.Format("The website {0} already exists", websiteName));
        }
    }
    catch (Exception)
    {
    }
 
    var websiteCreateParams = new WebSiteCreateParameters();
    websiteCreateParams.Name = websiteName;
    websiteCreateParams.ServerFarm = webHostingPlan.Name;
    websiteManagementClient.WebSites.Create(webSpace.Name, websiteCreateParams);
}

Add or update website settings

In the Azure Portal you can also configure the settings of a website. The MAML also offers some API to do this in code. Next example loads the AppSettings of WebSiteUpdateConfigurationParameters and tries to add or update a setting.


/// <summary>
/// Update setting in a Azure website.
/// </summary>
public void UpdateAzureWebsiteSetting()
{
    var websiteName = "MyAzureWebsite";
    var regionName = "West Europe";
    var mySettingName = "MySettingName";
    var mySettingValue = "MySettingValue";
 
    var credentials = GetCredentials();
 
    var websiteManagementClient = CloudContext.Clients.CreateWebSiteManagementClient(credentials);
 
    var webSpaces = websiteManagementClient.WebSpaces.List();
    var webSpace = webSpaces.FirstOrDefault(x => x.GeoRegion == regionName);
    if (webSpace == null)
    {
        throw new HandledException(string.Format("No webspace for region {0} found", regionName));
    }
 
    var currentConfiguration = websiteManagementClient.WebSites.GetConfiguration(webSpace.Name, websiteName);
 
    var newConfiguration = new WebSiteUpdateConfigurationParameters
    {
        ConnectionStrings = null,
        DefaultDocuments = null,
        HandlerMappings = null,
        Metadata = null,
        AppSettings = currentConfiguration.AppSettings
    };
 
    // Add setting or update it
    if (!newConfiguration.AppSettings.ContainsKey(mySettingName))
    {
        newConfiguration.AppSettings.Add(mySettingName, mySettingValue);
    }
    else
    {
        newConfiguration.AppSettings[mySettingName] = mySettingValue;
    }
 
    websiteManagementClient.WebSites.UpdateConfiguration(webSpace.Name, websiteName, newConfiguration);
}

Delete an Azure website

When deleting an Azure Website, you can specify some extra options like DeleteAllSlots, DeleteEmptyServerFarm and DeleteMetrics.

/// <summary>
/// Delete an Azure website.
/// </summary>
public void DeleteAzureWebsite()
{
    var websiteName = "MyAzureWebsite";
    var regionName = "West Europe";
 
    var credentials = GetCredentials();
 
    var websiteManagementClient = CloudContext.Clients.CreateWebSiteManagementClient(credentials);
 
    var webSpaces = websiteManagementClient.WebSpaces.List();
    var webSpace = webSpaces.FirstOrDefault(x => x.GeoRegion == regionName);
    if (webSpace == null)
    {
        throw new HandledException(string.Format("No Azure webspace for region {0} found", regionName));
    }
 
    var webSiteDeleteParameters = new WebSiteDeleteParameters();
    webSiteDeleteParameters.DeleteAllSlots = true;
    webSiteDeleteParameters.DeleteEmptyServerFarm = false;
    webSiteDeleteParameters.DeleteMetrics = true;
    websiteManagementClient.WebSites.Delete(webSpace.Name, websiteName, webSiteDeleteParameters);
}

Azure service bus & queues

Create a new Azure service bus


/// <summary>
/// Create a new Azure service bus.
/// </summary>
public void CreateAzureServiceBus()
{
    var serviceBusName = "MyAzureServiceBus";
    var region = "West Europe";
 
    var credentials = GetCredentials();
 
    var serviceBusManagementClient = CloudContext.Clients.CreateServiceBusManagementClient(credentials);
 
    var checkserviceBusResponse = serviceBusManagementClient.Namespaces.CheckAvailability(serviceBusName);
 
    if (checkserviceBusResponse.IsAvailable)
    {
        var serviceBusNamespaceCreateParameters = new ServiceBusNamespaceCreateParameters();
        serviceBusNamespaceCreateParameters.NamespaceType = NamespaceType.Messaging;
        serviceBusNamespaceCreateParameters.Region = region;
        serviceBusNamespaceCreateParameters.CreateACSNamespace = true;
        serviceBusManagementClient.Namespaces.CreateNamespace(
            serviceBusName, serviceBusNamespaceCreateParameters);
    }
}

Create a new Azure service bus queue

Once an Azure Service Bus is created, you can also create queues and topics. Following example will create a new queue.

/// <summary>
/// Create a new Azure service bus queue.
/// </summary>
public void CreateAzureServiceBusQueue()
{
    var serviceBusName = "MyAzureServiceBus";
    var queueName = "MyAzureServiceBusQueue";
 
    var credentials = GetCredentials();
 
    var serviceBusManagementClient = CloudContext.Clients.CreateServiceBusManagementClient(credentials);
 
    var serviceBusQueueCreateParameters = new ServiceBusQueueCreateParameters();
    serviceBusQueueCreateParameters.Name = queueName;
    serviceBusManagementClient.Queues.Create(serviceBusName, serviceBusQueueCreateParameters);
}

Delete an Azure service bus

/// <summary>
/// Delete an Azure service bus.
/// </summary>
public void DeleteAzureServiceBus()
{
    var serviceBusName = "MyAzureServiceBus";
 
    var credentials = GetCredentials();
 
    var serviceBusManagementClient = CloudContext.Clients.CreateServiceBusManagementClient(credentials);
    serviceBusManagementClient.Namespaces.Delete(serviceBusName);
}

Azure virtual machines

List all Azure virtual machines

The latest SDK also supports the virtual machines in Azure. The first example will list all existing VirtualMachineDisks. The other examples will show how to start and shutdown virtual machines in code.


/// <summary>
/// List all Azure virtual machines.
/// </summary>
public void ListVirtualMachines()
{
    var credentials = GetCredentials();
 
    var computeManagementClient = CloudContext.Clients.CreateComputeManagementClient(credentials);
 
    var virtualMachineDisks = computeManagementClient.VirtualMachineDisks.ListDisks();
 
    foreach(var virtualMachineDisk in virtualMachineDisks)
    {
        var hostedServiceName = virtualMachineDisk.UsageDetails.HostedServiceName;
        var deploymentName = virtualMachineDisk.UsageDetails.DeploymentName;
        var operatingSystemType = virtualMachineDisk.OperatingSystemType;
        var logicalSizeInGB = virtualMachineDisk.LogicalSizeInGB;
    }
}

Start and shutdown Azure virtual machines

/// <summary>
/// Start a Azure virtual machine.
/// </summary>
public void StartVirtualMachine()
{
    var hostedServiceName = "MyVmServiceName";
    var deploymentName = "MyVmDeploymentName";
 
    var credentials = GetCredentials();
 
    var computeManagementClient = CloudContext.Clients.CreateComputeManagementClient(credentials);
 
    var response = computeManagementClient.Deployments.GetByName(hostedServiceName, deploymentName);
    if (response.Status != DeploymentStatus.Running)
    {
        computeManagementClient.VirtualMachines.Start(hostedServiceName, deploymentName, deploymentName);
    }
}

/// <summary>
/// Shutdown a Azure virtual machine.
/// </summary>
public void ShutdownVirtualMachine()
{
    var hostedServiceName = "MyVmServiceName";
    var deploymentName = "MyVmDeploymentName";
 
    var credentials = GetCredentials();
 
    var computeManagementClient = CloudContext.Clients.CreateComputeManagementClient(credentials);
 
    var response = computeManagementClient.Deployments.GetByName(hostedServiceName, deploymentName);
    if (response.Status == DeploymentStatus.Running)
    {
        var virtualMachineShutdownParameters = new VirtualMachineShutdownParameters()
        {
            PostShutdownAction = PostShutdownAction.StoppedDeallocated,
        };
 
        computeManagementClient.VirtualMachines.Shutdown(
            hostedServiceName, deploymentName, deploymentName, virtualMachineShutdownParameters);
    }
}

I hope this article did help you getting started with the Microsoft Azure Management Libraries (MAML). If you have any suggestions or comments be sure to let me know.