Gerenciamento de recursos usando o SDK do Azure para .NET

As bibliotecas do plano de gerenciamento do SDK do Azure para .NET ajudarão você a criar, provisionar e gerenciar recursos do Azure por meio de aplicativos .NET. Todos os serviços do Azure têm bibliotecas de gerenciamento correspondentes.

Com as bibliotecas de gerenciamento (namespaces que começam com Azure.ResourceManager, por exemplo, Azure.ResourceManager.Compute), você pode criar programas de configuração e implantação para executar as mesmas tarefas que podem ser executadas com o portal do Azure, a CLI do Azure ou outras ferramentas de gerenciamento de recursos.

Esses pacotes seguem as novas diretrizes do SDK do Azure, que oferecem funcionalidades principais que são compartilhadas 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.

Introdução

Pré-requisitos

• Uma assinatura do Azure
• Uma implementação de TokenCredential, como um tipo de credencial de biblioteca de identidade do Azure.

Instalar o pacote

Instale os pacotes NuGet de gerenciamento de recursos do Azure Identity e 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

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

Autenticar o cliente

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

Para fazer a autenticação com o Azure e criar um ArmClient, crie uma instância das credenciais de ArmClient fornecidas:

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 classe Azure.Identity.DefaultAzureCredential, consulte Classe DefaultAzureCredential.

Folha de referências do SDK de gerenciamento

Para começar a usar o SDK de gerenciamento do Azure para .NET, imagine que você tenha a tarefa de criar, listar, atualizar e 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 você 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. Localize o método correspondente para gerenciar o recurso do Azure.

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 localizar o pacote correto do SDK de gerenciamento do Azure, procure pacotes nomeados com o padrão Azure.ResourceManager.{ResourceProviderName} a seguir.

Para saber mais sobre o ResourceIdentifier, confira Identificador de recurso estruturado.

Principais conceitos

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 usa, 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 no escopo da assinatura e do grupo de recursos adequados.

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

Classe {ResourceName}Resource

Esse tipo representa um objeto de cliente de recurso completo que contém uma propriedade Data que expõe os detalhes como um tipo {ResourceName}Data. Ele também tem acesso a todas as operações desse 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, pois agora tudo é retornado como um cliente de recursos completos.

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

Classe {ResourceName}Data

Esse 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 Modelo.

Classe {ResourceName}Collection

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 lógicas de coleta.

Na maioria dos casos, o pai de um recurso é o Grupo de recursos, mas, em alguns casos, o recurso tem um sub-recurso. Por exemplo, uma Sub-rede é filho de uma Rede virtual. O Grupo de recursos é filho de uma Assinatura

Juntando as peças

Imagine que nossa empresa exija que todas as máquinas virtuais sejam marcadas com o proprietário. Temos a tarefa de escrever um programa para adicionar a marca a qualquer máquina virtual ausente 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 recurso estruturado

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

Exemplo: analisando um 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, lembre-se de que algumas dessas propriedades podem ser nulas. Geralmente, você pode dizer pela própria cadeia de caracteres de ID qual é o tipo de ID de um recurso. Mas se você não tiver certeza, verifique se as propriedades são nulas.

Exemplo: Gerador de identificador de recurso

Talvez você não queira criar o resourceId manualmente usando uma string pura. Cada classe {ResourceName}Resource tem um método estático que pode ajudar você a criar a cadeia de caracteres do identificador de recurso.

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

Gerenciar os recursos existentes

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

Veja um exemplo de como acessar um objeto AvailabilitySetResource e gerenciá-lo diretamente com o respectivo 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 à API feitas no 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 definido. O objeto retornado é um {ResourceName}Resource. Como ele ainda não acessou o Azure para recuperar os dados, uma chamada à propriedade Data vai gerar exceção. Você pode usar a propriedade HasData para saber se a instância do recurso contém dados ou chamar o método Get ou GetAsync no recurso para recuperar os dados do recurso.

Portanto, o exemplo anterior ficaria 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 um Recurso existe

Se você não tem certeza de que um recurso que deseja obter já existe ou se apenas deseja verificar se ele existe, use o métodos Exists() ou ExistsAsync(), que podem ser invocados de qualquer classe {ResourceName}Collection.

Exists() retorna um Response<bool> enquanto ExistsAsync() como sua versão assíncrona retorna um Task<Response<bool>>. No objeto Response<bool>, você pode visitar a propriedade Value para verificar se existe um recurso. Se o recurso não existir, Value será false e vice-versa.

Nas versões anteriores dos pacotes, você teria que pegar o RequestFailedException e inspecionar o código de status para 404. Com essa 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");

Excluir 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 nos exemplos que temos disponíveis.

Solução de problemas

• Se você tiver um bug para relatar ou tiver uma sugestão, registre um problema por meio de problemas do GitHub e certifique-se de adicionar o rótulo "Visualizar" 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óximas etapas

Mais códigos de exemplo

• Gerenciando grupos de recursos
• Criando uma rede virtual
• Exemplos de código da biblioteca de gerenciamento .NET

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.