Edit

Use API version profiles with .NET in Azure Stack Hub

  • Article

Important

The .NET SDK has been updated from track 1 to track 2. We highly recommend migrating to the track 2 SDK as soon as possible. Please refer to this migration guide for instructions.

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. If you are using the deprecated track 1 .NET SDK (not recommended), these packages are versioned with API profiles, such as 2020-09-01-hybrid and 2019-03-01-hybrid. API profiles in the .NET SDK enable hybrid cloud development by helping you switch between global Azure resources and Azure Stack Hub resources. See the .NET and API version profiles section for more information.

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.

Note

The ResourceProvider portion of the NuGet package specification must be changed. Additionally, the packages for track 1 .NET SDK are deprecated, so you may face errors. We recommend updating to the track 2 .NET SDK as soon as possible.

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
2311 2020_09_01
2301 2020_09_01
2206 2020_09_01
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 this sample repository for update-to-date (track 2) sample code. See this sample repository for track 1 sample code. The root README.md describes general requirements, and each sub-directory contains a specific sample with its own README.md that describes 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: