integrazione di Archiviazione delle Code per .NET AspireeAzure

include:integrazione dell'hosting e Client integrazione

Azure Queue Storage è un servizio per l'archiviazione di un numero elevato di messaggi a cui è possibile accedere da qualsiasi parte del mondo attraverso chiamate autenticate. L'integrazione con il servizio di code .NET AspireAzure consente di connettersi alle istanze esistenti del servizio di code Azure o di creare nuove istanze dalle applicazioni .NET.

Integrazione dell'hosting

I modelli di integrazione .NET.NET AspireAzure di hosting rappresentano le varie risorse di archiviazione nei seguenti tipi:

• AzureStorageResource: rappresenta una risorsa di archiviazione Azure.
• AzureStorageEmulatorResource: rappresenta una risorsa emulatore di archiviazione Azure (Azurite).
• AzureBlobStorageResource: rappresenta una risorsa di archiviazione BLOB Azure.
• AzureQueueStorageResource: rappresenta una risorsa di archiviazione code Azure.
• AzureTableStorageResource: rappresenta una risorsa di archiviazione di tabelle Azure.

Per accedere a questi tipi e alle API per esprimerli, aggiungere il pacchetto NuGet 📦Aspire.Hosting.Azure.Storage nel progetto host dell'applicazione .

dotnet add package Aspire.Hosting.Azure.Storage

<PackageReference Include="Aspire.Hosting.Azure.Storage"
                  Version="*" />

Per altre informazioni, vedere dotnet add package o Manage package dependencies in .NET applications.

Aggiungere la risorsa di archiviazione Azure

Nel progetto host della tua app, chiama AddAzureStorage per aggiungere e restituire un costruttore di risorse di archiviazione Azure.

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage");

// An Azure Storage resource is required to add any of the following:
//
// - Azure Blob storage resource.
// - Azure Queue storage resource.
// - Azure Table storage resource.

// After adding all resources, run the app...

Quando si aggiunge un AzureStorageResource all'host dell'app, espone altre API utili per aggiungere Azure risorse di archiviazione BLOB, code e tabelle. In altre parole, è necessario aggiungere un AzureStorageResource prima di aggiungere qualsiasi altra risorsa di archiviazione.

Generazione del provisioning Bicep

Se sei nuovo a Bicep, si tratta di un linguaggio specifico per definire le risorse Azure. Con .NET.NET Aspire, non è necessario scrivere manualmente Bicep, poiché le API di provisioning generano automaticamente Bicep per te. Quando si pubblica l'app, il Bicep generato viene prodotto insieme al file di manifesto. Quando si aggiunge una risorsa di archiviazione Azure, viene generato il seguente Bicep:

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param principalId string

param principalType string

resource storage 'Microsoft.Storage/storageAccounts@2024-01-01' = {
  name: take('storage${uniqueString(resourceGroup().id)}', 24)
  kind: 'StorageV2'
  location: location
  sku: {
    name: 'Standard_GRS'
  }
  properties: {
    accessTier: 'Hot'
    allowSharedKeyAccess: false
    minimumTlsVersion: 'TLS1_2'
    networkAcls: {
      defaultAction: 'Allow'
    }
  }
  tags: {
    'aspire-resource-name': 'storage'
  }
}

resource blobs 'Microsoft.Storage/storageAccounts/blobServices@2024-01-01' = {
  name: 'default'
  parent: storage
}

resource storage_StorageBlobDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe')
    principalType: principalType
  }
  scope: storage
}

resource storage_StorageTableDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3')
    principalType: principalType
  }
  scope: storage
}

resource storage_StorageQueueDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '974c5e8b-45b9-4653-ba55-5f855dd0fb88'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '974c5e8b-45b9-4653-ba55-5f855dd0fb88')
    principalType: principalType
  }
  scope: storage
}

output blobEndpoint string = storage.properties.primaryEndpoints.blob

output queueEndpoint string = storage.properties.primaryEndpoints.queue

output tableEndpoint string = storage.properties.primaryEndpoints.table

Il Bicep precedente è un modulo che effettua il provisioning di un account di archiviazione Azure con le impostazioni predefinite seguenti.

