Condividi tramite

integrazione di tabelle dati .NET AspireAzure

  • Articolo

Include:integrazione con l'hosting e Client integrazione

Azure Table Storage è un servizio per l'archiviazione di dati NoSQL strutturati. L'integrazione delle tabelle dati .NET AspireAzure consente di connettersi alle istanze di Azure Table Storage esistenti o di creare nuove istanze dalle applicazioni .NET.

Integrazione dell'hosting

L'integrazione degli .NET.NET AspireAzure modelli di hosting modella le varie risorse di archiviazione come i seguenti tipi:

Per accedere a questi tipi e 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 Gestire le dipendenze dei pacchetti in .NET applicazioni.

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, chiama in modo implicito AddAzureProvisioning, che aggiunge il supporto per la generazione di risorse Azure in modo dinamico durante l'avvio dell'app. L'app deve configurare l'abbonamento e la posizione appropriati. Per altre informazioni, vedere Provisioning locale: Configurazione.

Bicep generato per il provisioning

Se non si ha familiarità con Bicep, si tratta di un linguaggio specifico del dominio per la definizione delle risorse Azure. Con .NET.NET Aspirenon è necessario scrivere Bicep manualmente; le API di provisioning generano Bicep per te. Quando si pubblica l'app, il Bicep generato viene fornito insieme al file manifesto. Quando si aggiunge una risorsa di archiviazione Azure, viene generato il seguente Bicep:


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: Il 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 all'applicazione l'accesso. Per ulteriori informazioni, vedere i ruoli predefiniti di controllo degli accessi basato sui ruoli Azure (Azure RBAC).

Ruolo/ID Descrizione
Collaboratore ai dati dei BLOB di archiviazione
ba92f5b4-2d11-453d-a403-e96b0029c9fe		 Leggere, scrivere ed eliminare contenitori e blob di archiviazione Azure.
Contributore dei dati alle tabelle di archiviazione
0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3		 Leggere, scrivere ed eliminare tabelle ed entità di archiviazione Azure.
Collaboratore ai dati della coda di archiviazione
974c5e8b-45b9-4653-ba55-5f855dd0fb88		 Leggere, scrivere ed eliminare code di archiviazione di 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 fluente 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:

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 avere un account di archiviazione Azure esistente a cui desideri connetterti. 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 nomenclatura .NET.NET Aspire, 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 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 è la forma abbreviata di IConfiguration.GetSection("ConnectionStrings")[name].

Aggiungere la risorsa dell'emulatore di archiviazione Azure

Per aggiungere una risorsa dell'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 di Blob Storage, Queue Storage e Table Storage Azure ed è un perfetto compagno per l'integrazione con l'hosting .NET AspireAzure. Azurite non è installato, ma è accessibile da .NET.NET Aspire come contenitore. Quando si aggiunge un contenitore all'host dell'applicazione, come illustrato nell'esempio precedente con l'immagine mcr.microsoft.com/azure-storage/azurite, il contenitore viene creato e avviato automaticamente all'avvio dell'host dell'applicazione. 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 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 10000 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, 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 del contenitore Azurite blob, queuee table affinché ascoltino 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 del 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 ciclo di vita della 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 è utilizzato per mantenere persistenti i dati di Azurite al di fuori del ciclo di vita del suo 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 di dati e sui motivi per cui sono preferiti rispetto ai "bind mounts" , consultare la documentazione Docker: Volumi.

Configurare il contenitore Azurite con il montaggio dell'associazione dati

Per aggiungere un punto di montaggio per l'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 bind mounts dei dati hanno funzionalità limitate rispetto ai volumi , che offrono prestazioni, portabilità e sicurezza migliori, rendendoli più adatti per gli ambienti di produzione. Tuttavia, i bind mounts consentono l'accesso e la modifica diretta dei file sul sistema host, ideale per lo sviluppo e il testing che richiedono 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 è montato sul percorso ../Azurite/Data sulla macchina host rispetto alla directory dell'host dell'app (IDistributedApplicationBuilder.AppHostDirectory) all'interno del container Azurite. Per ulteriori informazioni sui bind mounts dei dati, consultare la documentazione Docker: 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. Eseguire 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.

  5. Espandere il nodo emulatore & collegato.

  6. Espandi il nodo account di archiviazione.

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

    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.

