Utiliser le Kit de développement logiciel (SDK) Azure pour .NET dans les applications ASP.NET Core

Article
11/16/2024

Le Kit de développement logiciel (SDK) Azure pour .NET permet aux applications ASP.NET Core de s’intégrer à de nombreux services Azure différents. Dans cet article, vous allez découvrir les meilleures pratiques et les étapes à suivre pour adopter le Kit de développement logiciel (SDK) Azure pour .NET dans vos applications ASP.NET Core. Vous découvrirez comment effectuer les actions suivantes :

Inscrivez les services pour l’injection de dépendances.
S’authentifier auprès d’Azure sans utiliser de mots de passe ou de secrets.
Implémentez une configuration centralisée et standardisée.
Configurez des problèmes courants d’application web, tels que la journalisation et les nouvelles tentatives.

Explorer les bibliothèques clientes courantes du Kit de développement logiciel (SDK) Azure

ASP.NET applications principales qui se connectent aux services Azure dépendent généralement des bibliothèques clientes du Kit de développement logiciel (SDK) Azure suivantes :

Microsoft.Extensions.Azure fournit des méthodes d’assistance pour inscrire des clients auprès de la collection de services d’injection de dépendances et gérer diverses préoccupations pour vous, telles que la configuration de la journalisation, la gestion des durées de vie du service d’authentification et la gestion des informations d’identification d’authentification.
Azure.Identity permet la prise en charge de l’authentification d’ID Microsoft Entra dans le Kit de développement logiciel (SDK) Azure. Il fournit un ensemble d’implémentations TokenCredential pour construire des clients du Kit de développement logiciel (SDK) Azure qui prennent en charge l’authentification Microsoft Entra.
Azure.<service-namespace>bibliothèques, telles qu’Azure.Storage.Blobs et Azure.Messaging.ServiceBus, fournissent des clients de service et d’autres types pour vous aider à vous connecter et à consommer des services Azure spécifiques. Pour obtenir un inventaire complet de ces bibliothèques, consultez Bibliothèques à l’aide d’Azure.Core.

Dans les sections à venir, vous allez découvrir comment implémenter une application ASP.NET Core qui utilise ces bibliothèques.

Inscrire des clients du Kit de développement logiciel (SDK) Azure auprès de la collection de services d’interface de ligne de commande

Le Kit de développement logiciel (SDK) Azure pour les bibliothèques clientes .NET fournit aux clients de service de connecter votre application à des services Azure tels que Stockage Blob Azure et Azure Key Vault. Inscrivez ces services auprès du conteneur de dépendances dans le Program.cs fichier de votre application pour les rendre disponibles via l’injection de dépendances.

Effectuez les étapes suivantes pour inscrire les services dont vous avez besoin :

Ajoutez le package Microsoft.Extensions.Azure :

dotnet add package Microsoft.Extensions.Azure

Ajoutez les packages clients de service appropriés Azure.* :

dotnet add package Azure.Security.KeyVault.Secrets
dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Messaging.ServiceBus

Dans le Program.cs fichier de votre application, appelez la AddAzureClients méthode d’extension de la Microsoft.Extensions.Azure bibliothèque pour inscrire un client pour communiquer avec chaque service Azure. Certaines bibliothèques clientes fournissent des sous-clients supplémentaires pour des sous-groupes spécifiques de fonctionnalités de service Azure. Vous pouvez inscrire ces sous-clients pour l’injection de dépendances via la méthode d’extension AddClient .

builder.Services.AddAzureClients(clientBuilder =>
{
    // Register a client for each Azure service using inline configuration
    clientBuilder.AddSecretClient(new Uri("<key_vault_url>"));
    clientBuilder.AddBlobServiceClient(new Uri("<storage_url>"));
    clientBuilder.AddServiceBusClientWithNamespace(
        "<your_namespace>.servicebus.windows.net");

    // Register a subclient for each Azure Service Bus Queue
    var queueNames = new string[] { "queue1", "queue2" };
    foreach (string queue in queueNames)
    {
        clientBuilder.AddClient<ServiceBusSender, ServiceBusClientOptions>(
            (_, _, provider) => provider.GetService<ServiceBusClient>()
                    .CreateSender(queue)).WithName(queue);
    }

    // Register a shared credential for Microsoft Entra ID authentication
    clientBuilder.UseCredential(new DefaultAzureCredential());
});

Injectez les clients inscrits dans vos composants d’application, services ou point de terminaison d’API ASP.NET Core :

