Resurshantering med hjälp av Azure SDK för .NET

  • Artikel

Azure SDK för .NET-hanteringsplanbibliotek hjälper dig att skapa, etablera och hantera Azure-resurser inifrån .NET-program. Alla Azure-tjänster har motsvarande hanteringsbibliotek.

Med hanteringsbiblioteken (namnrymder som börjar med Azure.ResourceManager, till exempel Azure.ResourceManager.Compute), kan du skriva konfigurations- och distributionsprogram för att utföra samma uppgifter som du kan via Azure-portalen, Azure CLI eller andra resurshanteringsverktyg.

Dessa paket följer de nya Riktlinjerna för Azure SDK, som ger grundläggande funktioner som delas mellan alla Azure SDK:er, inklusive:

  • Det intuitiva Azure Identity-biblioteket.
  • En HTTP-pipeline med anpassade principer.
  • Felhantering.
  • Distribuerad spårning.

Kommentar

Du kanske märker att vissa paket fortfarande är förhandsversioner och att stegvisa versioner av ytterligare Bibliotek för Hanteringsplanet för Azure-tjänster pågår. Om du letar efter ett stabilt versionspaket för en viss Azure-resurs och för närvarande endast en förhandsversion är tillgänglig kan du skapa ett problem i Azure SDK för .NET Github-lagringsplatsen

Kom igång

Förutsättningar

Installera -paketet

Installera NuGet-paketen för Azure Identity och Azure Resource Management för .NET. Till exempel:

Install-Package Azure.Identity
Install-Package Azure.ResourceManager
Install-Package Azure.ResourceManager.Resources
Install-Package Azure.ResourceManager.Compute
Install-Package Azure.ResourceManager.Network

Autentisera klienten

Standardalternativet för att skapa en autentiserad klient är att använda DefaultAzureCredential. Eftersom alla hanterings-API:er går igenom samma slutpunkt måste bara en toppnivå ArmClient skapas för att kunna interagera med resurser.

Om du vill autentisera med Azure och skapa en ArmClientinstansierar du en ArmClient angiven autentisering:

using Azure.Identity;
using Azure.ResourceManager;
using System;
using System.Threading.Tasks;

// Code omitted for brevity

ArmClient client = new ArmClient(new DefaultAzureCredential());

Mer information om klassen finns i Azure.Identity.DefaultAzureCredential StandardAzureCredential-klass.

Hanterings-SDK-fuskark

Kom igång med Azure Management SDK för .NET genom att anta att du har en uppgift att skapa/lista/uppdatera/ta bort ett typiskt Azure Service Bus-namnområde genom att följa dessa steg:

  1. Autentisera till den prenumeration och resursgrupp som du vill arbeta med.
using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.ServiceBus;

ArmClient client = new ArmClient(new DefaultAzureCredential());
SubscriptionResource subscription = client.GetDefaultSubscription();
ResourceGroupResource resourceGroup =
    client.GetDefaultSubscription().GetResourceGroup(resourceGroupName);
  1. Hitta motsvarande metod för att hantera din Azure-resurs.
Åtgärd Method
Hämta en resurs med resursidentifierare client.GetServiceBusQueueResource(ResourceIdentifier resourceIdentifier)
List resourceGroup.GetServiceBusNamespaces()
Index resourceGroup.GetServiceBusNamespace(string servicebusNamespaceName)
Lägg till/uppdatera resourceGroup.GetServiceBusNamespaces().CreateOrUpdate(Azure.WaitUntil waitUntil, string name, ServiceBusNamespaceData data)
Innehåller resourceGroup.GetServiceBusNamespaces().Exists(string servicebusNamespaceName)
Delete client.GetServiceBusQueueResource(ResourceIdentifior resourceIdentifior).Delete() eller resourceGroup.GetServiceBusNamespace(string servicebusNamespaceName).Delete()

Kom ihåg att alla Azure-resurser, inklusive själva resursgruppen, kan hanteras av motsvarande hanterings-SDK med hjälp av kod som liknar exemplet ovan. Om du vill hitta rätt Azure Management SDK-paket letar du efter paket med namnet med följande mönster Azure.ResourceManager.{ResourceProviderName}.

Mer information om ResourceIdentifier finns i Strukturerad resursidentifierare.

Nyckelbegrepp

