Condividi tramite

integrazione di .NET AspireAzure Blob Storage

  • Articolo

Include:,,, integrazione dell'hosting e ,,Client, integrazione

Azure Blob Storage è un servizio per l'archiviazione di grandi quantità di dati non strutturati. L'integrazione .NET AspireAzure Blob Storage consente di connettersi alle istanze di Azure Blob Storage esistenti o di creare nuove istanze dalle applicazioni .NET.

Integrazione dell'hosting

I modelli di integrazione di .NET.NET AspireAzure archiviazione modellano le varie risorse di archiviazione come i seguenti tipi:

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

dotnet add package Aspire.Hosting.Azure.Storage

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

Aggiungere la risorsa di archiviazione Azure

Nel progetto host dell'app chiamare AddAzureStorage per aggiungere e restituire un generatore 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.

Importante

Quando si chiama AddAzureStorage, viene chiamato implicitamente AddAzureProvisioning, il quale aggiunge supporto per la generazione dinamica delle risorse Azure durante l'avvio dell'app. L'app deve configurare l'abbonamento e la località appropriate. Per ulteriori informazioni, vedere Approvvigionamento locale: Configurazione.

Gestione delle risorse Bicep generato

Se sei nuovo a Bicep, è un linguaggio specifico del dominio utilizzato per definire le risorse Azure. Con .NET.NET Aspirenon è necessario scrivere Bicep manualmente, invece le API di provisioning generano Bicep per te. Quando pubblichi la tua app, il Bicep generato viene prodotto accanto al file manifesto. Quando si aggiunge una risorsa di archiviazione Azure, viene generato il file Bicep seguente:


Attiva/Disattiva Azure Bicep di archiviazione. 

@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 fornisce un account di archiviazione Azure con le seguenti impostazioni predefinite:

  • 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, esegue anche il provisioning di un contenitore BLOB.

Le seguenti assegnazioni di ruolo vengono aggiunte all'account di archiviazione per consentire 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):

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

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 del Bicep generato 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:

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 Azure esistente

Potresti già avere un account di archiviazione esistente Azure a cui connettersi. 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 endpoint e altri servizi. Nella .NET.NET Aspire denominazione, il termine "stringa di connessione" viene usato 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 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 la risorsa dell'emulatore di memoria 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 tue app di Blob, Archiviazione Code e Archiviazione Tabelle Azure ed è un perfetto complemento per l'integrazione di hosting .NET AspireAzure. Azurite non è installato, ma è accessibile per .NET.NET Aspire come contenitore. Quando si aggiunge un contenitore all’host dell'applicazione, come mostrato nell'esempio precedente con l'immagine mcr.microsoft.com/azure-storage/azurite, il contenitore viene creato e avviato all’avvio dell’host dell'applicazione. 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 dei container di Azurite

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

Punto finale Porta contenitore Porta host
blob 10.000 dinamico
queue 10001 dinamico
table 10002 dinamico

La porta su cui sono in ascolto è 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, eseguire chiamate concatenate sul builder 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 ascoltare rispettivamente sulle porte 27000, 27001e 27002. Le porte del contenitore Azurite vengono mappate alle porte host, come illustrato nella tabella seguente:

Nome endpoint Mapping 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 contenitore.

Configurare un contenitore Azurite con un 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 rendere 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 a associare i montaggi, vedere la documentazione Docker: Volumi.

Configurare il contenitore Azurite con un bind mount per i dati

Per aggiungere un montaggio dell'associazione dati alla risorsa dell'emulatore di archiviazione Azure, chiamare 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 di binding dei dati hanno funzionalità limitate rispetto ai volumi , che offrono prestazioni, portabilità e sicurezza migliori, rendendole più adatte per gli ambienti di produzione. Tuttavia, i montaggi bind consentono l'accesso e la modifica diretta dei file nel sistema host, ideale per lo sviluppo e i test in cui sono richieste 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 bind mount dei dati viene montato al percorso ../Azurite/Data sul 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 viene eseguito l'host dell'app .NET.NET Aspire, è 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 è configurato il contenitore Azurite per l'uso di porte diverse, sarà necessario configurare Azure Storage Explorer per connettersi alle porte corrette.

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

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

  2. Aprire il Azure Storage Explorer.

  3. Visualizza il riquadro Esplora.

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

  5. Espandi il nodo collegato dell'emulatore & .

  6. Espandi il nodo account di archiviazione.

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

    Azure Storage Explorer: risorsa di archiviazione Azurite individuata.

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

Aggiungi la risorsa Azure Blob Storage

