Partilhar via

Gerenciamento de recursos usando o SDK do Azure para .NET

  • Artigo

O SDK do Azure para bibliotecas de plano de gerenciamento .NET ajudará você a criar, provisionar e gerenciar recursos do Azure a partir de aplicativos .NET. Todos os serviços do Azure têm bibliotecas de gerenciamento correspondentes.

Com as bibliotecas de gerenciamento (namespaces começando com Azure.ResourceManager, por exemplo, Azure.ResourceManager.Compute), você pode escrever programas de configuração e implantação para executar as mesmas tarefas que você pode através do portal do Azure, CLI do Azure ou outras ferramentas de gerenciamento de recursos.

Esses pacotes seguem as novas diretrizes do SDK do Azure, que fornecem recursos principais que são compartilhados entre todos os SDKs do Azure, incluindo:

  • A biblioteca intuitiva do Azure Identity.
  • Um pipeline HTTP com políticas personalizadas.
  • Tratamento de erros.
  • Rastreamento distribuído.

Nota

Você pode notar que alguns pacotes ainda são versão de pré-lançamento, versões em fases de bibliotecas de plano de gerenciamento de serviços adicionais do Azure estão em processo. Se você estiver procurando um pacote de versão estável para um recurso azure específico e atualmente apenas uma versão de pré-lançamento está disponível, levante um problema no repositório Github do SDK do Azure para .NET

Começar agora

Pré-requisitos

Instalar o pacote

Instale o Azure Identity e os pacotes NuGet de gerenciamento de recursos do Azure para .NET. Por exemplo:

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

Autenticar o cliente

A opção padrão para criar um cliente autenticado é usar DefaultAzureCredentialo . Como todas as APIs de gerenciamento passam pelo mesmo ponto de extremidade, para interagir com recursos, apenas um nível ArmClient superior precisa ser criado.

Para autenticar com o Azure e criar um ArmClient, instancie uma ArmClient determinada credencial:

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

// Code omitted for brevity

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

Para obter mais informações sobre a Azure.Identity.DefaultAzureCredential classe, consulte DefaultAzureCredential Class.

Folha de cheat do SDK de gerenciamento

Para começar a usar o SDK de gerenciamento do Azure para .NET, imagine que você tenha uma tarefa para criar/listar/atualizar/excluir um namespace típico do barramento de serviço do Azure, siga estas etapas:

  1. Autentique-se na assinatura e no grupo de recursos em que deseja trabalhar.
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. Encontre o método correspondente para gerenciar seu recurso do Azure.
Operação Método
Obter um recurso com identificador de recurso client.GetServiceBusQueueResource(ResourceIdentifier resourceIdentifier)
Listagem resourceGroup.GetServiceBusNamespaces()
Índice resourceGroup.GetServiceBusNamespace(string servicebusNamespaceName)
Adicionar/Atualizar resourceGroup.GetServiceBusNamespaces().CreateOrUpdate(Azure.WaitUntil waitUntil, string name, ServiceBusNamespaceData data)
Contains resourceGroup.GetServiceBusNamespaces().Exists(string servicebusNamespaceName)
Delete client.GetServiceBusQueueResource(ResourceIdentifior resourceIdentifior).Delete() ou resourceGroup.GetServiceBusNamespace(string servicebusNamespaceName).Delete()

Lembre-se de que todos os recursos do Azure, incluindo o próprio grupo de recursos, podem ser gerenciados pelo SDK de gerenciamento correspondente usando um código semelhante ao exemplo acima. Para encontrar o pacote correto do SDK de gerenciamento do Azure, procure pacotes nomeados com o seguinte padrão Azure.ResourceManager.{ResourceProviderName}.

Para saber mais sobre o ResourceIdentifier, consulte Structured Resource Identifier.

Conceitos-chave

Noções básicas sobre a hierarquia de recursos do Azure

Para reduzir o número de clientes necessários para executar tarefas comuns e o número de parâmetros redundantes que cada um desses clientes utiliza, introduzimos uma hierarquia de objetos no SDK que imita a hierarquia de objetos no Azure. Cada cliente de recurso no SDK tem métodos para acessar os clientes de recursos de seus filhos que já estão com escopo para a assinatura adequada e o grupo de recursos.

Para fazer isso, estamos introduzindo três tipos padrão para todos os recursos no Azure:

{ResourceName} Classe de recurso

Esse tipo representa um objeto de cliente de recurso completo que contém uma propriedade Data expondo os detalhes como um tipo {ResourceName}Data . Ele também tem acesso a todas as operações nesse recurso sem precisar passar parâmetros de escopo, como ID de assinatura ou nome do recurso. Isso torna conveniente executar operações diretamente no resultado de chamadas de lista, uma vez que tudo é retornado como um cliente de recurso completo agora.

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} Classe de dados

Este tipo representa o modelo que compõe um determinado recurso. Normalmente, esses são os dados de resposta de uma chamada de serviço, como HTTP GET, e fornecem detalhes sobre o recurso subjacente. Anteriormente, isso era representado por uma classe Model .