Förstå Azure-resurshierarki

För att minska antalet klienter som behövs för att utföra vanliga uppgifter och antalet redundanta parametrar som var och en av dessa klienter tar, har vi introducerat en objekthierarki i SDK som efterliknar objekthierarkin i Azure. Varje resursklient i SDK har metoder för att komma åt resursklienter för sina underordnade som redan är begränsade till rätt prenumeration och resursgrupp.

För att åstadkomma detta introducerar vi tre standardtyper för alla resurser i Azure:

{ResourceName} Resursklass

Den här typen representerar ett fullständigt resursklientobjekt som innehåller en dataegenskap som exponerar informationen som en {ResourceName}-datatyp . Den har också åtkomst till alla åtgärder på resursen utan att behöva skicka in omfångsparametrar som prenumerations-ID eller resursnamn. Detta gör det enkelt att direkt köra åtgärder på resultatet av listanrop, eftersom allt returneras som en fullständig resursklient nu.

ArmClient client = new ArmClient(new DefaultAzureCredential());
string resourceGroupName = "myResourceGroup";
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
ResourceGroupResource resourceGroup = await subscription.GetResourceGroupAsync(resourceGroupName);
await foreach (VirtualMachineResource virtualMachine in resourceGroup.GetVirtualMachinesAsync())
{
    //previously we would have to take the resourceGroupName and the vmName from the vm object
    //and pass those into the powerOff method as well as we would need to execute that on a separate compute client
    await virtualMachine.PowerOffAsync(WaitUntil.Completed);
}

{ResourceName} Dataklass

Den här typen representerar den modell som utgör en viss resurs. Detta är vanligtvis svarsdata från ett tjänstanrop som HTTP GET och innehåller information om den underliggande resursen. Tidigare representerades detta av en modellklass .

{ResourceName} Samlingsklass

Den här typen representerar de åtgärder som du kan utföra på en samling resurser som tillhör en specifik överordnad resurs. Det här objektet innehåller de flesta av de logiska samlingsåtgärderna.

Samlingsbeteende Samlingsmetod
Iterera/lista GetAll()
Index Get(strängnamn)
Lägg till CreateOrUpdate(Azure.WaitUntil waitUntil, strängnamn, {ResourceName}Datadata)
Innehåller Exists(strängnamn)

I de flesta fall är överordnad för en resurs ResourceGroup, men i vissa fall har en resurs själv underresurs, till exempel är ett undernät underordnat ett VirtualNetwork. Själva ResourceGroup är underordnad en prenumeration

Färdigställa allt

Anta att vårt företag kräver att alla virtuella datorer taggas med ägaren. Vi har till uppgift att skriva ett program för att lägga till taggen till eventuella virtuella datorer som saknas i en viss resursgrupp.

// First we construct our armClient
ArmClient client = new ArmClient(new DefaultAzureCredential());

// Next we get a resource group object
// ResourceGroup is a {ResourceName}Resource object from above
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
ResourceGroupResource resourceGroup =
   await subscription.GetResourceGroupAsync("myRgName");

// Next we get the collection for the virtual machines
// vmCollection is a {ResourceName}Collection object from above
VirtualMachineCollection virtualMachineCollection = await resourceGroup.GetVirtualMachines();

// Next we loop over all vms in the collection
// Each vm is a {ResourceName}Resource object from above
await foreach(VirtualMachineResource virtualMachine in virtualMachineCollection)
{
   // We access the {ResourceName}Data properties from vm.Data
   if(!virtualMachine.Data.Tags.ContainsKey("owner"))
   {
       // We can also access all operations from vm since it is already scoped for us
       await virtualMachine.AddTagAsync("owner", GetOwner());
   }
}

Strukturerad resursidentifierare

Resurs-ID:t innehåller användbar information om själva resursen, men de är enkla strängar som måste parsas. I stället för att implementera din egen parsningslogik kan du använda ett ResourceIdentifier objekt som utför parsningen åt dig.

Exempel: Parsa ett ID med hjälp av ett ResourceIdentifier-objekt