• kind: tipo di account di archiviazione. Il valore predefinito è StorageV2.
• sku: SKU dell'account di archiviazione. Il valore predefinito è Standard_GRS.
• properties: proprietà dell'account di archiviazione:
  • accessTier: Il livello di accesso dell'account di archiviazione. Il valore predefinito è Hot.
  • allowSharedKeyAccess: valore booleano che indica se l'account di archiviazione consente di autorizzare le richieste con la chiave di accesso dell'account. Il valore predefinito è false.
  • minimumTlsVersion: versione minima supportata di TLS per l'account di archiviazione. Il valore predefinito è TLS1_2.
  • networkAcls: gli ACL di rete per l'account di archiviazione. Il valore predefinito è { defaultAction: 'Allow' }.

Oltre all'account di archiviazione, crea anche un contenitore blob.

Le seguenti assegnazioni di ruolo vengono aggiunte all'account di archiviazione per concedere l'accesso alla tua applicazione. Per altre informazioni, vedere i ruoli predefiniti Azure controllo degli accessi in base al ruolo (Azure controllo degli accessi in base al ruolo):

Il Bicep generato è un punto di partenza e può essere personalizzato per soddisfare i requisiti specifici.

Personalizzare l'infrastruttura di provisioning

Tutte le risorse .NET AspireAzure sono sottoclassi del tipo di AzureProvisioningResource. Questo tipo consente la personalizzazione di Bicep generato fornendo un'API Fluent per configurare le risorse Azure, usando l'API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Ad esempio, è possibile configurare il kind, sku, propertiese altro ancora. L'esempio seguente illustra come personalizzare la risorsa di archiviazione Azure:

builder.AddAzureStorage("storage")
    .ConfigureInfrastructure(infra =>
    {
        var storageAccount = infra.GetProvisionableResources()
                                  .OfType<StorageAccount>()
                                  .Single();

        storageAccount.AccessTier = StorageAccountAccessTier.Cool;
        storageAccount.Sku = new StorageSku { Name = StorageSkuName.PremiumZrs };
        storageAccount.Tags.Add("ExampleKey", "Example value");
    });

Il codice precedente:

• Concatena una chiamata all'API ConfigureInfrastructure:
  • Il parametro infra è un'istanza del tipo AzureResourceInfrastructure.
  • Le risorse provisionabili si recuperano chiamando il metodo GetProvisionableResources().
  • Viene recuperato il singolo StorageAccount.
  • Il StorageAccount.AccessTier viene assegnato a StorageAccountAccessTier.Cool.
  • Il StorageAccount.Sku viene assegnato a un nuovo StorageSku con un Name di PremiumZrs.
  • Un tag viene aggiunto all'account di archiviazione con una chiave di ExampleKey e un valore di Example value.

Sono disponibili molte altre opzioni di configurazione per personalizzare la risorsa di archiviazione Azure. Per altre informazioni, vedere Azure.Provisioning.Storage.

Connetti a un Azure Storage account esistente

Potresti avere un account di archiviazione Azure esistente che desideri connetterti a. Anziché rappresentare una nuova risorsa di archiviazione Azure, è possibile aggiungere una stringa di connessione all'host dell'app. Per aggiungere una connessione a un account di archiviazione Azure esistente, chiamare il metodo AddConnectionString:

var builder = DistributedApplication.CreateBuilder(args);

var blobs = builder.AddConnectionString("blobs");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(blobs);

// After adding all resources, run the app...

La stringa di connessione viene configurata nella configurazione dell'host dell'app, in genere sotto User Secrets, nella sezione ConnectionStrings. L'host dell'app inserisce questa stringa di connessione come variabile di ambiente in tutte le risorse dipendenti, ad esempio:

{
    "ConnectionStrings": {
        "blobs": "https://{account_name}.blob.core.windows.net/"
    }
}

La risorsa dipendente può accedere alla stringa di connessione inserita chiamando il metodo GetConnectionString e passando il nome della connessione come parametro, in questo caso "blobs". L'API GetConnectionString è un'abbreviazione di IConfiguration.GetSection("ConnectionStrings")[name].

Aggiungere risorsa dell'emulatore di storage Azure

Per aggiungere una risorsa dell'emulatore di archiviazione Azure, concatenare una chiamata a un IResourceBuilder<AzureStorageResource> all'API RunAsEmulator:

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage")
                     .RunAsEmulator();

