Partager via

Gestion des ressources à l'aide du Kit SDK Azure pour .NET

  • Article

Les bibliothèques du plan de gestion du kit SDK Azure pour .NET vous aideront à créer, à approvisionner et à gérer les ressources Azure à partir d'applications .NET. Tous les services Azure ont des bibliothèques de gestion correspondantes.

Avec les bibliothèques de gestion (espaces de noms commençant par Azure.ResourceManager, par exemple, Azure.ResourceManager.Compute), vous pouvez écrire des programmes de configuration et de déploiement pour effectuer les mêmes tâches que celles que vous pouvez effectuer via le portail Azure, l’interface de ligne de commande Azure, ou d'autres outils de gestion des ressources.

Ces paquets respectent les nouvelles directives relatives aux kits SDK Azure, qui fournissent des fonctionnalités de base partagées par tous les kits SDK Azure, notamment :

  • La bibliothèque d’identités Azure intuitive.
  • Un pipeline HTTP avec des stratégies personnalisées.
  • Gestion des erreurs.
  • Suivi distribué.

Notes

Vous remarquerez peut-être que certains paquets sont encore en version préliminaire, les versions de production des bibliothèques de plan de gestion des services Azure supplémentaires sont en cours. Si vous recherchez une version stable de package pour une ressource Azure particulière et que seule une version préliminaire est actuellement disponible, veuillez signaler ce problème dans le référentiel Github du Kit de développement logiciel (SDK) Azure pour .NET

Bien démarrer

Prérequis

Installer le package

Installez les packages NuGet Azure Identity et de gestion des ressources Azure pour .NET. Par exemple :

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

Authentifier le client

L'option par défaut pour créer un client authentifié consiste à utiliser DefaultAzureCredential. Comme toutes les API de gestion passent par le même point de terminaison, pour interagir avec les ressources, un seul niveau supérieur ArmClient doit être créé.

Pour s'authentifier auprès d'Azure et créer un objet ArmClient, instanciez les informations d'identification ArmClient données :

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

// Code omitted for brevity

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

Pour plus d’informations sur la classe Azure.Identity.DefaultAzureCredential, consultez DefaultAzureCredential, classe.

Aide-mémoire du Kit de développement logiciel (SDK) de gestion

Pour commencer à utiliser le kit SDK de gestion Azure pour .NET, imaginez que vous avez une tâche consistant à créer/lister/mettre à jour/supprimer un espace de noms typique du bus de service Azure, et suivez ces étapes :

  1. Authentifiez-vous sur l'abonnement et le groupe de ressources sur lesquels vous voulez travailler.
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. Trouvez la méthode correspondante pour gérer votre ressource Azure.
Opération Méthode
Obtenir une ressource avec un identifiant de ressource client.GetServiceBusQueueResource(ResourceIdentifier resourceIdentifier)
List resourceGroup.GetServiceBusNamespaces()
Index resourceGroup.GetServiceBusNamespace(string servicebusNamespaceName)
Ajouter/mettre à jour resourceGroup.GetServiceBusNamespaces().CreateOrUpdate(Azure.WaitUntil waitUntil, string name, ServiceBusNamespaceData data)
Contient resourceGroup.GetServiceBusNamespaces().Exists(string servicebusNamespaceName)
Supprimer client.GetServiceBusQueueResource(ResourceIdentifior resourceIdentifior).Delete() ou resourceGroup.GetServiceBusNamespace(string servicebusNamespaceName).Delete()

N'oubliez pas que toutes les ressources Azure, y compris le groupe de ressources lui-même, peuvent être gérées par leur kit SDK de gestion correspondant en utilisant un code similaire à l'exemple ci-dessus. Pour trouver le paquet SDK de gestion Azure approprié, recherchez les paquets nommés selon le modèle Azure.ResourceManager.{ResourceProviderName} suivant.

Pour en savoir plus sur ResourceIdentifier, veuillez vous reporter à Structured Resource Identifier.

Concepts clés

Présentation de la hiérarchie des ressources Azure

Pour réduire le nombre de clients nécessaires à l'exécution de tâches courantes et le nombre de paramètres redondants requis pour chacun de ces clients, nous avons introduit dans le kit SDK une hiérarchie d'objets qui imite celle d'Azure. Chaque client de ressources du kit SDK propose des méthodes permettant d'accéder aux clients de ressources de ses enfants qui sont déjà associés à l'abonnement et au groupe de ressources appropriés.

Pour cela, nous introduisons trois types standard pour toutes les ressources dans Azure :

Classe {ResourceName}Resource

Ce type représente un objet client de ressource complète qui contient une propriété Data exposant les détails comme un type {ResourceName}Data. Il a également accès à toutes les opérations sur cette ressource sans avoir à passer des paramètres de portée tels que l'ID de l'abonnement ou le nom de la ressource. Cela permet d'exécuter directement des opérations sur le résultat des appels de liste, puisque tout est renvoyé sous forme de ressource client complète.

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

Ce type représente le modèle qui compose une ressource donnée. Il s'agit généralement des données de réponse d'un appel de service comme HTTP GET et qui fournit des détails sur la ressource sous-jacente. Auparavant, cela était représenté par une classe Model.

Classe {ResourceName}Collection

Ce type représente les opérations que vous pouvez effectuer sur une collection de ressources appartenant à une ressource parente spécifique. Cet objet fournit la plupart des opérations logiques de collecte.

