Compartir a través de

Uso del SDK de Azure para .NET en aplicaciones de ASP.NET Core

  • Artículo

El SDK de Azure para .NET permite que las aplicaciones de ASP.NET Core se integren con muchos servicios de Azure diferentes. En este artículo, aprenderá los procedimientos recomendados y los pasos para adoptar el SDK de Azure para .NET en las aplicaciones de ASP.NET Core. Aprenderá a:

  • Registrar servicios para la inserción de dependencias.
  • Autentíquese en Azure sin usar contraseñas ni secretos.
  • Implemente una configuración centralizada y estandarizada.
  • Configure problemas comunes de la aplicación web, como el registro y los reintentos.

Exploración de bibliotecas cliente comunes del SDK de Azure

ASP.NET aplicaciones principales que se conectan a los servicios de Azure suelen depender de las siguientes bibliotecas cliente del SDK de Azure:

  • Microsoft.Extensions.Azure proporciona métodos auxiliares para registrar clientes con la recopilación del servicio de inserción de dependencias y controla diversos problemas para usted, como la configuración del registro, el control de la duración del servicio de inserción de dependencias y la administración de credenciales de autenticación.
  • Azure.Identity habilita la compatibilidad con la autenticación del identificador de Entra de Microsoft en el SDK de Azure. Proporciona un conjunto de implementaciones de TokenCredential para construir clientes del SDK de Azure que admiten la autenticación de Microsoft Entra.
  • Azure.<service-namespace> las bibliotecas, como Azure.Storage.Blobs y Azure.Messaging.ServiceBus, proporcionan clientes de servicio y otros tipos para ayudarle a conectarse y consumir servicios específicos de Azure. Para obtener un inventario completo de estas bibliotecas, consulte Bibliotecas con Azure.Core.

En las secciones siguientes, explorará cómo implementar una aplicación ASP.NET Core que use estas bibliotecas.

Registro de clientes del SDK de Azure con la colección de servicios de inserción de dependencias

Las bibliotecas cliente de Azure SDK para .NET proporcionan clientes de servicio para conectar la aplicación a servicios de Azure, como Azure Blob Storage y Azure Key Vault. Registre estos servicios con el contenedor de dependencias en el archivo de la Program.cs aplicación para que estén disponibles a través de la inserción de dependencias.

Complete los pasos siguientes para registrar los servicios que necesita:

  1. Agregue el paquete Microsoft.Extensions.Azure :

    dotnet add package Microsoft.Extensions.Azure

  2. Agregue los paquetes de cliente de servicio pertinentes Azure.* :

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

  3. En el Program.cs archivo de la aplicación, invoque el AddAzureClients método de extensión desde la Microsoft.Extensions.Azure biblioteca para registrar un cliente para comunicarse con cada servicio de Azure. Algunas bibliotecas cliente proporcionan subclientes adicionales para subgrupos específicos de la funcionalidad del servicio de Azure. Puede registrar estos subclientes para la inserción de dependencias mediante el método de AddClient extensión.

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

  4. Inserte los clientes registrados en los componentes de la aplicación, los servicios o el punto de conexión de API de ASP.NET Core:

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

Para más información, consulte Inserción de dependencias con el SDK de Azure para .NET.

Autenticación mediante Microsoft Entra ID

La autenticación basada en tokens con el identificador de Entra de Microsoft es el enfoque recomendado para autenticar solicitudes en los servicios de Azure. Para autorizar esas solicitudes, el control de acceso basado en rol (RBAC) de Azure administra el acceso a los recursos de Azure en función de la identidad de Microsoft Entra de un usuario y los roles asignados.

Use la biblioteca de identidades de Azure para la compatibilidad con la autenticación basada en tokens mencionada anteriormente. La biblioteca proporciona clases como DefaultAzureCredential para simplificar la configuración de conexiones seguras. DefaultAzureCredential admite varios métodos de autenticación y determina el que se debe usar en tiempo de ejecución. Este enfoque permite que la aplicación use diferentes métodos de autenticación en distintos entornos (local frente a producción) sin implementar código específico del entorno. Visite la sección Autenticación de la documentación de Azure SDK para .NET para más información sobre estos temas.

Nota:

Muchos servicios de Azure también permiten autorizar solicitudes mediante claves. Sin embargo, este enfoque debe usarse con precaución. Los desarrolladores deben ser diligentes para no exponer nunca las claves de acceso en una ubicación que no sea segura. Cualquier persona que tenga la clave de acceso puede autorizar solicitudes en el recurso de Azure asociado.

  1. Agregue el paquete Azure.Identity :

    dotnet add package Azure.Identity

  2. En el Program.cs archivo de la aplicación, invoque el UseCredential método de extensión de la Microsoft.Extensions.Azure biblioteca para establecer una instancia compartida DefaultAzureCredential para todos los clientes de servicio de Azure registrados:

    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 detecta las credenciales disponibles en el entorno actual y las usa para autenticarse en los servicios de Azure. Para conocer el orden y las ubicaciones en las que DefaultAzureCredential examina las credenciales, consulte Información general sobre DefaultAzureCredential. El uso de una instancia compartida DefaultAzureCredential garantiza que se use la caché de tokens subyacente, lo que mejora la resistencia y el rendimiento de la aplicación debido a menos solicitudes de un nuevo token.

