Sdílet prostřednictvím

Správa prostředků pomocí sady Azure SDK pro .NET

  • Článek

Knihovny roviny správy Azure SDK pro .NET vám pomůžou vytvářet, zřizovat a spravovat prostředky Azure z aplikací .NET. Všechny služby Azure mají odpovídající knihovny pro správu.

S knihovnami pro správu (obory názvů začínajícími Azure.ResourceManagernapříklad Azure.ResourceManager.Compute) můžete psát programy konfigurace a nasazení pro provádění stejných úloh, které můžete provádět prostřednictvím webu Azure Portal, Azure CLI nebo jiných nástrojů pro správu prostředků.

Tyto balíčky se řídí novými pokyny sady Azure SDK, které poskytují základní funkce sdílené mezi všemi sadami Azure SDK, včetně těchto:

  • Intuitivní knihovna identit Azure.
  • Kanál HTTP s vlastními zásadami.
  • Zpracování chyb
  • Distribuované trasování

Poznámka:

Můžete si všimnout, že některé balíčky jsou stále předběžné verze, postupné verze dalších knihoven roviny správy služeb Azure jsou v procesu. Pokud hledáte stabilní balíček verzí pro konkrétní prostředek Azure a aktuálně je k dispozici pouze předběžná verze, vytvořte problém v úložišti Azure SDK pro .NET na GitHubu.

Začínáme

Požadavky

Nainstalujte balíček .

Nainstalujte balíčky NuGet pro správu prostředků Azure a Identity a Azure pro .NET. Příklad:

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

Ověření klienta

Výchozí možností vytvoření ověřeného klienta je použití DefaultAzureCredential. Vzhledem k tomu, že všechna rozhraní API pro správu procházejí stejným koncovým bodem, aby bylo možné pracovat s prostředky, je potřeba vytvořit pouze jednu nejvyšší úroveň ArmClient .

Pokud se chcete ověřit pomocí Azure a vytvořit ArmClientinstanci zadaných ArmClient přihlašovacích údajů:

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

// Code omitted for brevity

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

Další informace o Azure.Identity.DefaultAzureCredential třídě naleznete v tématu DefaultAzureCredential Třída.

Stručná nápověda k sadě SDK pro správu

Pokud chcete začít se sadou Sdk pro správu Azure pro .NET, představte si, že máte úlohu vytvoření, výpisu, aktualizace nebo odstranění typického oboru názvů služby Azure Service Bus, postupujte takto:

  1. Ověřte předplatné a skupinu prostředků, na které chcete pracovat.
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. Vyhledejte odpovídající metodu pro správu prostředku Azure.
Operace metoda
Získání prostředku s identifikátorem prostředku client.GetServiceBusQueueResource(ResourceIdentifier resourceIdentifier)
List resourceGroup.GetServiceBusNamespaces()
Index resourceGroup.GetServiceBusNamespace(string servicebusNamespaceName)
Přidání nebo aktualizace resourceGroup.GetServiceBusNamespaces().CreateOrUpdate(Azure.WaitUntil waitUntil, string name, ServiceBusNamespaceData data)
Contains resourceGroup.GetServiceBusNamespaces().Exists(string servicebusNamespaceName)
Odstranění client.GetServiceBusQueueResource(ResourceIdentifior resourceIdentifior).Delete() nebo resourceGroup.GetServiceBusNamespace(string servicebusNamespaceName).Delete()

Nezapomeňte, že všechny prostředky Azure, včetně samotné skupiny prostředků, je možné spravovat pomocí odpovídající sady SDK pro správu pomocí kódu podobného výše uvedenému příkladu. Pokud chcete najít správný balíček sady SDK pro správu Azure, vyhledejte balíčky s názvem s následujícím vzorem Azure.ResourceManager.{ResourceProviderName}.

Další informace o resourceIdentifieru najdete v identifikátoru strukturovaného prostředku.

Klíčové koncepty

Principy hierarchie prostředků Azure

Abychom snížili počet klientů potřebných k provádění běžných úloh a počet redundantních parametrů, které každý z těchto klientů převezme, zavedli jsme v sadě SDK hierarchii objektů, která napodobuje hierarchii objektů v Azure. Každý klient prostředků v sadě SDK má metody pro přístup k klientům prostředků podřízených položek, které jsou již vymezeny na správné předplatné a skupinu prostředků.

Abychom toho dosáhli, představujeme tři standardní typy pro všechny prostředky v Azure:

{ResourceName} Třída prostředků

Tento typ představuje úplný objekt klienta prostředku, který obsahuje vlastnost Data zobrazující podrobnosti jako datový typ {ResourceName} . Má také přístup ke všem operacím s tímto prostředkem, aniž by bylo nutné předávat parametry oboru, jako je ID předplatného nebo název prostředku. Díky tomu můžete přímo spouštět operace s výsledkem volání seznamu, protože vše se teď vrátí jako úplný klient prostředků.

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} Datová třída

Tento typ představuje model, který tvoří daný prostředek. Obvykle se jedná o data odpovědí z volání služby, jako je HTTP GET, a poskytuje podrobnosti o podkladovém prostředku. Dříve ji reprezentovala třída modelu .

