Administración de recursos mediante el SDK de Azure para .NET

Las bibliotecas del plano de administración de .NET del SDK de Azure le ayudarán a crear, aprovisionar y administrar recursos de Azure desde aplicaciones .NET. Todos los servicios de Azure tienen bibliotecas de administración correspondientes.

Con las bibliotecas de administración (espacios de nombres que comienzan por Azure.ResourceManager, por ejemplo, Azure.ResourceManager.Compute), puede escribir programas de configuración e implementación para realizar las mismas tareas que puede realizar a través de Azure Portal, la CLI de Azure u otras herramientas de administración de recursos.

Estos paquetes siguen las nuevas directrices del SDK de Azure , que proporcionan funcionalidades principales que se comparten entre todos los SDK de Azure, entre los que se incluyen:

• La biblioteca intuitiva de identidades de Azure.
• Una canalización HTTP con directivas personalizadas.
• Control de errores.
• Seguimiento distribuido.

Comenzar

Prerrequisitos

• Una suscripción de Azure.
• Una implementación de TokenCredential, como un tipo de credencial de la biblioteca de Azure Identity.

Instalación del paquete

Instale los paquetes NuGet de Azure Identity y Azure Resource Management para .NET. Por ejemplo:

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

Autenticación del cliente

La opción predeterminada para crear un cliente autenticado es usar DefaultAzureCredential. Dado que todas las API de administración pasan por el mismo punto de conexión, con el fin de interactuar con los recursos, solo se debe crear un ArmClient de nivel superior.

Para autenticarse con Azure y crear un objeto ArmClient, cree una instancia de una credencial determinada de ArmClient:

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

// Code omitted for brevity

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

Para más información sobre la clase Azure.Identity.DefaultAzureCredential, consulte Clase DefaultAzureCredential.

Hoja de referencia rápida del SDK de administración

Para empezar a trabajar con el SDK de administración de Azure para .NET, imagine que tiene una tarea para crear, enumerar, actualizar o eliminar un espacio de nombres típico de Azure Service Bus, siga estos pasos:

1. Autentíquese en la suscripción y el grupo de recursos en los que desea trabajar.

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. Busque el método correspondiente para administrar el recurso de Azure.

Recuerde que todos los recursos de Azure, incluido el propio grupo de recursos, se pueden administrar mediante su SDK de administración correspondiente mediante código similar al ejemplo anterior. Para buscar el paquete correcto del SDK de administración de Azure, busque los paquetes denominados con el siguiente patrón Azure.ResourceManager.{ResourceProviderName}.

Para obtener más información sobre ResourceIdentifier, consulte Identificador de recursos estructurado.

Conceptos clave

Descripción de la jerarquía de recursos de Azure

Para reducir el número de clientes necesarios para realizar tareas comunes y el número de parámetros redundantes que toma cada uno de esos clientes, hemos introducido una jerarquía de objetos en el SDK que imita la jerarquía de objetos en Azure. Cada cliente de recursos del SDK tiene métodos para acceder a los clientes de recursos de sus elementos secundarios, que ya está limitado a la suscripción y el grupo de recursos adecuados.

Para ello, se presentan tres tipos estándar para todos los recursos de Azure:

Clase Recurso{ResourceName}

Este tipo representa un objeto cliente de recurso completo que contiene una propiedad Data que expone los detalles como tipo {ResourceName}Data. También tiene acceso a todas las operaciones de ese recurso sin necesidad de pasar parámetros de ámbito, como el identificador de suscripción o el nombre del recurso. Esto hace que sea conveniente para ejecutar directamente operaciones en el resultado de las llamadas de lista, ya que ahora todo se devuelve como un cliente de recurso completo.

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

Clase Datos{ResourceName}

Este tipo representa el modelo que compone un recurso determinado. Normalmente, estos son los datos de respuesta de una llamada de servicio como HTTP GET y proporcionan detalles sobre el recurso subyacente. Anteriormente, esto se representaba mediante una clase Model.

Clase Colección{ResourceName}

Este tipo representa las operaciones que puede realizar en una colección de recursos que pertenecen a un recurso primario específico. Este objeto proporciona la mayoría de las operaciones de colección lógica.

En la mayoría de los casos, el elemento primario de un recurso es ResourceGroup pero, en algunos casos, el propio recurso tiene un subrecurso, por ejemplo, Subnet es un elemento secundario de VirtualNetwork. ResourceGroup es en sí un elemento secundario de Suscripción.

