Ressourcenverwaltung mit dem Azure SDK für .NET

  • Artikel

Die Bibliotheken des Azure SDK für .NET-Verwaltungsebene unterstützt Sie bei der Erstellung, Bereitstellung und Verwaltung von Azure-Ressourcen innerhalb von .NET-Anwendungen. Alle Azure-Dienste verfügen über entsprechende Verwaltungsbibliotheken.

Mit den Verwaltungsbibliotheken (die Namenspaces beginnen mit Azure.ResourceManager, z. B. Azure.ResourceManager.Compute) können Sie Konfigurations- und Bereitstellungsprogramme schreiben, um dieselben Aufgaben auszuführen, zu denen Sie auch das Azure-Portal, die Azure CLI oder andere Tools zur Verwaltung von Ressourcen nutzen können.

Diese Pakete folgen den neuen Azure SDK-Richtlinien, die Kernfunktionen bereitstellen, die von allen Azure SDKs gemeinsam genutzt werden, darunter:

  • Die intuitive Azure-Identitätsbibliothek.
  • Eine HTTP-Pipeline mit benutzerdefinierten Richtlinien.
  • Fehlerbehandlung.
  • Verteilte Ablaufverfolgung.

Hinweis

Sie werden feststellen, dass es sich bei einigen Paketen noch um Vorabversionen handelt. Die schrittweise Freigabe weiterer Bibliotheken für die Verwaltungsebene von Azure-Diensten ist in Arbeit. Wenn Sie nach einem stabilen Versionspaket für eine bestimmte Azure-Ressource suchen und derzeit nur eine Vorabversion verfügbar ist, beheben Sie ein Problem im Azure SDK für .NET Github-Repository

Erste Schritte

Voraussetzungen

Installieren des Pakets

Installieren Sie die NuGet-Pakete Azure Identity und Azure Resource Management für .NET. Beispiel:

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

Authentifizieren des Clients

Die Standardoption zum Erstellen eines authentifizierten Clients ist die Verwendung von DefaultAzureCredential. Da alle Verwaltungs-APIs denselben Endpunkt verwenden, muss nur eine oberste Ebene ArmClient erstellt werden, um mit Ressourcen zu interagieren.

Um sich bei Azure zu authentifizieren und einen ArmClient zu erstellen, instanziieren Sie einen ArmClient mit den entsprechenden Anmeldedaten:

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

// Code omitted for brevity

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

Weitere Informationen zur Azure.Identity.DefaultAzureCredential-Klasse finden Sie unter DefaultAzureCredential-Klasse.

Management SDK-Spickzettel

Um mit dem Azure Management SDK für .NET zu beginnen, stellen Sie sich vor, Sie haben eine Aufgabe zum Erstellen/Auflisten/Aktualisieren/Löschen eines typischen Azure Service Bus-Namespaces. Führen Sie die folgenden Schritte aus:

  1. Authentifizieren Sie sich bei dem Abonnement und der Ressourcengruppe, an dem Sie arbeiten möchten.
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. Suchen Sie die entsprechende Methode zum Verwalten Ihrer Azure-Ressource.
Vorgang Methode
Abrufen einer Ressource mit Ressourcenbezeichner client.GetServiceBusQueueResource(ResourceIdentifier resourceIdentifier)
List resourceGroup.GetServiceBusNamespaces()
Index resourceGroup.GetServiceBusNamespace(string servicebusNamespaceName)
Hinzufügen/Aktualisieren resourceGroup.GetServiceBusNamespaces().CreateOrUpdate(Azure.WaitUntil waitUntil, string name, ServiceBusNamespaceData data)
Enthält resourceGroup.GetServiceBusNamespaces().Exists(string servicebusNamespaceName)
Löschen client.GetServiceBusQueueResource(ResourceIdentifior resourceIdentifior).Delete() oder resourceGroup.GetServiceBusNamespace(string servicebusNamespaceName).Delete()

Denken Sie daran, dass alle Azure-Ressourcen, einschließlich der Ressourcengruppe selbst, vom entsprechenden Verwaltungs-SDK mithilfe von Code wie im obigen Beispiel verwaltet werden können. Um das richtige Azure Management SDK-Paket zu finden, suchen Sie nach Paketen mit dem folgenden Muster Azure.ResourceManager.{ResourceProviderName}.

