integrazione dell'archiviazione delle code .NET AspireAzure

2025-05-09

Include: —&— Client

Azure Archiviazione code è un servizio per l'archiviazione di un numero elevato di messaggi a cui è possibile accedere da qualsiasi parte del mondo tramite 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 hosting

I modelli di integrazione 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 delle code Azure.
AzureTableStorageResource: rappresenta una risorsa di archiviazione di tabelle Azure.

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

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.Storage

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

Per altre informazioni, vedere dotnet add package o .NET.

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, vengono esposte altre API utili per aggiungere risorse di archiviazione BLOB, code e tabelle Azure. In altre parole, è necessario aggiungere un AzureStorageResource prima di aggiungere qualsiasi altra risorsa di archiviazione.

Importante

Quando si chiama AddAzureStorage, chiama implicitamente AddAzureProvisioning, che aggiunge il supporto per la generazione dinamica delle risorse Azure durante l'avvio dell'app. L'app deve configurare la sottoscrizione e la posizione appropriate. Per ulteriori informazioni, vedere Provisioning locale: Configurazione.

Bicep generato dal provisioning

Se non si ha familiarità con Bicep, si tratta di un linguaggio specifico del dominio per la definizione delle Azure risorse. 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 fornito insieme al file manifest. 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

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
}

output blobEndpoint string = storage.properties.primaryEndpoints.blob

output queueEndpoint string = storage.properties.primaryEndpoints.queue

output tableEndpoint string = storage.properties.primaryEndpoints.table

output name string = storage.name

Il Bicep precedente è un modulo che fornisce un account di archiviazione Azure con le seguenti impostazioni predefinite:

kind: Il tipo di account di archiviazione. Il valore predefinito è StorageV2.
sku: Lo SKU dell'account di archiviazione. Il valore predefinito è Standard_GRS.
properties: Le 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 archivio. Il valore predefinito è { defaultAction: 'Allow' }.

Oltre all'account di archiviazione, allestisce 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 Azure ruoli predefiniti di controllo degli accessi in base al ruolo:Azure

Ruolo/ID	Descrizione
Collaboratore ai dati di archiviazione Blob `ba92f5b4-2d11-453d-a403-e96b0029c9fe`	Leggere, scrivere ed eliminare contenitori e blob di archivio Azure.
Contributore ai dati delle tabelle di archiviazione `0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3`	Leggere, scrivere ed eliminare tabelle ed entità di archiviazione Azure.
Collaboratore ai dati della coda di archivio `974c5e8b-45b9-4653-ba55-5f855dd0fb88`	Leggere, scrivere ed eliminare Azure le code di archiviazione e i messaggi nelle code.

Il Bicep generato è un punto di partenza e viene influenzato dalle modifiche apportate all'infrastruttura di provisioning in C#. Le personalizzazioni apportate direttamente al file Bicep verranno sovrascritte, quindi è necessario effettuare modifiche tramite le API di provisioning C# per garantire che vengano riflesse nei file generati.

Personalizzare l'infrastruttura di provisioning

Tutte le risorse .NET AspireAzure sono sottoclassi del tipo di AzureProvisioningResource. Questo tipo consente la personalizzazione delle risorse Bicep generate fornendo un'API Fluent per configurare le risorse Azure, utilizzando 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 account di archiviazione esistente Azure

Potresti avere un account di archiviazione Azure esistente che desideri connetterti a. È possibile concatenare una chiamata per annotare che il AzureStorageResource è una risorsa esistente:

var builder = DistributedApplication.CreateBuilder(args);

var existingStorageName = builder.AddParameter("existingStorageName");
var existingStorageResourceGroup = builder.AddParameter("existingStorageResourceGroup");

var storageaccount = builder.AddAzureStorage("storage")
                    .AsExisting(existingStorageName, existingStorageResourceGroup)
                    .AddBlobs("blobs");

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

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

Importante

Quando si chiamano i metodi RunAsExisting, PublishAsExisting o AsExisting per usare le risorse già presenti nella sottoscrizione Azure, è necessario aggiungere determinati valori di configurazione all'App Host per assicurarsi che .NET Aspire possa individuarli. I valori di configurazione necessari includono SubscriptionId, AllowResourceGroupCreation, ResourceGroup e Location. Se non vengono impostati, nel dashboard vengono visualizzati .NET.NET Aspire errori di configurazione mancanti. Per altre informazioni su come impostarle, vedere Configurazione.

Per altre informazioni sulla gestione delle risorse di archiviazione Azure come risorse esistenti, vedere Usare le risorse esistentiAzure.

Nota

In alternativa, anziché rappresentare una Azure risorsa dell'account di archiviazione, è possibile aggiungere una stringa di connessione all'host dell'app. Questo approccio è di tipo debole e non funziona con assegnazioni di ruolo o personalizzazioni dell'infrastruttura. Per ulteriori informazioni, vedere Azure.

Aggiungi la risorsa dell'emulatore di archiviazione Azure

Per aggiungere una risorsa di emulatore di archiviazione Azure, concatenare una chiamata su 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, ma è accessibile da .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 del 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:

