Resourcebeheer met behulp van de Azure SDK voor .NET

Met de Azure SDK voor .NET-beheervlakbibliotheken kunt u Azure-resources maken, inrichten en beheren vanuit .NET-toepassingen. Alle Azure-services hebben bijbehorende beheerbibliotheken.

Met de beheerbibliotheken (naamruimten die beginnen met Azure.ResourceManagerbijvoorbeeld Azure.ResourceManager.Compute), kunt u configuratie- en implementatieprogramma's schrijven om dezelfde taken uit te voeren die u kunt uitvoeren via de Azure-portal, Azure CLI of andere hulpprogramma's voor resourcebeheer.

Deze pakketten volgen de nieuwe Azure SDK-richtlijnen, die kernmogelijkheden bieden die worden gedeeld tussen alle Azure SDK's, waaronder:

• De intuïtieve Azure Identity-bibliotheek.
• Een HTTP-pijplijn met aangepast beleid.
• Foutafhandeling.
• Gedistribueerde tracering.

Notitie

U ziet mogelijk dat sommige pakketten nog steeds een voorlopige versie zijn, gefaseerde versies van de beheervlakbibliotheken van Azure-services worden verwerkt. Als u op zoek bent naar een stabiel versiepakket voor een bepaalde Azure-resource en momenteel alleen een voorlopige versie beschikbaar is, dient u een probleem op te lossen in de Azure SDK voor .NET Github-opslagplaats

Aan de slag

Vereisten

• Een Azure-abonnement
• Een TokenCredential-implementatie , zoals een referentietype azure-identiteitsbibliotheek.

Het pakket installeren

Installeer de NuGet-pakketten voor Azure Identity en Azure-resourcebeheer voor .NET. Voorbeeld:

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

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

De client verifiëren

De standaardoptie voor het maken van een geverifieerde client is om te gebruiken DefaultAzureCredential. Aangezien alle beheer-API's hetzelfde eindpunt doorlopen om te kunnen communiceren met resources, hoeft er slechts één niveau op het hoogste niveau ArmClient te worden gemaakt.

Als u wilt verifiëren met Azure en een ArmClientinstantie wilt maken, maakt u een instantie van een ArmClient bepaalde referenties:

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

// Code omitted for brevity

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

Zie DefaultAzureCredential Class voor meer informatie over de Azure.Identity.DefaultAzureCredential klasse.

Cheatsheet voor beheer-SDK

Als u aan de slag wilt gaan met de Azure Management SDK voor .NET, stelt u zich voor dat u een taak hebt om een typische Azure Service Bus-naamruimte te maken/bij te werken/te verwijderen. Volg deze stappen:

1. Verifieer bij het abonnement en de resourcegroep waaraan u wilt werken.

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. Zoek de bijbehorende methode om uw Azure-resource te beheren.

Bewerking	Methode
Een resource ophalen met resource-id	client.GetServiceBusQueueResource(ResourceIdentifier resourceIdentifier)
List	resourceGroup.GetServiceBusNamespaces()
Index	resourceGroup.GetServiceBusNamespace(string servicebusNamespaceName)
Toevoegen/bijwerken	resourceGroup.GetServiceBusNamespaces().CreateOrUpdate(Azure.WaitUntil waitUntil, string name, ServiceBusNamespaceData data)
Contains	resourceGroup.GetServiceBusNamespaces().Exists(string servicebusNamespaceName)
Delete	client.GetServiceBusQueueResource(ResourceIdentifior resourceIdentifior).Delete() of resourceGroup.GetServiceBusNamespace(string servicebusNamespaceName).Delete()

Onthoud dat alle Azure-resources, inclusief de resourcegroep zelf, kunnen worden beheerd door de bijbehorende beheer-SDK met behulp van code die vergelijkbaar is met het bovenstaande voorbeeld. Als u het juiste Azure Management SDK-pakket wilt vinden, zoekt u naar pakketten met de naam met het volgende patroon Azure.ResourceManager.{ResourceProviderName}.

Raadpleeg gestructureerde resource-id voor meer informatie over de ResourceIdentifier.

Belangrijke concepten

Informatie over Azure-resourcehiërarchie

Om het aantal clients te verminderen dat nodig is voor het uitvoeren van algemene taken en het aantal redundante parameters dat elk van deze clients neemt, hebben we een objecthiërarchie geïntroduceerd in de SDK die de objecthiërarchie in Azure nabootst. Elke resourceclient in de SDK heeft methoden voor toegang tot de resourceclients van de onderliggende elementen die al zijn gericht op het juiste abonnement en de juiste resourcegroep.

Hiervoor introduceren we drie standaardtypen voor alle resources in Azure:

{ResourceName} Resourceklasse

Dit type vertegenwoordigt een volledig resourceclientobject dat een gegevenseigenschap bevat die de details weergeeft als een {ResourceName}-gegevenstype . Het heeft ook toegang tot alle bewerkingen op die resource zonder dat u bereikparameters zoals abonnements-id of resourcenaam hoeft door te geven. Dit maakt het handig om bewerkingen rechtstreeks uit te voeren op het resultaat van lijstoproepen, omdat alles nu wordt geretourneerd als een volledige resourceclient.

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} Gegevensklasse

Dit type vertegenwoordigt het model waaruit een bepaalde resource bestaat. Dit zijn doorgaans de antwoordgegevens van een service-aanroep zoals HTTP GET en bevatten details over de onderliggende resource. Voorheen werd dit vertegenwoordigd door een modelklasse .

{ResourceName} Verzamelingsklasse