Weitere Informationen zum Ressourcenbezeichner finden Sie unter Strukturierter Ressourcenbezeichner.

Wichtige Begriffe

Grundlegendes zur Azure-Ressourcenhierarchie

Um sowohl die Anzahl der Clients, die zum Ausführen gängiger Aufgaben erforderlich sind, als auch die Menge der redundanten Parameter zu reduzieren, die jeder dieser Clients verwendet, haben wir eine Objekthierarchie im SDK eingeführt, die die Objekthierarchie in Azure imitiert. Jeder Ressourcenclient im SDK verfügt über Methoden für den Zugriff auf die Ressourcenclients der ihm untergeordneten Elemente, die bereits dem richtigen Abonnement und der richtigen Ressourcengruppe angepasst sind.

Zu diesem Zweck werden drei Standardtypen für alle Ressourcen in Azure eingeführt:

{ResourceName}Ressource-Klasse

Dieser Typ stellt ein vollständiges Ressourcenclientobjekt dar, das eine Data-Eigenschaft enthält, die die Details als {ResourceName}Data-Typ verfügbar macht. Es hat auch Zugriff auf alle Vorgänge für diese Ressource, ohne Bereichsparameter wie die Abonnement-ID oder den Ressourcennamen übergeben zu müssen. Dadurch können Vorgänge bequem direkt für das Ergebnis von Listenaufrufen ausgeführt werden, da jetzt alles als vollständiger Ressourcenclient zurückgegeben wird.

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

Dieser Typ stellt das Modell dar, das eine bestimmte Ressource ausmacht. In der Regel handelt es sich dabei um die Antwortdaten eines Dienstaufrufs wie HTTP GET, und es werden Details zur zugrunde liegenden Ressource bereitgestellt. Zuvor wurde dies durch eine Model-Klasse dargestellt.

{ResourceName}Collection-Klasse

Dieser Typ stellt die Vorgänge dar, die Sie für eine Sammlung von Ressourcen ausführen können, die zu einer bestimmten übergeordneten Ressource gehören. Dieses Objekt bietet die meisten der logischen Sammlungsvorgänge.

Sammlungsverhalten Sammlungsmethode
Iterieren/Auflisten GetAll()
Index Get(Zeichenfolgenname)
Hinzufügen CreateOrUpdate(Azure.WaitUntil waitUntil, String name, {ResourceName}Data)
Enthält Exists(Zeichenfolgenname)

In den meisten Fällen ist das übergeordnete Element einer Ressource ResourceGroup, aber in einigen Fällen verfügt eine Ressource selbst über eine Unterressource, z. B. ist ein Subnetz ein untergeordnetes Element eines VirtualNetwork. ResourceGroup selbst ist ein untergeordnetes Element eines Abonnements

Zusammenfügen des Gesamtbilds

Stellen Sie sich vor, dass unser Unternehmen verlangt, dass alle virtuellen Computer mit dem Besitzer gekennzeichnet werden. Wir haben die Aufgabe, ein Programm zu schreiben, um das Tag allen fehlenden virtuellen Computern in einer bestimmten Ressourcengruppe hinzuzufügen.

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

Strukturierter Ressourcenbezeichner

Ressourcen-IDs enthalten nützliche Informationen zur Ressource selbst, sind jedoch einfache Zeichenfolgen, die analysiert werden müssen. Anstatt Ihre eigene Analyselogik zu implementieren, können Sie ein ResourceIdentifier-Objekt verwenden, das die Analyse für Sie durchführt.

Beispiel: Analyse einer ID mithilfe eines ResourceIdentifier-Objekts

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

Beachten Sie jedoch, dass einige dieser Eigenschaften NULL sein können. Sie können in der Regel anhand der ID-Zeichenfolge erkennen, um welchen Typ es sich bei einer Ressourcen-ID handelt. Wenn Sie sich jedoch nicht sicher sind, überprüfen Sie, ob die Eigenschaften NULL sind.

Beispiel: Resource Identifier Generator