Aplicación de configuraciones

Los clientes del servicio Azure SDK admiten configuraciones para cambiar sus comportamientos predeterminados. Hay dos maneras de configurar clientes de servicio:

  • Los archivos de configuración JSON suelen ser el enfoque recomendado porque simplifican la administración de diferencias en las implementaciones de aplicaciones entre entornos.
  • Las configuraciones de código insertadas se pueden aplicar al registrar el cliente de servicio. Por ejemplo, en la sección Registrar clientes y subclientes , ha pasado explícitamente las variables de URI a los constructores de cliente.

IConfiguration Los métodos de extensión respetan las Microsoft.Extensions.Azure reglas de precedencia, que se detallan en la documentación de proveedores de configuración.

Complete los pasos descritos en las secciones siguientes para actualizar la aplicación para usar la configuración de archivos JSON para los entornos adecuados. Use el appsettings.Development.json archivo para la configuración de desarrollo y el appsettings.Production.json archivo para la configuración del entorno de producción. Puede agregar opciones de configuración cuyos nombres son propiedades públicas en la ClientOptions clase al archivo JSON.

Configuración de servicios registrados

  1. Actualice el appsettings.<environment>.json archivo de la aplicación con las configuraciones de servicio resaltadas:

    {
  "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"
  }
}

    En la muesta del código JSON anterior:

    • Los nombres de clave de nivel superior, KeyVault, ServiceBusy Storage, son nombres arbitrarios que se usan para hacer referencia a las secciones de configuración desde el código. Estos nombres se pasan a AddClient los métodos de extensión para configurar un cliente determinado. Todos los demás nombres de clave se asignan a opciones de cliente específicas y la serialización JSON se realiza de manera que no distingue mayúsculas de minúsculas.
    • Los KeyVault:VaultUrivalores de clave , ServiceBus:Namespacey Storage:ServiceUri se asignan a los argumentos de las SecretClient(Uri, TokenCredential, SecretClientOptions)sobrecargas del constructor , ServiceBusClient(String)y BlobServiceClient(Uri, TokenCredential, BlobClientOptions) , respectivamente. Las variantes de los constructores TokenCredential se usan porque se establece un valor predeterminado TokenCredential a través de la llamada al método UseCredential(TokenCredential).

  2. Actualice el Program.cs archivo para recuperar las configuraciones del archivo JSON mediante IConfiguration y páselas a los registros de servicio:

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

Configuración de los valores predeterminados y reintentos de Azure

Es posible que quiera cambiar las configuraciones de cliente de Azure predeterminadas globalmente o para un cliente de servicio específico. Por ejemplo, puede que le interese una configuración de reintentos diferente o que prefiera usar una versión de API de servicio diferente. Puede establecer la configuración de reintentos globalmente o por servicio.

  1. Actualice el archivo de configuración para establecer la configuración predeterminada de Azure, como una nueva directiva de reintento predeterminada que usarán todos los clientes registrados de Azure:

    {
  "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"
  }
}

  2. En el Program.cs archivo, llame al método de ConfigureDefaults extensión para recuperar la configuración predeterminada y aplicarla a los clientes de servicio:

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

registro

Las bibliotecas cliente de Azure SDK para .NET pueden registrar operaciones de biblioteca cliente para supervisar las solicitudes y respuestas a los servicios de Azure. Las bibliotecas cliente también pueden registrar una variedad de otros eventos, incluidos reintentos, recuperación de tokens y eventos específicos del servicio de varios clientes. Al registrar un cliente de Azure SDK mediante el AddAzureClients método de extensión, AzureEventSourceLogForwarder se registra con el contenedor de inserción de dependencias. Reenvía AzureEventSourceLogForwarder los mensajes de registro de los orígenes de eventos del SDK de Azure a ILoggerFactory para que pueda usar la configuración de registro estándar ASP.NET Core para el registro.

En la tabla siguiente se muestra cómo se asigna el elemento EventLevel del SDK de Azure para .NET al elemento LogLevel de ASP.NET Core. Para más información sobre estos temas y otros escenarios, consulte Registro con el SDK de Azure para .NET e inserción de dependencias con el SDK de Azure para .NET.

EventLevel de SDK de Azure LogLevel de ASP.NET Core
Critical Critical
Error Error
Informational Information
Warning Warning
Verbose Debug
LogAlways Information

Puede cambiar los niveles de registro predeterminados y otras opciones mediante las mismas configuraciones JSON que se describen en la sección Configuración de la autenticación . Por ejemplo, cambie el nivel de ServiceBusClient registro a Debug estableciendo la clave de la Logging:LogLevel:Azure.Messaging.ServiceBus siguiente manera:

{
  "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"
  }
}