string resourceId = "/subscriptions/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/resourceGroups/workshop2021-rg/providers/Microsoft.Network/virtualNetworks/myVnet/subnets/mySubnet";
ResourceIdentifier id = new ResourceIdentifier(resourceId);
Console.WriteLine($"Subscription: {id.SubscriptionId}");
Console.WriteLine($"ResourceGroup: {id.ResourceGroupName}");
Console.WriteLine($"Vnet: {id.Parent.Name}");
Console.WriteLine($"Subnet: {id.Name}");

Tänk dock på att vissa av dessa egenskaper kan vara null. Du kan vanligtvis se av själva ID-strängen vilken typ av resurs-ID som är. Men om du är osäker kontrollerar du om egenskaperna är null.

Exempel: Generator för resursidentifierare

Du kanske inte vill skapa resourceId från en ren stringmanuellt . Varje {ResourceName}Resource klass har en statisk metod som kan hjälpa dig att skapa resursidentifierarsträngen.

ResourceIdentifier resourceId =
    AvailabilitySetResource.CreateResourceIdentifier(
        "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "resourceGroupName",
        "resourceName");

Hantera befintliga resurser

Att utföra åtgärder på resurser som redan finns är ett vanligt användningsfall när du använder hanteringsklientbiblioteken. I det här scenariot har du vanligtvis identifieraren för den resurs som du vill arbeta med som en sträng. Även om den nya objekthierarkin är bra för etablering och arbete inom omfånget för en viss överordnad, är den inte den mest effektiva när det gäller det här specifika scenariot.

Här är ett exempel på hur du kan komma åt ett AvailabilitySetResource objekt och hantera det direkt med dess resursidentifierare:

using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.Resources;
using Azure.ResourceManager.Compute;
using System;
using System.Threading.Tasks;

// Code omitted for brevity

ResourceIdentifier subscriptionId =
    SubscriptionResource.CreateResourceIdentifier("aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee");

ResourceIdentifier resourceId =
    AvailabilitySetResource.CreateResourceIdentifier(
        subscriptionId.SubscriptionId,
        "resourceGroupName",
        "resourceName");

// We construct a new armClient to work with
ArmClient client = new ArmClient(new DefaultAzureCredential());
// Next we get the specific subscription this resource belongs to
SubscriptionResource subscription = client.GetSubscriptionResource(subscriptionId);
// Next we get the specific resource group this resource belongs to
ResourceGroupResource resourceGroup = await subscription.GetResourceGroupAsync(resourceId.ResourceGroupName);
// Finally we get the resource itself
// Note: for this last step in this example, Azure.ResourceManager.Compute is needed
AvailabilitySetResource availabilitySet = await resourceGroup.GetAvailabilitySetAsync(resourceId.Name);

Den här metoden krävde mycket kod och tre API-anrop görs till Azure. Samma sak kan göras med mindre kod och utan NÅGRA API-anrop med hjälp av tilläggsmetoder som vi har angett på själva klienten. Med de här tilläggsmetoderna kan du skicka in en resursidentifierare och hämta en begränsad resursklient. Objektet som returneras är en {ResourceName}-resurs. Eftersom den inte har kontaktat Azure för att hämta data ännu, och om du anropar Data egenskapen utlöser ett undantag, kan du antingen använda HasData egenskapen för att se om resursinstansen innehåller data eller anropa Get metoden eller GetAsync på resursen för att hämta resursdata.

Det föregående exemplet skulle därför se ut så här:

ResourceIdentifier resourceId =
    AvailabilitySetResource.CreateResourceIdentifier(
        "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "resourceGroupName",
        "resourceName");
// We construct a new armClient to work with
ArmClient client = new ArmClient(new DefaultAzureCredential());
// Next we get the AvailabilitySet resource client from the armClient
// The method takes in a ResourceIdentifier but we can use the implicit cast from string
AvailabilitySetResource availabilitySet = client.GetAvailabilitySetResource(resourceId);
// At this point availabilitySet.Data will be null and trying to access it will throw exception
// If we want to retrieve the objects data we can simply call get
availabilitySet = await availabilitySet.GetAsync();
// we now have the data representing the availabilitySet
Console.WriteLine(availabilitySet.Data.Name);

Kontrollera om det finns en resurs

Om du inte är säker på om en resurs som du vill få finns, eller om du bara vill kontrollera om den finns, kan du använda Exists() eller ExistsAsync() metoder som kan anropas från vilken klass som helst {ResourceName}Collection .

Exists() returnerar ett Response<bool> tag ExistsAsync() eftersom dess asynkrona version returnerar en Task<Response<bool>>. Response<bool> I objektet kan du besöka dess Value egenskap för att kontrollera om det finns en resurs. Value är false om resursen inte finns och vice versa.

I tidigare versioner av paket måste du fånga RequestFailedException och granska statuskoden för 404. Med det här nya API:et hoppas vi att detta kan öka utvecklarproduktiviteten och optimera resursåtkomsten.

ArmClient client = new ArmClient(new DefaultAzureCredential());
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
string resourceGroupName = "myRgName";

try
{
    ResourceGroupResource resourceGroup = await subscription.GetResourceGroupAsync(resourceGroupName);
    // At this point, we are sure that myRG is a not null Resource Group, so we can use this object to perform any operations we want.
}
catch (RequestFailedException ex) when (ex.Status == 404)
{
    Console.WriteLine($"Resource Group {resourceGroupName} does not exist.");
}

Nu med dessa bekvämlighetsmetoder kan vi helt enkelt göra följande.

ArmClient client = new ArmClient(new DefaultAzureCredential());
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
string resourceGroupName = "myRgName";

bool exists = await subscription.GetResourceGroups().ExistsAsync(resourceGroupName).Value;

if (exists)
{
    Console.WriteLine($"Resource Group {resourceGroupName} exists.");

    // We can get the resource group now that we know it exists.
    // This does introduce a small race condition where resource group could have been deleted between the check and the get.
    ResourceGroupResource resourceGroup = await subscription.GetResourceGroupAsync(resourceGroupName);
}
else
{
    Console.WriteLine($"Resource Group {rgName} does not exist.");
}

Exempel

Skapa en resursgrupp

// First, initialize the ArmClient and get the default subscription
ArmClient client = new ArmClient(new DefaultAzureCredential());
// Now we get a ResourceGroup collection for that subscription
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
ResourceGroupCollection resourceGroupCollection = subscription.GetResourceGroups();

// With the collection, we can create a new resource group with an specific name
string resourceGroupName = "myRgName";
AzureLocation location = AzureLocation.WestUS2;
ResourceGroupData resourceGroupData = new ResourceGroupData(location);
ResourceGroupResource resourceGroup = (await resourceGroupCollection.CreateOrUpdateAsync(resourceGroupName, resourceGroupData)).Value;

Visa en lista över alla resursgrupper

// First, initialize the ArmClient and get the default subscription
ArmClient client = new ArmClient(new DefaultAzureCredential());
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
// Now we get a ResourceGroup collection for that subscription
ResourceGroupCollection resourceGroupCollection = subscription.GetResourceGroups();
// With GetAllAsync(), we can get a list of the resources in the collection
await foreach (ResourceGroupResource resourceGroup in resourceGroupCollection)
{
    Console.WriteLine(resourceGroup.Data.Name);
}

Uppdatera en resursgrupp

// Note: Resource group named 'myRgName' should exist for this example to work.
ArmClient client = new ArmClient(new DefaultAzureCredential());
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
string resourceGroupName = "myRgName";
ResourceGroupResource resourceGroup = await subscription.GetResourceGroupAsync(resourceGroupName);
resourceGroup = await resourceGroup.AddTagAsync("key", "value");

Ta bort en resursgrupp

ArmClient client = new ArmClient(new DefaultAzureCredential());
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
string resourceGroupName = "myRgName";
ResourceGroupResource resourceGroup = await subscription.GetResourceGroupAsync(resourceGroupName);
await resourceGroup.DeleteAsync();

Mer detaljerade exempel finns i exempel som vi har tillgängliga.

Felsökning

  • Om du har en bugg att rapportera eller har ett förslag kan du skicka in ett problem via GitHub-problem och se till att du lägger till etiketten "Förhandsversion" i problemet.
  • Om du behöver hjälp kontrollerar du tidigare frågor eller ställer nya på StackOverflow med hjälp av Azure- och .NET-taggar.
  • Om du har problem med autentisering kan du läsa dokumentationen DefaultAzureCredential.

Nästa steg

Mer exempelkod

Ytterligare dokumentation

Om du migrerar från den gamla SDK:en till den här förhandsversionen kan du läsa den här migreringsguiden.

Mer information om Azure SDK finns i Azure SDK-versioner.