Partager via

Gestion des ressources à l’aide du Kit de développement logiciel (SDK) Azure pour .NET

  • Article

Le Kit de développement logiciel (SDK) Azure pour les bibliothèques de plan de gestion .NET vous aidera à créer, provisionner et gérer des 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, Azure CLI ou d’autres outils de gestion des ressources.

Ces packages suivent les nouvelles instructions du Kit de développement logiciel (SDK) Azure, qui fournissent des fonctionnalités de base partagées entre tous les kits SDK Azure, notamment :

  • Bibliothèque d’identités Azure intuitive.
  • Pipeline HTTP avec des stratégies personnalisées.
  • Gestion des erreurs.
  • Suivi distribué.

Remarque

Vous remarquerez peut-être que certains packages sont toujours en préversion. Les versions progressives des bibliothèques de plan de gestion des services Azure supplémentaires sont en cours. Si vous recherchez un package de version stable pour une ressource Azure particulière et qu’actuellement seule une version préliminaire est disponible, soulèvez un problème dans Kit de développement logiciel (SDK) Azure pour le dépôt GitHub .NET.

Démarrer

Conditions préalables

Installer le package

Installez les packages NuGet Azure Identity et 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. Étant donné que toutes les API de gestion passent par le même point de terminaison, pour interagir avec les ressources, une seule ArmClient de niveau supérieur doit être créée.

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 de développement logiciel (SDK) de gestion Azure pour .NET, imaginez que vous disposez d’une tâche pour créer/répertorier/mettre à jour/supprimer un espace de noms Azure Service Bus classique, procédez comme suit :

  1. Authentifiez-vous auprès de l’abonnement et du groupe de ressources sur lequel vous souhaitez 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. Recherchez la méthode correspondante pour gérer votre ressource Azure.
Opération Méthode
Obtenir une ressource avec l’identificateur de ressource client.GetServiceBusQueueResource(ResourceIdentifier resourceIdentifier)
Liste 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 de développement logiciel (SDK) de gestion correspondant à l’aide du code similaire à l’exemple ci-dessus. Pour rechercher le package correct du Kit de développement logiciel (SDK) de gestion Azure, recherchez les packages nommés avec le modèle suivant Azure.ResourceManager.{ResourceProviderName}.

Pour en savoir plus sur ResourceIdentifier, reportez-vous à Structured Resource Identifier .

Concepts clés

Présentation de la hiérarchie des ressources Azure

Pour réduire le nombre de clients nécessaires pour effectuer des tâches courantes et le nombre de paramètres redondants que chacun de ces clients prend, nous avons introduit une hiérarchie d’objets dans le Kit de développement logiciel (SDK) qui imite la hiérarchie d’objets dans Azure. Chaque client de ressources du Kit de développement logiciel (SDK) a des méthodes pour accéder aux clients de ressources de ses enfants qui sont déjà configurés pour l’abonnement et le groupe de ressources appropriés.

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

Classe {ResourceName}Resource

Ce type représente un objet client de ressources complet qui contient une propriété Data exposant les détails sous la forme d’un type {ResourceName}Data. Il a également accès à toutes les opérations sur cette ressource sans avoir à transmettre des paramètres d’étendue tels que l’ID d’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. En règle générale, il s’agit des données de réponse d’un appel de service tel que HTTP GET et 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 de collection logique.

Comportement de collecte Méthode de collecte
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 possède une sous-ressource, par exemple un sous-réseau est un enfant d’un VirtualNetwork. ResourceGroup lui-même est un enfant d’un Abonnement

Tout assembler

Imaginez que notre entreprise exige que toutes les machines virtuelles soient étiquetées avec le propriétaire. Nous sommes chargés d’écrire un programme pour ajouter la balise à 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());
   }
}

Identificateur de ressource structuré

Les ID de ressource contiennent des informations utiles sur la ressource elle-même, mais il s’agit de 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 effectuera 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 être nulles. Vous pouvez généralement identifier à partir de la chaîne d'ID elle-même le type d'ID de ressource. Mais si vous n’êtes pas sûr, vérifiez si les propriétés sont nulles.

Exemple : Générateur d’identificateur de ressource

Vous ne souhaiterez peut-être pas créer manuellement le resourceId à partir d’un stringpur. Chaque classe {ResourceName}Resource a une méthode statique qui peut vous aider à créer la chaîne d’identificateur de ressource.

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

Gérer les ressources existantes

L’exécution d’opérations sur les ressources qui existent déjà est un cas d’usage courant lors de l’utilisation des bibliothèques clientes de gestion. Dans ce scénario, vous disposez généralement de l’identificateur de la ressource sur laquelle vous souhaitez travailler sous forme de chaîne. Bien que la nouvelle hiérarchie d’objets soit idéale pour la mise en place et le travail 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 identificateur 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 effectués sur Azure. La même chose peut être effectuée avec moins de code et sans aucun appel d’API à l’aide de méthodes d’extension que nous avons fournies sur le client lui-même. Ces méthodes d’extension vous permettent de transmettre un identificateur de ressource et de récupérer un client de ressources délimité. L’objet retourné est un {ResourceName}Resource. Étant donné qu’elle n’a pas encore atteint Azure pour récupérer les données, l’appel de la propriété Data lève une exception, vous pouvez utiliser HasData propriété pour indiquer si l’instance de ressource contient des données ou appeler la méthode Get ou GetAsync sur la ressource pour récupérer les données de ressource.

Par conséquent, l’exemple précédent se présente comme suit :

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 ne savez pas si une ressource que vous souhaitez obtenir existe ou si vous souhaitez simplement vérifier si elle existe, vous pouvez utiliser des méthodes Exists() ou ExistsAsync(), qui peuvent être appelées à partir de n’importe quelle classe {ResourceName}Collection.

Exists() retourne un Response<bool>, alors que ExistsAsync(), sous sa version asynchrone, retourne un Task<Response<bool>>. Dans l’objet Response<bool>, vous pouvez visiter sa propriété Value pour vérifier si une ressource existe. La Value 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.");
}

Maintenant, avec ces méthodes pratiques, nous pouvons simplement effectuer les opérations suivantes.

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;

Répertorier 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);
}

Mettre à jour 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 avons disponibles.

Dépannage

  • Si vous avez un bogue à signaler ou si vous avez une suggestion, signalez un problème via problèmes GitHub et veillez à ajouter l’étiquette « Aperçu » au problème.
  • Si vous avez besoin d’aide, vérifiez questions précédentes, ou posez-en de nouvelles sur StackOverflow à l’aide de balises Azure et .NET.
  • Si vous rencontrez des problèmes d’authentification, consultez la documentation DefaultAzureCredential.

Étapes suivantes

Autres exemples de code

Documentation supplémentaire

Si vous migrez de l’ancien SDK vers cette préversion, consultez ce guide de migration .

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