Navigating The Hello World Custom Resource Provider Sample

Applies To: Windows Azure Pack

A sample Custom Resource Provider is provided as part of the Windows Azure Pack for Windows Server Developer Kit. For more information, see https://www.microsoft.com/en-us/download/details.aspx?id=41146.

The Hello World sample provides both management portal for administrator and management portal for tenants user interface extensions as well as the required endpoint implementations. As an MVC ASP.NET website based sample, controllers are used provide the endpoint definitions that allow access to the resource provider resources. They are also used to make calls to the Service Management API on behalf of the management portal user interface. The custom resource provider management portal administrator user interface extensions are expressed as views.

User Interface Extensions and Controllers

The sample user interface provides extensions for the management portal for administrators and the management portal for tenants. A client-side JavaScript based user interface is available through the Internet Explorer. The sample projects are:

For more information about how the client-side user interface is created, see Windows Azure Pack Management Portal User Interface Extensions.

Within these projects, server-side MVC controllers are used to interact with the Service Management API. The controller source files are

Both controllers use HelloWorldClient.cs in Microsoft.WAP.Samples.HelloWorld.APIClient to route calls through the Service Management API to the Hello World custom resource provider.

Resource Provider Endpoint Implementation

The four REST endpoints are implemented as server-side controllers in the Hello World sample project, Microsoft.WAP.HelloWorld.API. There are 7 controllers representing the administrator and tenant endpoints. FileShareController.cs represents the tenant endpoint whilst the others represent the administrator endpoint.

Tracing Client-Side User Extension Calls to Resource Provider Endpoints

The process by which a client-side management portal user activity results in a call to one of the resource provider endpoints is as follows. In this example, a tenant uses the custom management portal for tenants user interface extension to Quick Create a file share.

1. The tenant chooses to Quick Create a file share. Processed client-side In HelloWorldTenantController.js this results in a REST call server-side to CreateFileShare in HelloWorldTenantController.cs

   public JsonResult CreateFileShare(string subscriptionId, FileShareModel fileShareToCreate)
       {
           this.apiClient.CreateFileShare(subscriptionId, fileShareToCreate.ToApiObject());
   
           return this.Json(fileShareToCreate);
       }
   

2. CreateFileShare calls CreateFileShare in the api client helper class defined in HelloWorldClient.cs—Microsoft.WAP.Samples.HelloWorld.APIClient. This function does the work of building the URI for the Create File Share Tenant REST API call on the Hello World resource provider and making the call via the Service Management API.

   public void CreateFileShare(string subscriptionId, FileShare fileShareNameToCreate)
       {
           var requestUrl = this.CreateRequestUri(string.Format(CultureInfo.InvariantCulture, HelloWorldClient.FileShares, subscriptionId));
           this.Post<FileShare>(requestUrl, fileShareNameToCreate);
       }
   

   The relative path for the File Shares REST call is defined in HelloWorldClient.FileShares. The definition for all administrator and tenant relative paths is in HelloWorldClient.cs.

3. To build the complete URI, CreateRequestUri (HelloWorldClient) also needs the Service Management API endpoint obtained from BaseEndpoint.

   private Uri CreateRequestUri(string relativePath, string queryString = "")
       {
           var endpoint = new Uri(this.BaseEndpoint, relativePath);
           var uriBuilder = new UriBuilder(endpoint);
           uriBuilder.Query = queryString;
           return uriBuilder.Uri;
       }
   

   BaseEndpoint is assigned in the HelloWorldClient class constructor which is created in the HelloWorldTenantController class constructor. rdfeEndpoint is the Service Management API endpoint.

   public HelloWorldTenantController()
       {
           // 
           var rdfeEndpoint = new Uri(AppManagementConfiguration.Instance.RdfeUnifiedManagementServiceUri);
   
           var handler = new BearerMessageProcessingHandler();
   
           this.apiClient = new HelloWorldClient(rdfeEndpoint, handler);           
       }    
   

4. The call to this.Post in CreateFileShare (HelloWorldClient.cs) sends the REST call, with accompanying file share name request body, to the Service Management API which routes the call to the Hello World custom resource provider.

5. The hello world custom provider tenant endpoint receives the create file share call in FileShareController.cs and performs the appropriate action.

   [HttpPost]
   public void CreateFileShare(FileShare fileShare)
   {
       fileShares.Add(new FileShare
       {
           Id = fileShares.Count,
           FileServerName = fileShare.FileServerName,
           Name = fileShare.Name,
           SubscriptionId = fileShare.SubscriptionId,
           Size = fileShare.Size
       };
   }
   

Registering the Hello World Resource Provider

The hello world sample project Microsoft.WAP.Samples.HelloWorld.Setup provides an installer and registration for the customer provider. It is documented in Deploying a Windows Azure Pack Management Portal Extension. Specifically related to registering a custom resource provider is registering the endpoints with Windows Azure Pack. The hello world sample uses a Windows PowerShell script (Register-ResourceProvider.ps1) to register the custom resource provider endpoints. This gives Windows Azure Pack the necessary information to correctly pass REST calls through the Service Management API to the Hello World custom resource provider. In the script, Windows Azure Pack PowerShell cmdlets perform registration. The rpSettings parameter provides the necessary endpoint information used to register the endpoints and other configuration information.

$rpSettings = @{
    'Name' = $rpName;
    'DisplayName' = 'Hello World';
    'InstanceDisplayName' = 'Hello World';
    'AdminForwardingAddress' = "http://$hostName/admin";
    'AdminAuthenticationMode' = 'Basic';
    'AdminAuthenticationUserName' = $userName;
    'AdminAuthenticationPassword' = $password;        
    'TenantForwardingAddress' = "http://$hostName/";
    'TenantAuthenticationMode' = 'Basic';
    'TenantAuthenticationUserName' = $userName;
    'TenantAuthenticationPassword' = $password;
    'TenantSourceUriTemplate' = '{subid}/services/helloworld/{*path}';
    'TenantTargetUriTemplate' = 'subscriptions/{subid}/{*path}';
    'NotificationForwardingAddress' = "http://$hostName/admin";
    'NotificationAuthenticationMode' = 'Basic';
    'NotificationAuthenticationUserName' = $userName;
    'NotificationAuthenticationPassword' = $password;
}

Write-Host -ForegroundColor Green "Create new resource provider '$rpName'..."
$rp = New-ResourceProvider @rpSettings
Write-Host -ForegroundColor Green "Created new resource provider '$rpName'."

See Also

Windows Azure Pack Custom Resource Providers