Möglicherweise möchten Sie die resourceId nicht manuell aus einem reinen string erstellen. Jede {ResourceName}Resource-Klasse verfügt über eine statische Methode, mit der Sie die Ressourcenbezeichnerzeichenfolge erstellen können.

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

Verwalten vorhandener Ressourcen

Das Ausführen von Vorgängen für bereits vorhandene Ressourcen ist ein häufiger Anwendungsfall bei Verwendung der Verwaltungsclientbibliotheken. In diesem Szenario verfügen Sie in der Regel in Form einer Zeichenfolge über den Bezeichner der Ressource, an der Sie arbeiten möchten. Die neue Objekthierarchie ist zwar ideal für die Bereitstellung und die Arbeit innerhalb des Bereichs eines bestimmten übergeordneten Elements, aber in diesem speziellen Szenario nicht die effizienteste Lösung.

Das folgende Beispiel zeigt, wie Sie auf ein AvailabilitySetResource-Objekt zugreifen und es direkt mit seinem Ressourcenbezeichner verwalten:

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

Dieser Ansatz erforderte viel Code und drei API-Aufrufe an Azure. Dasselbe kann mit weniger Code und ohne API-Aufrufe mithilfe von Erweiterungsmethoden erfolgen, die wir auf dem Client selbst bereitgestellt haben. Mit diesen Erweiterungsmethoden können Sie einen Ressourcenbezeichner übergeben und einen bereichsbezogenen Ressourcenclient abrufen. Das zurückgegebene Objekt ist eine {ResourceName}Ressource. Da Azure zum Abrufen der Daten noch nicht erreicht wurde, löst das Aufrufen der Eigenschaft Data eine Ausnahme aus. Sie können entweder die Eigenschaft HasData verwenden, um zu ermitteln, ob die Ressourceninstanz Daten enthält, oder die Methode Get oder GetAsync für die Ressource aufrufen, um die Ressourcendaten abzurufen.

Das vorherige Beispiel würde daher folgendermaßen aussehen:

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

Überprüfen, ob eine Resource vorhanden ist

Wenn Sie nicht sicher sind, ob eine Ressource, die Sie abrufen möchten, vorhanden ist, oder wenn Sie nur überprüfen möchten, ob sie vorhanden ist, können Sie die Methoden Exists() oder ExistsAsync() verwenden, die aus jeder {ResourceName}Collection-Klasse aufgerufen werden können.

Exists() gibt Response<bool> zurück, während ExistsAsync() als asynchrone Version Task<Response<bool>> zurückgibt. Im Response<bool>-Objekt können Sie die Value-Eigenschaft anzeigen, um zu überprüfen, ob eine Ressource vorhanden ist. Value ist false, wenn die Ressource nicht vorhanden ist und umgekehrt.

In früheren Versionen von Paketen müssten Sie RequestFailedException abfangen und den Statuscode für 404 überprüfen. Mit dieser neuen API hoffen wir, dass die Entwicklerproduktivität gesteigert und der Ressourcenzugriff optimiert werden kann.

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

Mit diesen praktischen Methoden können wir nun einfach folgende Aktionen ausführen.

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

Beispiele

Erstellen einer Ressourcengruppe

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

Auflisten aller Ressourcengruppen

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

Aktualisieren einer Ressourcengruppe

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

Löschen einer Ressourcengruppe

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

Ausführlichere Beispiele finden Sie in den verfügbaren Beispielen.

Problembehandlung

  • Wenn Sie einen Fehler melden oder einen Vorschlag haben, melden Sie ein Problem über die Issue-Funktion in GitHub, und stellen Sie sicher, dass Sie dem Problem die Bezeichnung „Preview“ hinzufügen.
  • Wenn Sie Hilfe benötigen, überprüfen Sie frühere Fragen, oder stellen Sie neue Fragen mit Azure- und .NET-Tags in StackOverflow.
  • Wenn Sie Probleme mit der Authentifizierung haben, nutzen Sie die Dokumentation zu DefaultAzureCredential.

Nächste Schritte

Weiterer Beispielcode

Zusätzliche Dokumentation

Wenn Sie vom alten SDK zu dieser Vorschau migrieren, lesen Sie diesen Migrationsleitfaden.

Weitere Informationen zum Azure SDK finden Sie unter Azure SDK Releases.