// After adding all resources, run the app...

Quando si chiama RunAsEmulator, configura le risorse di archiviazione per l'esecuzione in locale usando un emulatore. L'emulatore in questo caso è Azurite. L'emulatore open source Azurite offre un ambiente locale gratuito per testare le applicazioni Blob, Queue Storage e Table Storage Azure ed è il compagno ideale per l'integrazione dell'hosting .NET AspireAzure. Azurite non è installato, è invece accessibile a .NET.NET Aspire come contenitore. Quando si aggiunge un contenitore all'host dell'app, come illustrato nell'esempio precedente con l'immagine mcr.microsoft.com/azure-storage/azurite, viene creato e avviato il contenitore all'avvio dell'host dell'app. Per altre informazioni, vedere ciclo di vita delle risorse contenitore.

Configurare il contenitore Azurite

Sono disponibili varie configurazioni per le risorse del contenitore, ad esempio è possibile configurare le porte del contenitore, le variabili di ambiente, la durata e altro ancora.

Configurare le porte del container di Azurite

Per impostazione predefinita, il contenitore Azurite quando configurato da .NET.NET Aspireespone gli endpoint seguenti:

La porta su cui stanno ascoltando è dinamica per impostazione predefinita. All'avvio del contenitore, le porte vengono mappate a una porta casuale nel computer host. Per configurare le porte dell'endpoint, concatenare le chiamate al generatore di risorse del contenitore fornito dal metodo RunAsEmulator, come illustrato nell'esempio seguente:

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage").RunAsEmulator(
                     azurite =>
                     {
                         azurite.WithBlobPort("blob", 27000)
                                .WithQueuePort("queue", 27001)
                                .WithTablePort("table", 27002);
                     });

// After adding all resources, run the app...

Il codice precedente configura gli endpoint esistenti blob, queuee table del contenitore Azurite per l'ascolto rispettivamente sulle porte 27000, 27001e 27002. Le porte del contenitore Azurite vengono mappate alle porte host, come illustrato nella tabella seguente:

Configurare il contenitore Azurite con durata permanente

Per configurare il contenitore Azurite con una durata permanente, chiamare il metodo WithLifetime nella risorsa contenitore Azurite e passare ContainerLifetime.Persistent:

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage").RunAsEmulator(
                     azurite =>
                     {
                         azurite.WithLifetime(ContainerLifetime.Persistent);
                     });

// After adding all resources, run the app...

Per ulteriori informazioni, vedere durata risorsa contenitore.

Configurare il contenitore Azurite con il volume di dati

Per aggiungere un volume di dati alla risorsa emulatore di archiviazione Azure, chiamare il metodo WithDataVolume nella risorsa dell'emulatore di archiviazione Azure:

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage").RunAsEmulator(
                     azurite =>
                     {
                         azurite.WithDataVolume();
                     });

// After adding all resources, run the app...

Il volume di dati viene usato per mantenere persistenti i dati di Azurite al di fuori del ciclo di vita del contenitore. Il volume di dati viene montato nel percorso /data nel contenitore Azurite e quando non viene specificato un parametro name, il nome viene formattato come .azurite/{resource name}. Per ulteriori informazioni sui volumi dati e sui motivi per cui sono preferiti rispetto a bind mount , consultare la documentazione Docker: Volumi.

Configurare il contenitore Azurite con il montaggio dell'associazione dati

Per aggiungere un bind mount dei dati alla risorsa dell'emulatore di archiviazione Azure, utilizzare il metodo WithDataBindMount:

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage").RunAsEmulator(
                     azurite =>
                     {
                         azurite.WithDataBindMount("../Azurite/Data");
                     });

// After adding all resources, run the app...

I montaggi di associazione dati si basano sul file system del computer host per rendere persistenti i dati di Azurite tra i riavvii dei contenitori. Il montaggio dell'associazione dati viene montato nel percorso ../Azurite/Data nel computer host rispetto alla directory host dell'app (IDistributedApplicationBuilder.AppHostDirectory) nel contenitore Azurite. Per altre informazioni sui montaggi di associazione dati, vedere Docker docs: Bind mounts.

Connettersi alle risorse di archiviazione

