Usare Azure SDK per .NET nelle app ASP.NET Core

Articolo
11/16/2024

Azure SDK per .NET consente alle app ASP.NET Core di integrarsi con molti servizi di Azure diversi. Questo articolo illustra le procedure consigliate e i passaggi per adottare Azure SDK per .NET nelle app ASP.NET Core. Si apprenderà come:

Registrare i servizi per l'inserimento delle dipendenze.
Eseguire l'autenticazione in Azure senza usare password o segreti.
Implementare una configurazione centralizzata standardizzata.
Configurare problemi comuni dell'app Web, ad esempio la registrazione e i tentativi.

Esplorare le librerie client comuni di Azure SDK

ASP.NET app core che si connettono ai servizi di Azure dipendono in genere dalle librerie client di Azure SDK seguenti:

Microsoft.Extensions.Azure fornisce metodi helper per registrare i client con la raccolta di servizi di inserimento delle dipendenze e gestisce vari problemi, ad esempio la configurazione della registrazione, la gestione della durata del servizio di inserimento delle dipendenze e la gestione delle credenziali di autenticazione.
Azure.Identity abilita il supporto per l'autenticazione di Microsoft Entra ID in Azure SDK. Fornisce un set di implementazioni di TokenCredential per costruire client Azure SDK che supportano l'autenticazione di Microsoft Entra.
Azure.<service-namespace> librerie, ad esempio Azure.Storage.Blobs e Azure.Messaging.ServiceBus, forniscono client di servizio e altri tipi per consentire la connessione e l'utilizzo di servizi di Azure specifici. Per un inventario completo di queste librerie, vedere Librerie con Azure.Core.

Nelle sezioni successive si esaminerà come implementare un'applicazione ASP.NET Core che usa queste librerie.

Registrare i client Azure SDK con la raccolta di servizi di inserimento delle dipendenze

Le librerie client di Azure SDK per .NET forniscono client di servizio per connettere l'app ai servizi di Azure, ad esempio Archiviazione BLOB di Azure e Azure Key Vault. Registrare questi servizi con il contenitore di dipendenze nel Program.cs file dell'app per renderli disponibili tramite inserimento delle dipendenze.

Completare i passaggi seguenti per registrare i servizi necessari:

Aggiungere il pacchetto Microsoft.Extensions.Azure :
```
dotnet add package Microsoft.Extensions.Azure
```

Aggiungere i pacchetti client del servizio pertinenti Azure.* :

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

Program.cs Nel file dell'app richiamare il AddAzureClients metodo di estensione dalla Microsoft.Extensions.Azure libreria per registrare un client per comunicare con ogni servizio di Azure. Alcune librerie client forniscono sottoclienti aggiuntivi per sottogruppi specifici della funzionalità del servizio di Azure. È possibile registrare tali sottoclienti per l'inserimento delle dipendenze tramite il AddClient metodo di estensione.

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

Inserire i client registrati nell'endpoint dell'app core ASP.NET:

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

Per altre informazioni, vedere Inserimento di dipendenze con Azure SDK per .NET.

Eseguire l'autenticazione con Microsoft Entra ID

L'autenticazione basata su token con Microsoft Entra ID è l'approccio consigliato per autenticare le richieste ai servizi di Azure. Per autorizzare tali richieste, il controllo degli accessi in base al ruolo di Azure gestisce l'accesso alle risorse di Azure in base all'identità di Microsoft Entra di un utente e ai ruoli assegnati.

Usare la libreria di identità di Azure per il supporto dell'autenticazione basata su token. La libreria fornisce classi come DefaultAzureCredential per semplificare la configurazione delle connessioni sicure. DefaultAzureCredential supporta più metodi di autenticazione e determina il metodo da usare in fase di esecuzione. Questo approccio consente all'app di usare metodi di autenticazione diversi in ambienti diversi (locale e di produzione) senza implementare codice specifico dell'ambiente. Per altre informazioni su questi argomenti, vedere la sezione Relativa all'autenticazione della documentazione di Azure SDK per .NET.

Nota

Molti servizi di Azure consentono anche di autorizzare le richieste usando le chiavi. Tuttavia, questo approccio deve essere usato con cautela. Gli sviluppatori devono essere diligenti per non esporre mai la chiave di accesso in una posizione non sicura. Chiunque abbia la chiave di accesso può autorizzare le richieste alla risorsa di Azure associata.

Aggiungere il pacchetto Azure.Identity :
```
dotnet add package Azure.Identity
```

Program.cs Nel file dell'app richiamare il UseCredential metodo di estensione dalla Microsoft.Extensions.Azure libreria per impostare un'istanza condivisa DefaultAzureCredential per tutti i client del servizio di Azure registrati:

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 individua le credenziali disponibili nell'ambiente corrente e le usa per eseguire l'autenticazione ai servizi di Azure. Per l'ordine e le posizioni in cui DefaultAzureCredential vengono esaminate le credenziali, vedere Panoramica di DefaultAzureCredential. L'uso di un'istanza condivisa DefaultAzureCredential garantisce che venga usata la cache dei token sottostante, migliorando la resilienza e le prestazioni dell'applicazione a causa di un minor numero di richieste per un nuovo token.