Aggiungere risorsa Azure Table Storage

Nel progetto host dell'app, registra l'integrazione Azure Table Storage concatenando una chiamata a AddTables sull'istanza IResourceBuilder<IAzureStorageResource> restituita da AddAzureStorage. Nell'esempio seguente viene illustrato come aggiungere una risorsa Azure Table Storage denominata storage e una risorsa di tabella denominata tables:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Il codice precedente:

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

Verifiche di integrità dell'integrazione di hosting

L'integrazione dell'hosting di archiviazione Azure aggiunge automaticamente un controllo 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.

Client integrazione

Per iniziare con l'integrazione del client delle tabelle dati di .NET AspireAzure, installare il pacchetto NuGet 📦Aspire.Azure.Data.Tables nel progetto cliente, cioè il progetto per l'applicazione che utilizza il client delle tabelle dati Azure. L'integrazione client delle tabelle di dati Azure registra un'istanza di TableServiceClient che è possibile usare per interagire con Azure Table Storage.

dotnet add package Aspire.Azure.Data.Tables

Aggiungere Azure Table Storage client

Nel file Program.cs del progetto che usa il client, chiama il metodo di estensione AddAzureTableClient in qualsiasi IHostApplicationBuilder per registrare un TableServiceClient da usare tramite il contenitore di iniezione delle dipendenze. Il metodo accetta un parametro del nome di connessione.

builder.AddAzureTableClient("tables");

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

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

Configurazione

L'integrazione .NET AspireAzure Table Storage offre più opzioni per configurare l'TableServiceClient in base ai requisiti e alle convenzioni del progetto.

Usare i fornitori di configurazione

L'integrazione .NET AspireAzure Table Storage supporta Microsoft.Extensions.Configuration. Carica il AzureDataTablesSettings e il TableClientOptions dalla configurazione utilizzando la chiave Aspire:Azure:Data:Tables. Il frammento di codice seguente è un esempio di un file appsettings.json che configura alcune delle opzioni:

{
  "Aspire": {
    "Azure": {
      "Data": {
        "Tables": {
          "ServiceUri": "YOUR_URI",
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "EnableTenantDiscovery": true
          }
        }
      }
    }
  }
}

Per lo schema JSON completo dell'integrazione client di tabelle dati di Azure, vedere Aspire.Azure. Data.Tables/ConfigurationSchema.json.

Usare delegati inline

È anche possibile passare il delegato Action<AzureDataTablesSettings> configureSettings per configurare alcune o tutte le opzioni inline, ad esempio per configurare il ServiceUri:

builder.AddAzureTableClient(
    "tables",
    settings => settings.DisableHealthChecks = true);

È anche possibile configurare il TableClientOptions usando il delegate Action<IAzureClientBuilder<TableServiceClient, TableClientOptions>> configureClientBuilder, il secondo parametro del metodo AddAzureTableClient. Ad esempio, per impostare l'ID TableServiceClient per identificare il client:

builder.AddAzureTableClient(
    "tables",
    configureClientBuilder: clientBuilder =>
        clientBuilder.ConfigureOptions(
            options => options.EnableTenantDiscovery = true));

Client controlli di integrità dell'integrazione

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

Integrazione delle tabelle dati .NET AspireAzure:

  • Aggiunge il controllo dello stato di salute quando AzureDataTablesSettings.DisableHealthChecks è falsee tenta di connettersi al Azure Table 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 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 delle tabelle dati di .NET AspireAzure usa le categorie di log seguenti:

  • Azure.Core
  • Azure.Identity

Tracciamento

L'integrazione delle tabelle dati di .NET AspireAzure emette le seguenti attività di tracciamento utilizzando OpenTelemetry:

  • Azure.Data.Tables.TableServiceClient

Metriche

L'integrazione delle tabelle dati di .NET AspireAzure attualmente non supporta le metriche per impostazione predefinita a causa delle limitazioni del SDK Azure.

Vedere anche