Edit

Use API version profiles with .NET in Azure Stack Hub

  • Article

The .NET SDK for the Azure Stack Hub Resource Manager provides tools to help you build and manage your infrastructure. Resource providers in the SDK include Compute, Networking, Storage, App Services, and Key Vault. The .NET SDK includes 14 NuGet packages. You must download these packages to your solution every time you compile your project. However, you can specifically download which resource provider you'll use for the 2020-09-01-hybrid or 2019-03-01-hybrid versions in order to optimize the memory for your app. Each package consists of a resource provider, the respective API version, and the API profile to which it belongs. API profiles in the .NET SDK enable hybrid cloud development by helping you switch between global Azure resources and resources on Azure Stack Hub.

Install the Azure .NET SDK

.NET and API version profiles

An API profile is a combination of resource providers and API versions. Use an API profile to get the latest, most stable version of each resource type in a resource provider package.

Profiles

For profiles containing dates, to use a different SDK profile or version, substitute the date in Microsoft.Azure.Management.Profiles.hybrid_<date>.ResourceManager. For example, for the 2008 version, the profile is 2019_03_01, and the string becomes Microsoft.Azure.Management.Profiles.hybrid_2019_03_01.ResourceManager. Note that sometimes the SDK team changes the name of the packages, so simply replacing the date of a string with a different date might not work. See the following table for association of profiles and Azure Stack versions.

Azure Stack version Profile
2108 2020_09_01
2102 2020_09_01
2008 2019_03_01

For more information about Azure Stack Hub and API profiles, see the Summary of API profiles.

Subscription

If you do not already have a subscription, create a subscription and save the subscription ID to be used later. For information about how to create a subscription, see this document.

Service principal

A service principal and its associated environment information should be created and saved somewhere. Service principal with owner role is recommended, but depending on the sample, a contributor role may suffice. Refer to the README in the sample repository for the required values. You may read these values in any format supported by the SDK language such as from a JSON file (which our samples use). Depending on the sample being run, not all of these values may be used. See the sample repository for updated sample code or further information.

Tenant ID

To find the directory or tenant ID for your Azure Stack Hub, follow the instructions in this article.

Register resource providers

Register required resource providers by following this document. These resource providers will be required depending on the samples you want to run. For example, if you want to run a VM sample, the Microsoft.Compute resource provider registration is required.

Azure Stack resource manager endpoint

Azure Resource Manager (ARM) is a management framework that enables administrators to deploy, manage, and monitor Azure resources. Azure Resource Manager can handle these tasks as a group, rather than individually, in a single operation. You can get the metadata info from the Resource Manager endpoint. The endpoint returns a JSON file with the info required to run your code.

  • The ResourceManagerEndpointUrl in the Azure Stack Development Kit (ASDK) is: https://management.local.azurestack.external/.
  • The ResourceManagerEndpointUrl in integrated systems is: https://management.region.<fqdn>/, where <fqdn> is your fully qualified domain name.
  • To retrieve the metadata required: <ResourceManagerUrl>/metadata/endpoints?api-version=1.0. For available API versions, see Azure rest API specifications. E.g., in 2020-09-01 profile version, you can change the api-version to 2019-10-01 for resource provider microsoft.resources.

Sample JSON:

{
   "galleryEndpoint": "https://portal.local.azurestack.external:30015/",
   "graphEndpoint": "https://graph.windows.net/",
   "portal Endpoint": "https://portal.local.azurestack.external/",
   "authentication": 
      {
         "loginEndpoint": "https://login.windows.net/",
         "audiences": ["https://management.yourtenant.onmicrosoft.com/3cc5febd-e4b7-4a85-a2ed-1d730e2f5928"]
      }
}

Samples

See the sample repository for update-to-date sample code. The root README.md describes general requirements, and each sub-directory contains a specific sample with its own README.md on how to run that sample.

See here for the sample applicable for Azure Stack version 2008 or profile 2019-03-01 and below.

Next steps

Learn more about API profiles: