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

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 (namnområden 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 nya Riktlinjer för Azure SDK, som ger kärnfunktioner som delas mellan alla Azure SDK:er, inklusive:

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

Anteckning

Du kanske märker att vissa paket fortfarande är förhandsversioner. Stegvisa versioner av ytterligare Azure-tjänsters hanteringsplansbibliotek befinner sig i process. 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.

Sätta igång

Förutsättningar

• En Azure-prenumeration.
• En TokenCredential- implementering, till exempel en autentiseringstyp för Azure Identity-biblioteket.

Installera paketet

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

PowerShell

PowerShell

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

.NET CLI

.NET CLI

dotnet add package Azure.Identity
dotnet add package Azure.ResourceManager
dotnet add package Azure.ResourceManager.Resources
dotnet add package Azure.ResourceManager.Compute
dotnet add 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, behövs det bara skapa en ArmClient för att kunna interagera med resurser.

För att autentisera med Azure och skapa en ArmClient, instansiera en ArmClient med de angivna autentiseringsuppgifterna.

C#

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 Azure.Identity.DefaultAzureCredential finns i DefaultAzureCredential Class.

Administrations-SDK-fusklapp

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.

C#

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.

Operation	Metod
Hämta en resurs med resursidentifierare	client.GetServiceBusQueueResource(ResourceIdentifier resourceIdentifier)
Lista	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)
Ta bort	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.

Viktiga begrepp

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 anpassade till rätt prenumeration och resursgrupp.

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

{ResourceName}Resource-klass

Den här typen representerar ett fullständigt resursklientobjekt som innehåller en egenskap Data som exponerar informationen som en {ResourceName}Data typ. 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.

C#

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}Data-klass

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 Model-klass.

{ResourceName}Collection-klass

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)
Addera	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 en underresurs, till exempel är en Undernät en del av en VirtualNetwork. ResourceGroup är en underordnad prenumeration

Att samla 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.

C#

// 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

C#

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 manuellt från en ren string. Varje {ResourceName}Resource-klass har en statisk metod som kan hjälpa dig att skapa resursidentifierarsträngen.

C#

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 tilldelning och arbete inom omfånget för en given ö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:

C#

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}Resource. Eftersom den inte har kontaktat Azure för att hämta data ännu och anropar egenskapen Data genererar undantag, kan du antingen använda egenskapen HasData för att se om resursinstansen innehåller data eller anropa metoden Get eller GetAsync på resursen för att hämta resursdata.

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

C#

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 {ResourceName}Collection klass som helst.

Exists() returnerar en Response<bool>, medan ExistsAsync() i sin asynkrona version returnerar en Task<Response<bool>>. I Response<bool>-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.

C#

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.

C#

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

C#

// 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

C#

// 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

C#

// 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

C#

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 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 kan du kontrollera tidigare frågoreller ställa 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

• Hantera resursgrupper
• Skapa ett virtuellt nätverk
• kodexempel för .NET-hanteringsbiblioteket

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.