API minimale
Blazor

app.MapGet("/reports", async (
        BlobServiceClient blobServiceClient,
        IAzureClientFactory<ServiceBusSender> senderFactory) =>
{
    // Create the named client
    ServiceBusSender serviceBusSender = senderFactory.CreateClient("queue1");

    await serviceBusSender.SendMessageAsync(new ServiceBusMessage("Hello world"));

    // Use the blob client
    BlobContainerClient containerClient
        = blobServiceClient.GetBlobContainerClient("reports");

    List<BlobItem> reports = new();
    await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
    {
        reports.Add(blobItem);
    }

    return reports;
})
.WithName("GetReports");

@page "/"
@using Azure.Storage.Blobs
@using Azure.Storage.Blobs.Models
@using Azure.Messaging.ServiceBus
@using Microsoft.Extensions.Azure;

<h1>Reports</h1>

<ul>
    @foreach (var report in reports)
    {
        <li>@report.Name</li>
    }
</ul>

@code {
    List<BlobItem> reports = new();

    private BlobServiceClient _blobServiceClient;
    private ServiceBusSender _serviceBusSender;

    public Home(
        BlobServiceClient blobServiceClient,
        IAzureClientFactory<ServiceBusSender> senderFactory)
    {
         _blobServiceClient = blobServiceClient;
        _serviceBusSender = senderFactory.CreateClient("queue1");
    }

Pour plus d’informations, consultez l’injection de dépendances avec le Kit de développement logiciel (SDK) Azure pour .NET.

S’authentifier avec Microsoft Entra ID

L’authentification basée sur les jetons avec l’ID Microsoft Entra est l’approche recommandée pour authentifier les demandes auprès des services Azure. Pour autoriser ces demandes, le contrôle d’accès en fonction du rôle (RBAC) Azure gère l’accès aux ressources Azure en fonction de l’identité Microsoft Entra d’un utilisateur et des rôles attribués.

Utilisez la bibliothèque Azure Identity pour la prise en charge de l’authentification basée sur les jetons mentionnée ci-dessus. La bibliothèque fournit des classes telles que DefaultAzureCredential la simplification de la configuration des connexions sécurisées. DefaultAzureCredential prend en charge plusieurs méthodes d’authentification et détermine quelle méthode doit être utilisée au moment de l’exécution. Cette approche permet à votre application d’utiliser différentes méthodes d’authentification dans différents environnements (local ou production) sans implémenter de code spécifique à l’environnement. Pour plus d’informations sur ces rubriques, consultez la section Authentification du Kit de développement logiciel (SDK) Azure pour .NET.

Remarque

De nombreux services Azure vous permettent également d’autoriser les demandes à l’aide de clés. Toutefois, cette approche doit être utilisée avec prudence. Les développeurs doivent être vigilants pour ne jamais exposer la clé d’accès dans un emplacement non sécurisé. Toute personne disposant de la clé d’accès peut autoriser les demandes sur la ressource Azure associée.

Ajoutez le package Azure.Identity :
```
dotnet add package Azure.Identity
```

Dans le Program.cs fichier de votre application, appelez la UseCredential méthode d’extension de la Microsoft.Extensions.Azure bibliothèque pour définir une instance partagée DefaultAzureCredential pour tous les clients de service Azure inscrits :

builder.Services.AddAzureClients(clientBuilder =>
{
    // Register a client for each Azure service using inline configuration
    clientBuilder.AddSecretClient(new Uri("<key_vault_url>"));
    clientBuilder.AddBlobServiceClient(new Uri("<storage_url>"));
    clientBuilder.AddServiceBusClientWithNamespace(
        "<your_namespace>.servicebus.windows.net");

    // Register a subclient for each Azure Service Bus Queue
    var queueNames = new string[] { "queue1", "queue2" };
    foreach (string queue in queueNames)
    {
        clientBuilder.AddClient<ServiceBusSender, ServiceBusClientOptions>(
            (_, _, provider) => provider.GetService<ServiceBusClient>()
                    .CreateSender(queue)).WithName(queue);
    }

    // Register a shared credential for Microsoft Entra ID authentication
    clientBuilder.UseCredential(new DefaultAzureCredential());
});

DefaultAzureCredential découvre les informations d’identification disponibles dans l’environnement actuel et les utilise pour s’authentifier auprès des services Azure. Pour connaître l’ordre et les emplacements dans lesquels DefaultAzureCredential les analyses d’informations d’identification sont effectuées, consultez la vue d’ensemble de DefaultAzureCredential. L’utilisation d’une instance partagée DefaultAzureCredential garantit que le cache de jetons sous-jacent est utilisé, ce qui améliore la résilience et les performances des applications en raison de moins de demandes pour un nouveau jeton.

Appliquer des configurations

Les clients du service sdk Azure prennent en charge les configurations pour modifier leurs comportements par défaut. Il existe deux façons de configurer les clients de service :

Les fichiers de configuration JSON sont généralement l’approche recommandée, car ils simplifient la gestion des différences dans les déploiements d’applications entre les environnements.
Les configurations de code inline peuvent être appliquées lorsque vous inscrivez le client de service. Par exemple, dans la section Inscrire des clients et des sous-clients, vous avez transmis explicitement les variables d’URI aux constructeurs clients.

IConfiguration Les règles de précédence sont respectées par les Microsoft.Extensions.Azure méthodes d’extension, qui sont détaillées dans la documentation des fournisseurs de configuration.

Effectuez les étapes décrites dans les sections suivantes pour mettre à jour votre application afin d’utiliser la configuration de fichiers JSON pour les environnements appropriés. Utilisez le appsettings.Development.json fichier pour les paramètres de développement et le appsettings.Production.json fichier pour les paramètres d’environnement de production. Vous pouvez ajouter des paramètres de configuration dont les noms sont des propriétés publiques sur la ClientOptions classe au fichier JSON.

Configurer les services inscrits

Mettez à jour le appsettings.<environment>.json fichier dans votre application avec les configurations de service en surbrillance :
```
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Azure.Messaging.ServiceBus": "Debug"
    }
  },
  "AzureDefaults": {
    "Diagnostics": {
      "IsTelemetryDisabled": false,
      "IsLoggingContentEnabled": true
    },
    "Retry": {
      "MaxRetries": 3,
      "Mode": "Exponential"
    }
  },
  "KeyVault": {
    "VaultUri": "https://<your-key-vault-name>.vault.azure.net"
  },
  "ServiceBus": {
    "Namespace": "<your_service-bus_namespace>.servicebus.windows.net"
  },
  "Storage": {
    "ServiceUri": "https://<your-storage-account-name>.storage.windows.net"
  }
}
```
Dans l’exemple JSON précédent :
- Les noms de clés de niveau supérieur, KeyVault, ServiceBuset , et Storage, sont des noms arbitraires utilisés pour référencer les sections de configuration à partir de votre code. Vous transmettez ces noms aux méthodes d’extension AddClient pour configurer un client donné. Tous les autres noms de clés correspondent à des options client spécifiques, et la sérialisation JSON est effectuée de manière non sensible à la casse.
- Les KeyVault:VaultUrivaleurs , ServiceBus:Namespaceet Storage:ServiceUri clés sont mappées aux arguments des SecretClient(Uri, TokenCredential, SecretClientOptions)ServiceBusClient(String)surcharges , et BlobServiceClient(Uri, TokenCredential, BlobClientOptions) constructeur, respectivement. Les variantes TokenCredential des constructeurs sont utilisées, car une valeur par défaut TokenCredential est définie via l’appel de méthode UseCredential(TokenCredential).

Mettez à jour le Program.cs fichier pour récupérer les configurations de fichiers JSON à l’aide IConfiguration de vos inscriptions de service et les transmettre à vos inscriptions de service :

builder.Services.AddAzureClients(clientBuilder =>
{
    // Register clients using a config file section
    clientBuilder.AddSecretClient(
        builder.Configuration.GetSection("KeyVault"));

    clientBuilder.AddBlobServiceClient(
        builder.Configuration.GetSection("Storage"));

    // Register clients using a specific config key-value pair
    clientBuilder.AddServiceBusClientWithNamespace(
        builder.Configuration["ServiceBus:Namespace"]);

Configurer les valeurs par défaut et les nouvelles tentatives Azure

Vous pouvez modifier les configurations de client Azure par défaut globalement ou pour un client de service spécifique. Par exemple, vous pouvez souhaiter des paramètres de nouvelles tentatives différents ou utiliser une autre version de l’API de service. Vous pouvez définir les paramètres de nouvelles tentatives globalement ou par service.

Mettez à jour votre fichier de configuration pour définir les paramètres Azure par défaut, tels qu’une nouvelle stratégie de nouvelle tentative par défaut que tous les clients Azure inscrits utiliseront :

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Azure.Messaging.ServiceBus": "Debug"
    }
  },
  "AzureDefaults": {
    "Diagnostics": {
      "IsTelemetryDisabled": false,
      "IsLoggingContentEnabled": true
    },
    "Retry": {
      "MaxRetries": 3,
      "Mode": "Exponential"
    }
  },
  "KeyVault": {
    "VaultUri": "https://<your-key-vault-name>.vault.azure.net"
  },
  "ServiceBus": {
    "Namespace": "<your_service-bus_namespace>.servicebus.windows.net"
  },
  "Storage": {
    "ServiceUri": "https://<your-storage-account-name>.storage.windows.net"
  }
}