Quando l'host dell'app .NET.NET Aspire è in esecuzione, le risorse di archiviazione possono essere accessibili da strumenti esterni, come Azure Storage Explorer. Se la risorsa di archiviazione è in esecuzione in locale tramite Azurite, verrà prelevata automaticamente dal Azure Storage Explorer.

Per connettersi alla risorsa di archiviazione da Azure Storage Explorer, seguire questa procedura:

1. Esegui l'host dell'app .NET.NET Aspire.

2. Aprire Azure Storage Explorer.

3. Visualizzare il riquadro esplora.

4. Selezionare il collegamento Aggiorna tutto per aggiornare l'elenco degli account di archiviazione dati.

5. Espandere il nodo emulatore & collegato.

6. Espandi il nodo account di archiviazione.

7. Dovresti vedere un account di archiviazione con il nome della tua risorsa come prefisso.

   

È possibile esplorare l'account di archiviazione e il relativo contenuto usando Azure Storage Explorer. Per altre informazioni sull'uso di Azure Storage Explorer, vedere Introduzione a Storage Explorer.

Aggiungere risorsa di Archiviazione in coda Azure

Nel progetto host dell'app registrare l'integrazione dell'archiviazione code Azure concatenando una chiamata a AddQueues nell'istanza di IResourceBuilder<IAzureStorageResource> restituita da AddAzureStorage. Nell'esempio seguente viene illustrato come aggiungere una risorsa di archiviazione code Azure denominata storage e una risorsa di coda denominata queues:

var builder = DistributedApplication.CreateBuilder(args);

var queues = builder.AddAzureStorage("storage")
                    .AddQueues("queues");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(queues);

// After adding all resources, run the app...

Il codice precedente:

• Aggiunge una risorsa di archiviazione Azure denominata storage.
• Aggiunge una coda denominata queues alla risorsa di archiviazione.
• Aggiunge la risorsa storage al ExampleProject e attende che sia pronta prima di avviare il progetto.

Hosting dei controlli di integrità dell'integrazione

L'integrazione di hosting di archiviazione Azure aggiunge automaticamente un controllo di integrità per la risorsa di archiviazione. Viene aggiunto solo quando viene eseguito come emulatore e verifica che il contenitore Azurite sia in esecuzione e che sia possibile stabilire una connessione. L'integrazione dell'hosting si basa sul pacchetto NuGet AspNetCore.HealthChecks.📦.Storage.Blobs Azure.

integrazione Client

Per iniziare a usare l'integrazione Queue Storage .NET Aspire di Azureclient, installare il pacchetto NuGet 📦Aspire.Azure.Storage.Queues nel progetto che utilizza client, cioè il progetto per l'applicazione che usa il Queue Storage Azureclient. L'integrazione di Archiviazione code Azureclient registra un'istanza di QueueServiceClient da utilizzare per interagire con l'Archiviazione code Azure.

dotnet add package Aspire.Azure.Storage.Queues

<PackageReference Include="Aspire.Azure.Storage.Queues"
                  Version="*" />

Aggiungere Azure la archiviazione delle code client

Nel file Program.cs del progetto clientdi consumo, chiamare il metodo di estensione AddAzureQueueClient su qualsiasi IHostApplicationBuilder per registrare un QueueServiceClient da usare tramite il contenitore per l'inserimento delle dipendenze. Il metodo accetta un parametro del nome di connessione.

builder.AddAzureQueueClient("queue");

È quindi possibile recuperare l'istanza di QueueServiceClient usando l'iniezione delle dipendenze. Ad esempio, per recuperare il client da un servizio:

public class ExampleService(QueueServiceClient client)
{
    // Use client...
}

Configurazione

L'integrazione dell'archiviazione delle code di .NET AspireAzure offre diverse opzioni per configurare le QueueServiceClient in base ai requisiti e alle convenzioni del tuo progetto.

Usare una stringa di connessione

Quando si usa una stringa di connessione dalla sezione di configurazione ConnectionStrings, è possibile specificare il nome della stringa di connessione quando si chiama AddAzureQueueClient:

builder.AddAzureQueueClient("queue");

La stringa di connessione viene quindi recuperata dalla sezione di configurazione ConnectionStrings e sono supportati due formati di connessione:

URI del servizio