Dit type vertegenwoordigt de bewerkingen die u kunt uitvoeren voor een verzameling resources die behoren tot een specifieke bovenliggende resource. Dit object biedt de meeste logische verzamelingsbewerkingen.

Gedrag van verzameling	Verzamelingsmethode
Herhalen/lijst	GetAll()
Index	Get(tekenreeksnaam)
Toevoegen	CreateOrUpdate(Azure.WaitUntil waitUntil, tekenreeksnaam, {ResourceName}Gegevensgegevens)
Contains	Exists(tekenreeksnaam)

In de meeste gevallen is het bovenliggende element van een resource ResourceGroup, maar in sommige gevallen heeft een resource zelf subresource, bijvoorbeeld een subnet een onderliggend element van een VirtualNetwork. ResourceGroup zelf is een onderliggend element van een abonnement

Alles samenvoegen

Stel dat voor ons bedrijf alle virtuele machines moeten worden gelabeld met de eigenaar. We moeten een programma schrijven om de tag toe te voegen aan ontbrekende virtuele machines in een bepaalde resourcegroep.

// 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());
   }
}

Gestructureerde resource-id

Resource-id's bevatten nuttige informatie over de resource zelf, maar ze zijn gewone tekenreeksen die moeten worden geparseerd. In plaats van uw eigen parseringslogica te implementeren, kunt u een ResourceIdentifier object gebruiken dat de parsering voor u uitvoert.

Voorbeeld: Een id parseren met behulp van een ResourceIdentifier-object

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}");

Houd er echter rekening mee dat sommige van deze eigenschappen null kunnen zijn. U kunt dit meestal zien door de id-tekenreeks zelf welk type een resource-id is. Maar als u het niet zeker weet, controleert u of de eigenschappen null zijn.

Voorbeeld: Resource Identifier Generator

Misschien wilt u de resourceId niet handmatig maken van een pure string. Elke {ResourceName}Resource klasse heeft een statische methode waarmee u de tekenreeks voor de resource-id kunt maken.

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

Bestaande resources beheren

Het uitvoeren van bewerkingen op resources die al bestaan, is een veelvoorkomende use-case bij het gebruik van de beheerclientbibliotheken. In dit scenario hebt u meestal de id van de resource waaraan u wilt werken als een tekenreeks. Hoewel de nieuwe objecthiërarchie ideaal is voor het inrichten en werken binnen het bereik van een bepaald bovenliggend item, is het niet de meest efficiënte als het gaat om dit specifieke scenario.

Hier volgt een voorbeeld van hoe u toegang krijgt tot een AvailabilitySetResource object en het rechtstreeks beheert met de bijbehorende resource-id:

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);

Deze benadering vereist veel code en drie API-aanroepen worden naar Azure uitgevoerd. Hetzelfde kan met minder code en zonder API-aanroepen worden gedaan met behulp van extensiemethoden die we op de client zelf hebben opgegeven. Met deze extensiemethoden kunt u een resource-id doorgeven en een scoped resourceclient ophalen. Het geretourneerde object is een {ResourceName}-resource. Omdat azure nog niet heeft bereikt om de gegevens op te halen, genereert het aanroepen van de Data eigenschap een uitzondering. U kunt de eigenschap gebruiken HasData om te zien of het resource-exemplaar een gegevens bevat of de Get of GetAsync methode voor de resource aanroept om de resourcegegevens op te halen.

Het vorige voorbeeld ziet er dan als volgt uit:

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);

Controleren of er een resource bestaat

Als u niet zeker weet of een resource die u wilt ophalen bestaat of als u alleen wilt controleren of deze bestaat, kunt u deze gebruiken of ExistsAsync() methoden gebruikenExists(), die vanuit elke {ResourceName}Collection klasse kunnen worden aangeroepen.

Exists() retourneert een Response<bool> tijdje ExistsAsync() als de asynchrone versie een Task<Response<bool>>. In het Response<bool> object kunt u de eigenschap ervan bezoeken Value om te controleren of er een resource bestaat. Dit Value is false als de resource niet bestaat en vice versa.

In eerdere versies van pakketten moet u de RequestFailedException statuscode voor 404 vangen en inspecteren. Met deze nieuwe API hopen we dat dit de productiviteit van ontwikkelaars kan verbeteren en de toegang tot resources kan optimaliseren.

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 met deze handige methoden kunnen we gewoon het volgende doen.

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.");
}

Voorbeelden

Een brongroep maken

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

Alle resourcegroepen weergeven

// 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);
}

Een resourcegroep bijwerken

// 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");

Een resourcegroep verwijderen

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

Bekijk voorbeelden die we beschikbaar hebben voor meer gedetailleerde voorbeelden.

Probleemoplossing

• Als u een fout hebt om te rapporteren of een suggestie hebt, dient u een probleem in via GitHub-problemen en zorgt u ervoor dat u het label Preview toevoegt aan het probleem.
• Als u hulp nodig hebt, kunt u eerdere vragen controleren of nieuwe vragen stellen op StackOverflow met behulp van Azure- en .NET-tags.
• Raadpleeg de documentatie defaultAzureCredential als u problemen ondervindt met verificatie.

Volgende stappen

Meer voorbeeldcode

• Resourcegroepen beheren
• Een virtueel netwerk maken
• Codevoorbeelden voor .NET-beheerbibliotheek

Aanvullende documentatie

Als u van de oude SDK naar deze preview migreert, raadpleegt u deze migratiehandleiding.

Zie Azure SDK-releases voor meer informatie over Azure SDK.