Dans le Program.cs fichier, appelez la ConfigureDefaults méthode d’extension pour récupérer les paramètres par défaut et les appliquer à vos clients de service :

builder.Services.AddAzureClients(clientBuilder =>
{
    // Register clients using a config file section
    clientBuilder.AddSecretClient(
        builder.Configuration.GetSection("KeyVault"));

    clientBuilder.AddBlobServiceClient(
        builder.Configuration.GetSection("Storage"));

    // Register clients using a specific config key-value pair
    clientBuilder.AddServiceBusClientWithNamespace(
        builder.Configuration["ServiceBus:Namespace"]);

    // Register a subclient for each Azure Service Bus Queue
    string[] queueNames = [ "queue1", "queue2" ];
    foreach (string queue in queueNames)
    {
        clientBuilder.AddClient<ServiceBusSender, ServiceBusClientOptions>(
            (_, _, provider) => provider.GetService<ServiceBusClient>()
                    .CreateSender(queue)).WithName(queue);
    }

    clientBuilder.UseCredential(new DefaultAzureCredential());

    // Set up any default settings
    clientBuilder.ConfigureDefaults(
        builder.Configuration.GetSection("AzureDefaults"));
});

Configuration de la journalisation

Le Kit de développement logiciel (SDK) Azure pour les bibliothèques clientes .NET peut journaliser les opérations de bibliothèque de client pour surveiller les demandes et les réponses aux services Azure. Les bibliothèques clientes peuvent également consigner diverses autres événements, notamment les nouvelles tentatives, la récupération de jetons et les événements spécifiques au service de différents clients. Lorsque vous inscrivez un client du Kit de développement logiciel (SDK) Azure à l’aide de la AddAzureClients méthode d’extension, celui-ci AzureEventSourceLogForwarder est inscrit auprès du conteneur d’injection de dépendances. Le AzureEventSourceLogForwarder transfert des messages de journalisation à partir de sources d’événements du Kit de développement logiciel (SDK) Azure pour ILoggerFactory vous permettre d’utiliser la configuration de journalisation standard ASP.NET Core pour la journalisation.