Punto di connessione	Porta contenitore	Porta host
`blob`	10.000	dinamico
`queue`	10001	dinamico
`table`	10002	dinamico

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(27000)
                                .WithQueuePort(27001)
                                .WithTablePort(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:

Nome endpoint	Mappatura delle porte (`container:host`)
`blob`	`10000:27000`
`queue`	`10001:27001`
`table`	`10002:27002`

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 altre informazioni, vedere Durata delle risorse del 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 altre informazioni sui volumi di dati e sui motivi per cui sono preferiti rispetto ai montaggi di binding, vedere Docker la documentazione: Volumi.

Configurare il contenitore Azurite con il punto di montaggio con 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...

Importante

I montaggi di associazione dati hanno funzionalità limitate rispetto ai volumi, che offrono prestazioni, portabilità e sicurezza migliori, rendendoli più adatti per gli ambienti di produzione. Tuttavia, i montaggi di associazione consentono l'accesso e la modifica diretta dei file nel sistema host, ideale per lo sviluppo e il test in cui sono necessarie modifiche in tempo reale.

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 punto di montaggio dell'associazione dati è montato nel percorso ../Azurite/Data sulla macchina host rispetto alla directory dell'host dell'app (IDistributedApplicationBuilder.AppHostDirectory) nel contenitore Azurite. Per altre informazioni sui montaggi di associazione dati, vedere la documentazione: Bind mounts.For more information on data bind mounts, see Docker docs: Bind mounts.

Connettersi alle risorse di archiviazione

Quando l'host .NET.NET Aspire dell'app viene eseguito, è possibile accedere alle risorse di archiviazione tramite strumenti esterni, ad esempio Azure Storage Explorer. Se la risorsa di archiviazione è in esecuzione in locale tramite Azurite, verrà prelevata automaticamente dal Azure Storage Explorer.

Nota

L'Azure Storage Explorer individua le risorse di archiviazione Azurite presupponendo che vengano usate le porte predefinite. Se il contenitore Azurite è stato configurato per l'uso di porte diverse, è necessario configurare Azure Storage Explorer per connettersi alle porte corrette.

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

Esegui l'host dell'app .NET.NET Aspire.
Apri Azure Storage Explorer.
Visualizzare il riquadro Esplora risorse .
Selezionare il collegamento Aggiorna tutto per aggiornare l'elenco degli account di archiviazione.
Espandi il nodo Emulatore e Collegato.
Espandi il nodo Account di archiviazione.
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 Azure risorsa di Archiviazione Queue

Nel progetto host dell'app, registrare l'integrazione di Queue Storage 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 della coda 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.

Bicep generato dal provisioning

Se non si ha familiarità con Bicep, si tratta di un linguaggio specifico del dominio per la definizione delle Azure risorse. Con .NET.NET Aspire, non è necessario scrivere Bicep a mano; Le API di provisioning generano invece Bicep automaticamente. Quando si pubblica l'app, il Bicep generato viene fornito insieme al file manifest. 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

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
}

output blobEndpoint string = storage.properties.primaryEndpoints.blob

output queueEndpoint string = storage.properties.primaryEndpoints.queue

output tableEndpoint string = storage.properties.primaryEndpoints.table

output name string = storage.name

Il bicep precedente è un modulo che effettua il provisioning di una risorsa dell'account Azure di archiviazione. Inoltre, le assegnazioni di ruolo vengono create per la Azure risorsa in un modulo separato:

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

param storage_outputs_name string

param principalType string

param principalId string

resource storage 'Microsoft.Storage/storageAccounts@2024-01-01' existing = {
  name: storage_outputs_name
}

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
}

Oltre all'account di archiviazione, allestisce 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 di controllo degli accessi in base al ruolo (AzureRBACAzure).

Ruolo/ID	Descrizione
Collaboratore ai dati di archiviazione Blob `ba92f5b4-2d11-453d-a403-e96b0029c9fe`	Leggere, scrivere ed eliminare contenitori e blob di archivio Azure.
Contributore ai dati delle tabelle di archiviazione `0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3`	Leggere, scrivere ed eliminare tabelle ed entità di archiviazione Azure.
Collaboratore ai dati della coda di archivio `974c5e8b-45b9-4653-ba55-5f855dd0fb88`	Leggere, scrivere ed eliminare Azure le code di archiviazione e i messaggi nelle code.

Il Bicep generato è un punto di partenza e viene influenzato dalle modifiche apportate all'infrastruttura di provisioning in C#. Se si apportano personalizzazioni direttamente al file Bicep, queste verranno sovrascritte, quindi apportare modifiche tramite le API di provisioning C# per assicurarsi che vengano riflesse nei file generati.

Personalizzare l'infrastruttura di provisioning

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.

Aggiungi la risorsa dell'emulatore di archiviazione Azure

Per aggiungere una risorsa di emulatore di archiviazione Azure, concatenare una chiamata su 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 come contenitore .NET.NET Aspire. 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 del 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, se configurato da .NET.NET Aspire, espone gli endpoint seguenti:

Punto di connessione	Porta contenitore	Porta host
`blob`	10.000	dinamico
`queue`	10001	dinamico
`table`	10002	dinamico

var builder = DistributedApplication.CreateBuilder(args);

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

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

Nome endpoint	Mappatura delle porte (`container:host`)
`blob`	`10000:27000`
`queue`	`10001:27001`
`table`	`10002:27002`

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 altre informazioni, vedere Durata delle risorse del 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...

Configurare il contenitore Azurite con il punto di montaggio con 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...

Importante

Connetti a un account di archiviazione esistente Azure

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...

Nota

Le stringhe di connessione vengono usate per rappresentare un'ampia gamma di informazioni di connessione, tra cui connessioni di database, broker di messaggi, URI di endpoint e altri servizi. Nella .NET.NET Aspire denominazione, il termine "stringa di connessione" è utilizzato per rappresentare qualsiasi tipo di informazioni di connessione.

La stringa di connessione viene configurata nella configurazione dell'host dell'app, in genere in Segreti utente, nella ConnectionStrings sezione . 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].

Connettersi alle risorse di archiviazione

Nota

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

Esegui l'host dell'app .NET.NET Aspire.
Apri Azure Storage Explorer.
Visualizzare il riquadro Esplora risorse .
Selezionare il collegamento Aggiorna tutto per aggiornare l'elenco degli account di archiviazione.
Espandi il nodo Emulatore e Collegato.
Espandi il nodo Account di archiviazione.
Dovresti vedere un account di archiviazione con il nome della tua risorsa come prefisso.

Controlli di integrità dell'integrazione di hosting

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.Azure.Storage.Blobs.

integrazione Client

Per iniziare a usare l'integrazione .NET AspireAzure del client di archiviazione code, installare il pacchetto NuGet 📦AspireAzure.Storage.Queues nel progetto cliente, cioè il progetto dell'applicazione che utilizza il client di archiviazione code Azure. L'integrazione del client di archiviazione di code Azure registra un'istanza di QueueServiceClient che è possibile usare per interagire con Azure archiviazione di code.

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Storage.Queues

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

Aggiungi il client di archiviazione delle code Azure

Nel file Program.cs del progetto che utilizza il client, chiamare il metodo di estensione AddAzureQueueClient su un qualsiasi IHostApplicationBuilder per registrare un QueueServiceClient da usare tramite il container per dependency injection. Il metodo accetta un parametro del nome di connessione.

builder.AddAzureQueueClient("queue");

È quindi possibile recuperare l'istanza di QueueServiceClient tramite l'iniezione della dipendenza. 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 Azure stringa di connessione di archiviazione .

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

Per altre informazioni, vedere Configurare le stringhe di connessione di archiviazioneAzure.

Utilizzare 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 di integrazione Azure Storage Queues client 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'user-agent 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, .NET.NET Aspire le integrazioni abilitano i controlli di integrità per tutti i servizi. Per altre informazioni, vedere .NET.NET Aspire Panoramica delle integrazioni.

Integrazione dell'archiviazione della coda: .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 pilastri dell'osservabilità. Per altre informazioni sull'osservabilità e la telemetria dell'integrazione, vedere .NET.NET Aspire Panoramica delle integrazioni. 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 .NET AspireAzure per l'archiviazione delle code 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.

Condividi tramite

integrazione dell'archiviazione delle code .NET AspireAzure

Integrazione hosting

Aggiungere la risorsa di archiviazione Azure

Bicep generato dal provisioning

Personalizzare l'infrastruttura di provisioning

Connetti a un account di archiviazione esistente Azure

Aggiungi la risorsa dell'emulatore di archiviazione Azure

Configurare il contenitore Azurite

Configurare le porte del container di Azurite

Configurare il contenitore Azurite con durata permanente

Configurare il contenitore Azurite con il volume di dati

Configurare il contenitore Azurite con il punto di montaggio con associazione dati

Connettersi alle risorse di archiviazione

Aggiungere Azure risorsa di Archiviazione Queue

Bicep generato dal provisioning

Personalizzare l'infrastruttura di provisioning

Aggiungi la risorsa dell'emulatore di archiviazione Azure

Configurare il contenitore Azurite

Configurare le porte del container di Azurite

Configurare il contenitore Azurite con durata permanente

Configurare il contenitore Azurite con il volume di dati

Configurare il contenitore Azurite con il punto di montaggio con associazione dati

Connetti a un account di archiviazione esistente Azure

Connettersi alle risorse di archiviazione

Controlli di integrità dell'integrazione di hosting

integrazione Client

Aggiungi il client di archiviazione delle code Azure

Configurazione

Usare una stringa di connessione

URI del servizio

Stringa di connessione

Utilizzare i provider di configurazione

Usare delegati inline

Client controlli di integrità dell'integrazione

Osservabilità e telemetria

Registrazione

Tracciamento

Metriche

Vedere anche

Commenti e suggerimenti

Risorse aggiuntive