Compartir a través de

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

  • Artículo

Las bibliotecas de plano de administración de Azure SDK para .NET facilitan la creación, el aprovisionamiento y la administración de recursos de Azure desde aplicaciones de .NET. Todos los servicios de Azure tienen bibliotecas de administración correspondientes.

Con las bibliotecas de administración (los espacios de nombres que empiezan por Azure.ResourceManager, como por ejemplo, Azure.ResourceManager.Compute), puede escribir programas de configuración e implementación para llevar a cabo las mismas tareas que puede realizar mediante Azure Portal, la CLI de Azure u otras herramientas de administración de recursos.

Esos paquetes siguen las nuevas directrices del SDK de Azure, que proporcionan funcionalidades básicas que se comparten entre todos los SDK de Azure, incluidas las siguientes:

  • La biblioteca intuitiva Identidad de Azure.
  • Canalización HTTP con directivas personalizadas.
  • Control de errores.
  • Seguimiento distribuido.

Nota

Es posible que observe que algunos paquetes siguen siendo versiones preliminares; las versiones por fases de las bibliotecas del plano de administración de los servicios de Azure adicionales están en proceso. Si busca un paquete de versión estable para un recurso de Azure determinado y solo hay disponible una versión preliminar, vaya al repositorio Github de Azure SDK para .NET. para registrar una incidencia.

Introducción

Requisitos previos

Instalar el 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

Autenticar el 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, para interactuar con los recursos, solo se tiene que 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 características clave del SDK de administración

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

  1. Autentíquese en la suscripción y en el grupo de recursos en los que quiere 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.
Operación Método
Obtención de un recurso con el identificador de recurso client.GetServiceBusQueueResource(ResourceIdentifier resourceIdentifier)
List resourceGroup.GetServiceBusNamespaces()
Índice resourceGroup.GetServiceBusNamespace(string servicebusNamespaceName)
Adición y actualización resourceGroup.GetServiceBusNamespaces().CreateOrUpdate(Azure.WaitUntil waitUntil, string name, ServiceBusNamespaceData data)
Contiene resourceGroup.GetServiceBusNamespaces().Exists(string servicebusNamespaceName)
Eliminar client.GetServiceBusQueueResource(ResourceIdentifior resourceIdentifior).Delete() o resourceGroup.GetServiceBusNamespace(string servicebusNamespaceName).Delete()

Recuerde que todos los recursos de Azure, incluido el propio grupo de recursos, se pueden administrar mediante el SDK de administración correspondiente con código similar al del ejemplo anterior. Para encontrar el paquete del SDK de administración de Azure correcto, busque paquetes cuyo nombre siga el 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 {ResourceName}Resource

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 {ResourceName}Data

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

Clase {ResourceName}Collection

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.

Comportamiento de la colección Método de la colección
Iteración/Lista GetAll()
Índice Get(nombre_de_cadena)
Sumar CreateOrUpdate(Azure.WaitUntil waitUntil, string name, {ResourceName}Data data)
Contiene Existe (nombre de cadena)

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 Subscription.

Resumen

Imagine que nuestra empresa necesita que todas las máquinas virtuales se etiqueten con el propietario. Se nos encomienda 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 estructurado

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

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

Pero tenga en cuenta que algunas de esas propiedades podrían ser NULL. En general, la propia cadena de id. permite saber el tipo de un id. de recurso. Pero, si no está seguro, compruebe si las propiedades son nulas.

Ejemplo: Generador de identificadores de recursos

Es posible que no quiera crear el objeto resourceId manualmente a partir de un elemento string puro. Cada clase {ResourceName}Resource tiene un método estático que puede ayudarle a crear la cadena de identificador de recurso.

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

Administración de recursos existentes

La realización de 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 aprovisionar y trabajar dentro del ámbito de un elemento primario concreto, no es la forma 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 mucho 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 los 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 de tipo {ResourceName}Resource. Puesto que aún no se ha llegado a Azure para recuperar los datos, al llamar a la propiedad Data se producirá una excepción, puede usar la propiedad HasData para indicar si la instancia del recurso contiene datos o llamar al método Get o GetAsync en el recurso para recuperar los datos del recurso.

Por tanto, el ejemplo anterior terminaría con este aspecto:

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

Comprobación de la existencia de un recurso

Si no se tiene seguridad de si existe un recurso que quiere obtener, o bien si solo quiere comprobar si existe, puede usar los métodos Exists() o ExistsAsync(), que se pueden invocar desde cualquier clase {ResourceName}Collection.

Exists() devuelve un elemento Response<bool> mientras que ExistsAsync() como su versión asincrónica devuelve un elemento Task<Response<bool>>. En el objeto Response<bool>, puede visitar su propiedad Value para comprobar si existe un recurso. El Value es falsesi rel 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, se espera 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 prácticos, simplemente se puede 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

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

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

Actualizar 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, vea los ejemplos disponibles.

Solución de problemas

Pasos siguientes

Más código de ejemplo

Documentación adicional

Si emigra del antiguo SDK a esta previsualización, consulte esta Migration guide, (Guía de migración).

Para obtener más información sobre el SDK de Azure consulte Azure SDK Releases, (Versiones del SDK de Azure).