Integrándolo todo

Imagine que nuestra empresa requiere que todas las máquinas virtuales se etiqueten con el propietario. Se nos encarga de escribir un programa para agregar la etiqueta a las máquinas virtuales que faltan en un grupo de recursos determinado.

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

Los identificadores de recursos contienen información útil sobre el propio recurso, pero son cadenas sin formato que se deben analizar. En lugar de implementar su propia lógica de análisis, puede usar un objeto ResourceIdentifier que realizará el análisis.

Ejemplo: Análisis de un identificador mediante un 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}");

Sin embargo, tenga en cuenta que algunas de esas propiedades podrían ser null. Normalmente, puede determinar por la propia cadena de identificador de qué tipo es un identificador de recurso. Pero si no está seguro, compruebe si las propiedades son nulas.

Ejemplo: Generador de identificadores de recursos

Es posible que no desee crear manualmente el resourceId a partir de una stringpura. Cada {ResourceName}Resource clase tiene un método estático que puede ayudarle a crear la cadena de identificador de recursos.

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

Administración de recursos existentes

Realizar operaciones en recursos que ya existen es un caso de uso común al usar las bibliotecas cliente de administración. En este escenario, normalmente tiene en forma de cadena el identificador del recurso en el que quiere trabajar. Aunque la nueva jerarquía de objetos es excelente para el aprovisionamiento y el trabajo dentro del ámbito de un padre determinado, no es la más eficaz cuando se trata de este escenario específico.

Este es un ejemplo de cómo puede acceder a un objeto AvailabilitySetResource y administrarlo directamente con su 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);

Este enfoque requiere una gran cantidad de código y se realizan tres llamadas API a Azure. Lo mismo se puede hacer con menos código y sin ninguna llamada API mediante métodos de extensión que hemos proporcionado en el propio cliente. Estos métodos de extensión permiten pasar un identificador de recurso y recuperar un cliente de recurso con ámbito. El objeto devuelto es un {ResourceName}Resource. Puesto que aún no se ha comunicado con Azure para recuperar los datos, al llamar a la propiedad Data se producirá una excepción, puede usar HasData propiedad para indicar si la instancia de recurso contiene datos o llamar al método Get o GetAsync en el recurso para recuperar los datos del recurso.

Por lo tanto, el ejemplo anterior terminaría viéndose así.

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

Comprobar si existe un recurso

Si no está seguro de si existe un recurso que desea obtener o solo desea comprobar si existe, puede usar métodos Exists() o ExistsAsync(), que se pueden invocar desde cualquier clase {ResourceName}Collection.

Exists() devuelve un Response<bool> mientras ExistsAsync() como su versión asincrónica devuelve un Task<Response<bool>>. En el objeto Response<bool>, puede visitar su propiedad Value para comprobar si existe un recurso. El Value es false si el recurso no existe y viceversa.

En versiones anteriores de los paquetes, tendría que detectar RequestFailedException e inspeccionar el código de estado para 404. Con esta nueva API, esperamos que esto pueda aumentar la productividad del desarrollador y optimizar el acceso a los 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.");
}

Ahora con estos métodos de conveniencia, simplemente podemos hacer lo siguiente.

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

Ejemplos

Creación de un 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;

Enumeración de todos los 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);
}

Actualización de un 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");

Eliminación de un 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 obtener ejemplos más detallados, eche un vistazo a los ejemplos que tenemos disponibles.

Solución de problemas

• Si tiene un error para notificar o tiene una sugerencia, abra un problema a través de problemas de GitHub y asegúrese de agregar la etiqueta "Versión preliminar" al problema.
• Si necesita ayuda, consulte preguntas anterioreso realice nuevas en StackOverflow mediante etiquetas de Azure y .NET.
• Si tiene problemas con la autenticación, consulte la documentación de DefaultAzureCredential.

Pasos siguientes

Más código de ejemplo

• administración de grupos de recursos
• Creación de una red virtual
• Ejemplos de código de la biblioteca de administración de .NET

Documentación adicional

Si va a migrar desde el SDK anterior a esta versión preliminar, consulte esta guía de migración de .

Para más información sobre el SDK de Azure, consulte versiones del SDK de Azure.