Applicare configurazioni

I client del servizio Azure SDK supportano le configurazioni per modificare i comportamenti predefiniti. Esistono due modi per configurare i client del servizio:

I file di configurazione JSON sono in genere l'approccio consigliato perché semplificano la gestione delle differenze nelle distribuzioni di app tra ambienti.
Le configurazioni del codice inline possono essere applicate quando si registra il client del servizio. Ad esempio, nella sezione Registra client e sottoclienti è stata passata in modo esplicito le variabili URI ai costruttori client.

IConfiguration le regole di precedenza vengono rispettate dai metodi di Microsoft.Extensions.Azure estensione, descritti in dettaglio nella documentazione relativa ai provider di configurazione.

Completare la procedura descritta nelle sezioni seguenti per aggiornare l'app per usare la configurazione dei file JSON per gli ambienti appropriati. Usare il appsettings.Development.json file per le impostazioni di sviluppo e il file per le impostazioni dell'ambiente appsettings.Production.json di produzione. È possibile aggiungere impostazioni di configurazione i cui nomi sono proprietà pubbliche nella ClientOptions classe al file JSON.

Configurare i servizi registrati

Aggiornare il appsettings.<environment>.json file nell'app con le configurazioni del servizio evidenziate:
```
{
  "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"
  }
}
```
Nel campione JSON precedente:
- I nomi delle chiavi di primo livello, , KeyVaultServiceBus, e Storagesono nomi arbitrari usati per fare riferimento alle sezioni di configurazione dal codice. Questi nomi verranno passati ai metodi di AddClient estensione per configurare un determinato client. Tutti gli altri nomi di chiave eseguono il mapping a opzioni client specifiche e la serializzazione JSON viene eseguita senza distinzione tra maiuscole e minuscole.
- I KeyVault:VaultUrivalori della chiave , ServiceBus:Namespaceeseguono Storage:ServiceUri rispettivamente il mapping agli argomenti degli overload del SecretClient(Uri, TokenCredential, SecretClientOptions)costruttore , ServiceBusClient(String)e BlobServiceClient(Uri, TokenCredential, BlobClientOptions) . Le varianti TokenCredential dei costruttori vengono utilizzate perché un valore predefinito TokenCredential viene impostato tramite la chiamata al metodo UseCredential(TokenCredential).

Aggiornare il Program.cs file per recuperare le configurazioni dei file JSON usando IConfiguration e passarle nelle registrazioni del servizio:

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

Configurare le impostazioni predefinite e i tentativi di Azure

È possibile modificare le configurazioni client predefinite di Azure a livello globale o per un client di servizio specifico. Ad esempio, è possibile che si vogliano impostazioni di ripetizione diverse o usare una versione diversa dell'API del servizio. È possibile impostare le impostazioni di ripetizione a livello globale o in base al servizio.

Aggiornare il file di configurazione per impostare le impostazioni di Azure predefinite, ad esempio un nuovo criterio di ripetizione dei tentativi predefinito che tutti i client di Azure registrati useranno:

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

Program.cs Nel file chiamare il ConfigureDefaults metodo di estensione per recuperare le impostazioni predefinite e applicarle ai client del servizio:

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

Configurare la registrazione

Le librerie client di Azure SDK per .NET possono registrare le operazioni della libreria client per monitorare le richieste e le risposte ai servizi di Azure. Le librerie client possono anche registrare diversi altri eventi, tra cui tentativi, recupero di token ed eventi specifici del servizio da diversi client. Quando si registra un client di Azure SDK usando il AddAzureClients metodo di estensione, viene AzureEventSourceLogForwarder registrato con il contenitore di inserimento delle dipendenze. Inoltra AzureEventSourceLogForwarder i messaggi di log dalle origini eventi di Azure SDK a ILoggerFactory per consentire di usare la configurazione di registrazione standard ASP.NET Core per la registrazione.

La tabella seguente illustra il mapping di EventLevel in Azure SDK per .NET a LogLevel in ASP.NET Core. Per altre informazioni su questi argomenti e altri scenari, vedere Registrazione con Azure SDK per .NET e Inserimento di dipendenze con Azure SDK per .NET.

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

È possibile modificare i livelli di log predefiniti e altre impostazioni usando le stesse configurazioni JSON descritte nella sezione Configurare l'autenticazione . Ad esempio, attivare o disattivare il ServiceBusClient livello Debug di log impostando la Logging:LogLevel:Azure.Messaging.ServiceBus chiave come indicato di seguito:

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

Condividi tramite