L'approccio consigliato consiste nell'usare un ServiceUri, che funziona con la proprietà AzureStorageQueuesSettings.Credential per stabilire una connessione. Se non è configurata alcuna credenziale, viene usato il Azure.Identity.DefaultAzureCredential.

{
  "ConnectionStrings": {
    "queue": "https://{account_name}.queue.core.windows.net/"
  }
}

Stringa di connessione

In alternativa, è possibile usare una stringa di connessione di archiviazione Azure.

{
  "ConnectionStrings": {
    "queue": "AccountName=myaccount;AccountKey=myaccountkey"
  }
}

Per altre informazioni, vedere Configurare le stringhe di connessione di archiviazione Azure.

Usare i provider di configurazione

L'integrazione dell'archiviazione delle code di .NET AspireAzure supporta Microsoft.Extensions.Configuration. Carica il AzureStorageQueuesSettings e il QueueClientOptions dalla configurazione usando la chiave Aspire:Azure:Storage:Queues. Il frammento di codice seguente è un esempio di un file appsettings.json che configura alcune delle opzioni:

{
  "Aspire": {
    "Azure": {
      "Storage": {
        "Queues": {
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "Diagnostics": {
              "ApplicationId": "myapp"
            }
          }
        }
      }
    }
  }
}

Per lo schema completo Azure Storage Queuesclient di integrazione JSON, vedere Aspire.Azure. Data.Queues/ConfigurationSchema.json.

Usare delegati inline

È anche possibile passare il delegate Action<AzureStorageQueuesSettings> configureSettings per configurare alcune o tutte le opzioni inline, ad esempio per configurare i controlli di stato:

builder.AddAzureQueueClient(
    "queue",
    settings => settings.DisableHealthChecks = true);

È possibile configurare anche il QueueClientOptions tramite il delegato Action<IAzureClientBuilder<QueueServiceClient, QueueClientOptions>> configureClientBuilder, che è il secondo parametro del metodo AddAzureQueueClient. Ad esempio, per impostare la prima parte delle intestazioni dell'agente utente per tutte le richieste inviate da questo client:

builder.AddAzureQueueClient(
    "queue",
    configureClientBuilder: clientBuilder =>
        clientBuilder.ConfigureOptions(
            options => options.Diagnostics.ApplicationId = "myapp"));

Client controlli di integrità dell'integrazione

Per impostazione predefinita, le integrazioni di .NET.NET Aspire abilitano controlli di integrità per tutti i servizi. Per altre informazioni, vedere panoramica delle integrazioni .NET.NET Aspire.

Integrazione con l'archiviazione in coda di .NET AspireAzure

• Aggiunge il controllo di integrità quando AzureStorageQueuesSettings.DisableHealthChecks è false, che tenta di connettersi all'archiviazione delle code Azure.
• Si integra con l'endpoint HTTP /health, che specifica che tutti i controlli di integrità registrati devono essere superati affinché l'app sia considerata pronta per accettare il traffico.

Osservabilità e telemetria

.NET .NET Aspire le integrazioni configurano automaticamente configurazioni di registrazione, traccia e metriche, talvolta note come i pilastri dell'osservabilità. Per altre informazioni sull'osservabilità e la telemetria dell'integrazione, vedere panoramica delle integrazioni .NET.NET Aspire. A seconda del servizio di backup, alcune integrazioni possono supportare solo alcune di queste funzionalità. Ad esempio, alcune integrazioni supportano la registrazione e la traccia, ma non le metriche. Le funzionalità di telemetria possono essere disabilitate anche usando le tecniche presentate nella sezione Configurazione .

Registrazione

L'integrazione di archiviazione delle code di .NET AspireAzure utilizza le seguenti categorie di log:

• Azure.Core
• Azure.Identity

Tracciamento

L'integrazione dell'archiviazione delle code di .NET AspireAzure genera le seguenti attività di tracciamento usando OpenTelemetry:

• Azure.Storage.Queues.QueueClient

Metriche

L'integrazione di archiviazione code di .NET AspireAzure attualmente non supporta per impostazione predefinita le metriche a causa delle limitazioni dell'SDK Azure.

Vedere anche

• Azure documentazione di Archiviazione Code
• .NET .NET Aspire integrazioni
• .NET Aspire GitHub repo