Le tableau suivant montre comment le EventLevel du SDK Azure pour .NET est mappé au LogLevel ASP.NET Core. Pour plus d’informations sur ces rubriques et d’autres scénarios, consultez Journalisation avec le Kit de développement logiciel (SDK) Azure pour .NET et l’injection de dépendances avec le Kit de développement logiciel (SDK) Azure pour .NET.

Kit de développement logiciel (SDK) Azure `EventLevel`	ASP.NET Core `LogLevel`
`Critical`	`Critical`
`Error`	`Error`
`Informational`	`Information`
`Warning`	`Warning`
`Verbose`	`Debug`
`LogAlways`	`Information`

Vous pouvez modifier les niveaux de journal par défaut et d’autres paramètres à l’aide des mêmes configurations JSON décrites dans la section Configurer l’authentification. Par exemple, basculez le niveau du ServiceBusClient journal en Debug définissant la Logging:LogLevel:Azure.Messaging.ServiceBus clé comme suit :

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Azure.Messaging.ServiceBus": "Debug"
    }
  },
  "AzureDefaults": {
    "Diagnostics": {
      "IsTelemetryDisabled": false,
      "IsLoggingContentEnabled": true
    },
    "Retry": {
      "MaxRetries": 3,
      "Mode": "Exponential"
    }
  },
  "KeyVault": {
    "VaultUri": "https://<your-key-vault-name>.vault.azure.net"
  },
  "ServiceBus": {
    "Namespace": "<your_service-bus_namespace>.servicebus.windows.net"
  },
  "Storage": {
    "ServiceUri": "https://<your-storage-account-name>.storage.windows.net"
  }
}

Partager via