{ResourceName} Classe de coleção

Esse tipo representa as operações que você pode executar em uma coleção de recursos pertencentes a um recurso pai específico. Este objeto fornece a maioria das operações de coleta lógica.

Comportamento de coleta Método de Recolha
Iterar/Listar GetAll()
Índice Get(nome da cadeia de caracteres)
Adicionar CreateOrUpdate(Azure.WaitUntil waitUntil, string name, {ResourceName}Data data)
Contains Exists(nome da cadeia de caracteres)

Na maioria dos casos, o pai de um recurso é ResourceGroup, mas em alguns casos, um recurso em si tem sub-recurso, por exemplo, uma Sub-rede é filha de uma VirtualNetwork. O próprio ResourceGroup é filho de uma Assinatura

Juntar tudo

Imagine que nossa empresa exige que todas as máquinas virtuais sejam marcadas com o proprietário. Somos encarregados de escrever um programa para adicionar a tag a quaisquer máquinas virtuais ausentes em um determinado grupo de recursos.

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

Identificador de recursos estruturados

As IDs de recurso contêm informações úteis sobre o recurso em si, mas são cadeias de caracteres simples que precisam ser analisadas. Em vez de implementar sua própria lógica de análise, você pode usar um ResourceIdentifier objeto que fará a análise para você.

Exemplo: Analisando uma ID usando um objeto 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}");

No entanto, tenha em mente que algumas dessas propriedades podem ser nulas. Normalmente, é possível saber pela própria cadeia de caracteres de ID qual é o tipo de ID de recurso. Mas se você não tiver certeza, verifique se as propriedades são nulas.

Exemplo: Gerador de identificador de recursos

Talvez você não queira criar manualmente o resourceId a partir de um arquivo .string Cada {ResourceName}Resource classe tem um método estático que pode ajudá-lo a criar a cadeia de caracteres do identificador de recurso.

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

Gerenciar recursos existentes

Executar operações em recursos que já existem é um caso de uso comum ao usar as bibliotecas de cliente de gerenciamento. Nesse cenário, você geralmente tem o identificador do recurso que você deseja trabalhar como uma cadeia de caracteres. Embora a nova hierarquia de objetos seja ótima para provisionar e trabalhar dentro do escopo de um determinado pai, ela não é a mais eficiente quando se trata desse cenário específico.

Aqui está um exemplo de como você pode acessar um AvailabilitySetResource objeto e gerenciá-lo diretamente com seu identificador de recurso:

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

Essa abordagem exigiu muito código e três chamadas de API foram feitas para o Azure. O mesmo pode ser feito com menos código e sem chamadas de API usando métodos de extensão que fornecemos no próprio cliente. Esses métodos de extensão permitem que você passe um identificador de recurso e recupere um cliente de recurso com escopo. O objeto retornado é um {ResourceName}Resource. Como ele ainda não entrou em contato com o Azure para recuperar os dados, chamar a Data propriedade lançará exceção, você pode usar HasData a propriedade para saber se a instância do recurso contém um dado ou chamar o Get método ou GetAsync no recurso para recuperar os dados do recurso.

Assim, o exemplo anterior acabaria ficando assim:

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

Verificar se existe um recurso

Se você não tem certeza se um recurso que você deseja obter existe, ou você só quer verificar se ele existe, você pode usar Exists() ou ExistsAsync() métodos, que podem ser invocados a partir de qualquer {ResourceName}Collection classe.

Exists() retorna um Response<bool> tempo, ExistsAsync() pois sua versão assíncrona retorna um Task<Response<bool>>arquivo . Response<bool> No objeto, você pode visitar sua Value propriedade para verificar se um recurso existe. O Value é false se o recurso não existir e vice-versa.

Em versões anteriores de pacotes, você teria que pegar o RequestFailedException e inspecionar o código de status para 404. Com esta nova API, esperamos que isso possa aumentar a produtividade do desenvolvedor e otimizar o acesso aos recursos.

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

Agora, com esses métodos de conveniência, podemos simplesmente fazer o seguinte.

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

Exemplos

Criar um grupo de recursos

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

Listar todos os grupos de recursos

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

Atualizar um grupo de recursos

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

Eliminar um grupo de recursos

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

Para exemplos mais detalhados, dê uma olhada nas amostras que temos disponíveis.

Resolução de Problemas

  • Se você tiver um bug para relatar ou tiver uma sugestão, registre um problema via problemas do GitHub e certifique-se de adicionar o rótulo "Visualização" ao problema.
  • Se precisar de ajuda, verifique as perguntas anteriores ou faça novas perguntas no StackOverflow usando as tags Azure e .NET.
  • Se tiver problemas com a autenticação, consulte a documentação DefaultAzureCredential.

Próximos passos

Mais código de exemplo

Documentação Adicional

Se você estiver migrando do SDK antigo para esta visualização, confira este Guia de migração.

Para obter mais informações sobre o SDK do Azure, consulte Versões do SDK do Azure.