Comportement de collection Méthode de collection
Itérer/Répertorier GetAll()
Index Get(nom de chaîne)
Ajouter CreateOrUpdate(Azure.WaitUntil waitUntil, nom de chaîne, données {ResourceName}Data)
Contient Exists(nom de chaîne)

Dans la plupart des cas, le parent d’une ressource est ResourceGroup, mais dans certains cas, une ressource elle-même possède une sous-ressource, par exemple un sous-réseau est un enfant d’un réseau virtuel (VirtualNetwork). ResourceGroup lui-même est un enfant d’un abonnement (abonnement)

Exemple complet

Imaginez que notre entreprise exige que toutes les machines virtuelles soient étiquetées pour indiquer leur propriétaire. Nous sommes chargés d’écrire un programme pour ajouter l’étiquette à toutes les machines virtuelles manquantes dans un groupe de ressources donné.

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

Structured Resource Identifier

Les ID de ressource contiennent des informations utiles sur la ressource elle-même, mais ils représentent des chaînes simples qui doivent être analysées. Au lieu d’implémenter votre propre logique d’analyse, vous pouvez utiliser un objet ResourceIdentifier qui effectue l’analyse pour vous.

Exemple : analyse d’un ID à l’aide d’un objet 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}");

Toutefois, gardez à l’esprit que certaines de ces propriétés peuvent avoir une valeur null. La chaîne d'identification elle-même permet généralement de déterminer le type d'identification d'une ressource. Mais si vous n’êtes pas sûr, vérifiez si les propriétés sont null.

Exemple : Resource Identifier Generator

Dans certains cas, vous ne voudrez pas créer manuellement l’objet resourceId à partir d’un string pur. Chaque classe {ResourceName}Resource possède une méthode statique qui peut vous aider à créer la chaîne d'identification de la ressource.

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

Gérer les ressources existantes

Effectuer des opérations sur des ressources qui existent déjà est un cas d'utilisation courant lors de l'utilisation des bibliothèques clientes de gestion. Dans ce scénario, vous disposez généralement de l'identifiant de la ressource sur laquelle vous souhaitez travailler sous forme d’une chaîne. Même si la nouvelle hiérarchie d'objets convient parfaitement au provisionnement et à une utilisation dans le cadre d'un parent donné, elle n'est pas la plus efficace pour ce scénario spécifique.

Voici un exemple de la façon dont vous pouvez accéder à un objet AvailabilitySetResource et le gérer directement avec son identifiant de ressource :

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

Cette approche nécessite beaucoup de code et trois appels d'API sont passés vers Azure. La même opération peut être effectuée avec moins de code et sans aucun appel à l'API en utilisant les méthodes d'extension que nous avons fournies au client lui-même. Ces méthodes d'extension vous permettent de transmettre un identifiant de ressource et de récupérer un client de ressource délimité. L’objet retourné est un {ResourceName}Resource. Comme il n’a pas encore contacté Azure pour récupérer les données, l'appel de la propriété Data entraînera une exception. Vous pouvez soit utiliser la propriété HasData pour savoir si l'instance de ressource contient des données, soit appeler la méthode Get ou GetAsync sur la ressource pour récupérer les données de la ressource.

Ainsi, l'exemple précédent ressemblerait à ceci :

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

Vérifier si une ressource existe

Si vous n'êtes pas sûr que la ressource que vous recherchez existe, ou si vous voulez simplement vérifier son existence, vous pouvez utiliser les méthodes Exists() ou ExistsAsync(), qui peuvent être invoquées à partir de n'importe quelle classe {ResourceName}Collection.

Exists() retourne une valeur Response<bool> avec ExistsAsync(), car sa version asynchrone renvoie Task<Response<bool>>. Dans l’objet Response<bool> , vous pouvez visiter sa propriété Value pour vérifier si une ressource existe. La Value valeur est false si la ressource n’existe pas, et inversement.

Dans les versions précédentes des packages, vous devrez intercepter et RequestFailedException inspecter le code d’état pour 404. Avec cette nouvelle API, nous espérons que cela peut stimuler la productivité des développeurs et optimiser l’accès aux ressources.

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

Avec ces méthodes pratiques, nous pouvons simplement faire ce qui suit.

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

Exemples

Créer un groupe de ressources

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

Liste de tous les groupes de ressources

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

Mise à jour d'un groupe de ressources

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

Supprimer un groupe de ressources

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

Pour obtenir des exemples plus détaillés, consultez les exemples que nous proposons.

Dépannage

  • Si vous avez un bogue à signaler ou une suggestion à faire, indiquez-le dans la section Problèmes GitHub en veillant à ajouter l'étiquette « Preview ».
  • Si vous avez besoin d'aide, consultez les questions précédentes ou posez-en de nouvelles sur StackOverflow en utilisant les balises Azure et .NET.
  • Si vous rencontrez des problèmes d'authentification, consultez la documentation de DefaultAzureCredential.

Étapes suivantes

Autres exemples de code

Documentation complémentaire

Si vous effectuez une migration de l’ancien kit SDK vers cette version préliminaire, consultez ce guide de migration.

Pour plus d’informations sur le Kit de développement logiciel (SDK) Azure, consultez Versions du Kit de développement logiciel (SDK) Azure.