Nel progetto host dell'app registrare l'integrazione Azure Blob Storage concatenandola con una chiamata a AddBlobs nell'istanza di IResourceBuilder<IAzureStorageResource> restituita da AddAzureStorage. Nell'esempio seguente viene illustrato come aggiungere una risorsa Azure Blob Storage denominata storage e un contenitore BLOB denominato blobs:

var builder = DistributedApplication.CreateBuilder(args);

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

builder.AddProject<Projects.ExampleProject>()
       .WithReference(blobs)
       .WaitFor(blobs);

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

Il codice precedente:

  • Aggiunge una risorsa di archiviazione Azure denominata storage.
  • Concatena una chiamata a RunAsEmulator per configurare la risorsa di archiviazione da eseguire in locale usando un emulatore. L'emulatore in questo caso è Azurite.
  • Aggiunge un contenitore BLOB denominato blobs alla risorsa di archiviazione.
  • Aggiunge la risorsa blobs al ExampleProject e attende che sia pronta prima di avviare il progetto.

Hosting dei controlli di integrità dell'integrazione

L'integrazione dell'hosting di archiviazione Azure aggiunge automaticamente un controllo dello stato di salute 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 client .NET AspireAzure Blob Storage, installare il 📦Aspire.Azure. Storage.Blobs pacchetto NuGet nel progetto che utilizza il client, ovvero il progetto per l'applicazione che usa il client Azure Blob Storage. L'integrazione client Azure Blob Storage registra un'istanza di BlobServiceClient che è possibile usare per interagire con Azure Blob Storage.

dotnet add package Aspire.Azure.Storage.Blobs

Aggiungere Azure Blob Storage client

Nel file Program.cs del progetto cliente, chiamate il metodo di estensione AddAzureBlobClient su qualsiasi IHostApplicationBuilder per registrare un BlobServiceClient da usare tramite il container per l'inserimento delle dipendenze. Il metodo accetta un parametro del nome di connessione.

builder.AddAzureBlobClient("blobs");

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

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

Configurazione

L'integrazione .NET AspireAzure Blob Storage offre più opzioni per configurare l'BlobServiceClient in base ai requisiti e alle convenzioni del 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 AddAzureBlobClient:

builder.AddAzureBlobClient("blobs");

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à AzureStorageBlobsSettings.Credential per stabilire una connessione. Se non è configurata alcuna credenziale, viene usato il Azure.Identity.DefaultAzureCredential.

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

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

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

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

Usare i provider di configurazione

L'integrazione .NET AspireAzure Blob Storage supporta Microsoft.Extensions.Configuration. Carica i AzureStorageBlobsSettings e BlobClientOptions dalla configurazione con la chiave Aspire:Azure:Storage:Blobs. Il frammento di codice seguente è un esempio di un file appsettings.json che configura alcune delle opzioni:

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

Per lo schema completo JSON di integrazione client Azure Blob Storage, vedere Aspire.Azure. Storage.Blobs/ConfigurationSchema.json.

Usare delegati inline

È anche possibile passare il delegato Action<AzureStorageBlobsSettings> configureSettings per configurare alcune o tutte le opzioni inline, ad esempio per configurare i controlli di integrità:

builder.AddAzureBlobClient(
    "blobs",
    settings => settings.DisableHealthChecks = true);

È anche possibile configurare il BlobClientOptions usando il delegato Action<IAzureClientBuilder<BlobServiceClient, BlobClientOptions>> configureClientBuilder, il secondo parametro del metodo AddAzureBlobClient. Ad esempio, per impostare la prima parte delle intestazioni user-agent per tutte le richieste effettuate da questo client:

builder.AddAzureBlobClient(
    "blobs",
    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 .NET AspireAzure Blob Storage:

  • Aggiunge il controllo di integrità quando AzureStorageBlobsSettings.DisableHealthChecks è false, che tenta di connettersi al Azure Blob Storage.
  • Si integra con l'endpoint HTTP /health, che specifica che tutti i controlli di integrità registrati devono essere passati affinché l'app sia considerata pronta per accettare il traffico.

Osservabilità e telemetria

.NET .NET Aspire le integrazioni configurano automaticamente le impostazioni di registrazione, tracciamento 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 .NET AspireAzure Blob Storage usa le categorie di log seguenti:

  • Azure.Core
  • Azure.Identity

Tracciamento

L'integrazione .NET AspireAzure Blob Storage emette le seguenti attività di tracciamento usando OpenTelemetry:

  • Azure.Storage.Blobs.BlobContainerClient

Metriche

L'integrazione .NET AspireAzure Blob Storage attualmente non supporta le metriche per impostazione predefinita a causa di limitazioni con Azure SDK.

Vedere anche