{ResourceName} Collection – třída

Tento typ představuje operace, které můžete provést s kolekcí prostředků patřících do konkrétního nadřazeného prostředku. Tento objekt poskytuje většinu operací logické kolekce.

Chování kolekce Collection – metoda
Iterace nebo seznam GetAll()
Index Get(název řetězce)
Přidání CreateOrUpdate(Azure.WaitUntil waitUntil, název řetězce, {ResourceName}Data)
Contains Exists(název řetězce)

Ve většině případů je nadřazený prostředek ResourceGroup, ale v některých případech má samotný prostředek dílčí prostředek, například podsíť je podřízená službě VirtualNetwork. Samotná skupina prostředků je podřízenou položkou předplatného .

Spojení všech součástí dohromady

Představte si, že naše společnost vyžaduje, aby všechny virtuální počítače byly označené vlastníkem. Máme za úkol napsat program, který přidá značku do všech chybějících virtuálních počítačů v dané skupině prostředků.

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

Identifikátor strukturovaného prostředku

ID prostředků obsahují užitečné informace o samotném prostředku, ale jedná se o prosté řetězce, které je potřeba analyzovat. Místo implementace vlastní logiky analýzy můžete použít ResourceIdentifier objekt, který provede analýzu za vás.

Příklad: Analýza ID pomocí objektu ResourceIdentifier

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

Mějte však na paměti, že některé z těchto vlastností mohou být null. Obvykle to poznáte pomocí samotného řetězce ID, který typ ID prostředku je. Pokud si ale nejste jistí, zkontrolujte, jestli jsou vlastnosti null.

Příklad: Generátor identifikátorů prostředků

Je možné, že nebudete chtít ručně vytvořit resourceId z čistého string. Každá {ResourceName}Resource třída má statickou metodu, která vám může pomoct vytvořit řetězec identifikátoru prostředku.

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

Správa existujících prostředků

Provádění operacísch V tomto scénáři obvykle máte identifikátor prostředku, na který chcete pracovat jako řetězec. I když je nová hierarchie objektů skvělá pro zřizování a práci v rámci rozsahu daného nadřazeného objektu, není to nejúčinnější, pokud jde o tento konkrétní scénář.

Tady je příklad, jak můžete získat přístup k objektu AvailabilitySetResource a spravovat ho přímo pomocí jeho identifikátoru prostředku:

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

Tento přístup vyžaduje velké množství kódu a tři volání rozhraní API se provádí v Azure. Totéž lze provést s menším kódem a bez jakýchkoli volání rozhraní API pomocí rozšiřujících metod, které jsme poskytli na samotném klientovi. Tyto metody rozšíření umožňují předat identifikátor prostředku a načíst klienta prostředků s vymezeným oborem. Vrácený objekt je {ResourceName}Zdroj. Vzhledem k tomu, že se ještě nedotáhl k Azure, aby načetl data, vyvolání Data vlastnosti vyvolá výjimku, můžete použít HasData vlastnost k tomu, abyste zjistili, jestli instance prostředku obsahuje data, nebo voláním Get nebo GetAsync metodou prostředku načíst data prostředku.

Předchozí příklad by tedy vypadal takto:

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

Kontrola, jestli prostředek existuje

Pokud si nejste jistí, jestli prostředek, který chcete získat, nebo chcete jenom zkontrolovat, jestli existuje, můžete použít Exists() nebo ExistsAsync() použít metody, které je možné vyvolat z libovolné {ResourceName}Collection třídy.

Exists()Response<bool> vrátí nějakou dobuExistsAsync(), protože její asynchronní verze vrátí Task<Response<bool>>hodnotu . V objektu Response<bool> můžete navštívit jeho Value vlastnost a zkontrolovat, jestli prostředek existuje. To Value znamená false , že prostředek neexistuje a naopak.

V předchozích verzích balíčků byste museli zachytit RequestFailedException stavový kód 404 a zkontrolovat ho. S tímto novým rozhraním API doufáme, že to může zvýšit produktivitu vývojářů a optimalizovat přístup k prostředkům.

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

Teď s těmito metodami pohodlí můžeme jednoduše provést následující akce.

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

Příklady

Vytvoření skupiny zdrojů

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

Výpis všech skupin prostředků

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

Aktualizace skupiny prostředků

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

Odstranění skupiny prostředků

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

Podrobnější příklady najdete v ukázkách , které máme k dispozici.

Řešení problému

  • Pokud máte chybu nahlásit nebo navrhnout, vytvořte problém prostřednictvím problémů GitHubu a ujistěte se, že k problému přidáte popisek Preview.
  • Pokud potřebujete pomoc, podívejte se na předchozí otázky nebo položte nové dotazy na StackOverflow pomocí značek Azure a .NET.
  • Pokud máte potíže s ověřováním, přečtěte si dokumentaci k DefaultAzureCredential.

Další kroky

Další ukázkový kód

Další dokumentace

Pokud migrujete ze staré sady SDK do této verze Preview, projděte si tohoto průvodce migrací.

Další informace o sadě Azure SDK najdete v tématu Vydání sady Azure SDK.