Integrace tabulek dat .NET AspireAzure

Článek
12/13/2024

zahrnuje: integraci hostování a Client integraci

Azure Table Storage je služba pro ukládání strukturovaných dat NoSQL. Integrace .NET AspireAzure datových tabulek umožňuje připojit se k existujícím instancím Azure Table Storage nebo vytvářet nové instance z .NET aplikací.

Integrace hostování

.NET .NET Aspire Azure Storage integrační modely modelují různé prostředky úložiště jako následující typy:

AzureStorageResource: Představuje úložný prostředek Azure.
AzureStorageEmulatorResource: Představuje prostředek emulátoru úložiště Azure (Azurite).
AzureBlobStorageResource: Představuje prostředek úložiště typu Blob Azure.
AzureQueueStorageResource: Představuje prostředek Azure Queue Storage.
AzureTableStorageResource: Představuje prostředek Azure úložiště tabulky.

Pokud chcete získat přístup k těmto typům a rozhraním API pro jejich vyjádření, přidejte balíček NuGet 📦Aspire.Hosting.Azure.Storage v projektu hostitele aplikace .

.NET rozhraní příkazového řádku
PackageReference

dotnet add package Aspire.Hosting.Azure.Storage

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

Další informace najdete v tématu dotnet add package nebo spravovat závislosti balíčků v .NET aplikacích.

Přidat úložný prostředek Azure

V projektu hostitele aplikace zavolejte AddAzureStorage, abyste přidali a vrátili tvůrce prostředků Azure Storage.

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

Když do hostitele aplikace přidáte AzureStorageResource, zveřejní další užitečná rozhraní API pro přidání prostředků Azure Blob, Queue a Table Storage. Jinými slovy, musíte nejprve přidat AzureStorageResource před přidáním jakéhokoli jiného úložišťového prostředku.

Důležitý

Když voláte AddAzureStorage, automaticky se volá AddAzureProvisioning, což umožňuje generování Azure prostředků dynamicky během spouštění aplikace. Aplikace musí nakonfigurovat příslušné předplatné a umístění. Další informace naleznete v tématu Místní zřizování: Konfigurace.

Vygenerovaný provisioning skript Bicep

Pokud jste nováčkem v Bicep, jedná se o specifický jazyk pro danou oblast k definování Azure prostředků. S .NET.NET Aspirenemusíte psát Bicep ručně, místo toho rozhraní API pro zřizování generuje Bicep za vás. Když publikujete aplikaci, vygenerovaný Bicep je uložen spolu se souborem manifestu. Při přidání zdroje Azure Storage se vygeneruje následující Bicep:

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

param principalType string

param principalId 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

Předchozí Bicep je modul, který zřídí úložiště Azure s následujícími výchozími nastaveními:

kind: Druh účtu úložiště. Výchozí hodnota je StorageV2.
sku: SKU účtu úložiště. Výchozí hodnota je Standard_GRS.
properties: Vlastnosti účtu úložiště:
- accessTier: Úroveň přístupu účtu úložiště. Výchozí hodnota je Hot.
- allowSharedKeyAccess: Logická hodnota, která označuje, jestli účet úložiště povoluje autorizaci požadavků s přístupovým klíčem účtu. Výchozí hodnota je false.
- minimumTlsVersion: Minimální podporovaná verze protokolu TLS pro účet úložiště. Výchozí hodnota je TLS1_2.
- networkAcls: Síťové ACL pro účet úložiště. Výchozí hodnota je { defaultAction: 'Allow' }.

Kromě účtu úložiště také vytvoří kontejner typu blob.

Následující přiřazení rolí jsou přidávána k účtu úložiště, aby vaše aplikace získala přístup. Další informace najdete o vestavěných rolích Azure řízení přístupu na základě role (Azure RBAC):

Role / Identifikátor	Popis
Přispěvatel dat objektů blob služby Storage `ba92f5b4-2d11-453d-a403-e96b0029c9fe`	Čtení, zápis a odstranění Azure kontejnerů a objektů blob úložiště.
Přispěvatel dat do tabulek úložiště `0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3`	Čtení, zápis a odstranění Azure tabulek úložiště a entit.
Přispěvatel dat ve frontě Storage `974c5e8b-45b9-4653-ba55-5f855dd0fb88`	Čtení, zápis a odstraňování front úložiště a zpráv ve frontách Azure.

Vygenerovaný Bicep je výchozím bodem a můžete ho přizpůsobit tak, aby splňoval vaše konkrétní požadavky.

Přizpůsobení infrastruktury implementace

Všechny zdroje .NET AspireAzure jsou podtřídy typu AzureProvisioningResource. Tento typ umožňuje přizpůsobení vygenerovaného Bicep tím, že poskytuje fluentní API pro konfiguraci prostředků Azure pomocí API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Můžete například nakonfigurovat kind, sku, propertiesatd. Následující příklad ukazuje, jak přizpůsobit prostředek Azure Storage:

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

Předchozí kód:

Propojuje volání k ConfigureInfrastructure API:
- Parametr infra je instance typu AzureResourceInfrastructure.
- Přidělitelné prostředky jsou načteny voláním metody GetProvisionableResources().
- Načte se jeden StorageAccount.
- StorageAccount.AccessTier je přiřazen k StorageAccountAccessTier.Cool.
- StorageAccount.Sku se přiřadí novému StorageSku s hodnotou NamePremiumZrs.
- Do účtu úložiště se přidá značka s klíčem ExampleKey a hodnotou Example value.

K dispozici je mnoho dalších možností konfigurace pro přizpůsobení prostředku Azure Storage. Další informace najdete v tématu Azure.Provisioning.Storage.

Připojení k existujícímu účtu Azure Storage

Možná máte existující účet Azure Storage, ke kterému se chcete připojit. Místo toho, abyste vytvořili nový prostředek Azure Storage, můžete do hostitele aplikace přidat připojovací řetězec. Pokud chcete přidat připojení k existujícímu účtu Azure Storage, zavolejte metodu 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...

Poznámka

Připojovací řetězce se používají k reprezentaci široké škály informací o připojení, včetně databázových připojení, zprostředkovatelů zpráv, identifikátorů URI koncových bodů a dalších služeb. V .NET.NET Aspire terminologii se výraz "připojovací řetězec" používá k reprezentaci jakéhokoli druhu informací o připojení.

Připojovací řetězec se konfiguruje v konfiguraci hostitele aplikace, obvykle v části Tajné kódy uživatelův části ConnectionStrings. Hostitel aplikace injektuje tento připojovací řetězec jako proměnnou prostředí do všech souvisejících prostředků, například:

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

Závislý prostředek může přistupovat k vloženému připojovacímu řetězci voláním metody GetConnectionString a předáním názvu připojení jako parametru, v tomto případě "blobs". Rozhraní API GetConnectionString je zkratka pro IConfiguration.GetSection("ConnectionStrings")[name].

Přidejte zdroj emulátoru úložiště Azure

Pokud chcete přidat prostředek emulátoru úložiště Azure, navázejte volání na IResourceBuilder<AzureStorageResource> k rozhraní RunAsEmulator API.

var builder = DistributedApplication.CreateBuilder(args);

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

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

Při volání RunAsEmulatornakonfiguruje prostředky úložiště tak, aby se spouštěly místně pomocí emulátoru. Emulátor v tomto případě je Azurite. Opensourcový emulátor Azurite poskytuje bezplatné místní prostředí pro testování aplikací Azure Blob, Queue Storage a Table Storage a je to dokonalý doplněk k integraci .NET AspireAzure hostování. Azurite není nainstalovaný, místo toho je přístupný pro .NET.NET Aspire jako kontejner. Když do hostitele aplikace přidáte kontejner, jak je znázorněno v předchozím příkladu s imagí mcr.microsoft.com/azure-storage/azurite, vytvoří a spustí kontejner při spuštění hostitele aplikace. Další informace najdete v tématu životní cyklus zdrojů kontejneru.

Konfigurace kontejneru Azurite

Pro prostředky kontejneru jsou k dispozici různé konfigurace, například můžete nakonfigurovat porty kontejneru, proměnné prostředí, životnostatd.

Konfigurace portů kontejneru Azurite

Ve výchozím nastavení kontejner Azurite při konfiguraci pomocí .NET.NET Aspirezveřejňuje následující koncové body:

Koncový bod	Kontejnerový přístav	Port hostitele
`blob`	10 000	dynamický
`queue`	10001	dynamický
`table`	10002	dynamický

Port, na kterém naslouchají, je ve výchozím nastavení dynamický. Po spuštění kontejneru se porty mapují na náhodný port na hostitelském počítači. Pokud chcete nakonfigurovat porty koncových bodů, zřetězte volání generátoru zdrojů kontejneru, který poskytuje metoda RunAsEmulator, jak je znázorněno v následujícím příkladu:

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

Předchozí kód nakonfiguruje stávající koncové body blob, queuea table kontejneru Azurite tak, aby naslouchaly na portech 27000, 27001a 27002, v tomto pořadí. Porty kontejneru Azurite se mapují na hostitelské porty, jak je znázorněno v následující tabulce:

Název koncového bodu	Mapování portů (`container:host`)
`blob`	`10000:27000`
`queue`	`10001:27001`
`table`	`10002:27002`

Konfigurace kontejneru Azurite s trvalou životností

Chcete-li konfigurovat kontejner Azurite s trvalou životností, zavolejte metodu WithLifetime u zdroje kontejneru Azurite a předejte 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...

Další informace najdete v tématu Životnost prostředků kontejneru.

Konfigurace kontejneru Azurite s datovým svazkem

Pokud chcete přidat datový svazek do emulátoru úložiště Azure, zavolejte metodu WithDataVolume na emulátoru úložiště Azure.

var builder = DistributedApplication.CreateBuilder(args);

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

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

Objem dat se používá k zachování dat Azurite mimo životní cyklus kontejneru. Datový svazek se připojí k cestě /data v kontejneru Azurite a pokud není zadaný parametr name, název se naformátuje jako .azurite/{resource name}. Další informace o datových svazcích a podrobnosti o tom, proč se upřednostňují před bind mounts, najdete v dokumentaci: Docker Svazky.

Konfigurace Azurite kontejneru s připojením svazku dat

Pokud chcete přidat připojení datového svazku ke zdroji emulátoru úložiště Azure, zavolejte metodu WithDataBindMount:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Důležitý

Připojení vazby dat mají v porovnání s svazkyomezené funkce, které nabízejí lepší výkon, přenositelnost a zabezpečení, což je vhodnější pro produkční prostředí. Připojení typu bind však umožňují přímý přístup a úpravy souborů na hostitelském systému, což je ideální pro vývoj a testování, kdy jsou potřeba změny v reálném čase.

Datové připojení pro vazby spoléhá na souborový systém hostitelského počítače ke zachování dat Azurite během restartování kontejneru. Datové vazební připojení je připojeno k cestě ../Azurite/Data na hostitelském počítači vzhledem k umístění adresáře aplikace (IDistributedApplicationBuilder.AppHostDirectory) v kontejneru Azurite. Další informace o datových přípojích typu bind najdete v dokumentaci: Připojení typu bind.

Připojit se k úložným prostředkům

Když se hostitel aplikace začne spouštět, mohou k prostředkům úložiště přistupovat externí nástroje, jako je Storage Explorer. Pokud je váš prostředek úložiště spuštěný místně pomocí Azurite, automaticky ho rozpozná nástroj Azure Storage Explorer.

Poznámka

Průzkumník úložiště Azure zjistí úložné prostředky Azurite, pokud se používají výchozí porty. Pokud jste nakonfigurovali kontejner Azurite tak, aby používal různé porty, budete muset nakonfigurovat průzkumníka služby Azure Storage tak, aby se připojil ke správným portům.

Chcete-li se připojit k prostředku úložiště z Azure Storage Explorer, postupujte takto:

Spusťte hostitele aplikace .NET.NET Aspire.
Otevřete Průzkumníka služby Azure Storage.
Zobrazit podokno Průzkumníka .
Chcete-li aktualizovat seznam účtů úložiště, vyberte odkaz Aktualizovat všechny.
Rozbalte uzel Emulátor & připojený.
Rozbalte uzel účty úložiště .
Měli byste vidět účet úložiště, jehož název začíná názvem vašeho prostředku:

Pomocí Průzkumníka služby Azure Storage můžete prozkoumat účet úložiště a jeho obsah. Další informace o používání průzkumníka služby Azure Storage najdete v tématu Začínáme s Průzkumníkem služby Storage.

Přidejte prostředek Azure Table Storage

V hostitelském projektu aplikace zaregistrujte integraci Azure Table Storage zřetězeným voláním AddTables na instanci IResourceBuilder<IAzureStorageResource>, kterou vrací AddAzureStorage. Následující příklad ukazuje, jak přidat Azure Table Storage zdroj pojmenovaný storage a zdroj tabulky pojmenovaný 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...

Předchozí kód:

Přidá úložný prostředek Azure pojmenovaný storage.
Přidá prostředek tabulkového úložiště s názvem tables k prostředku úložiště.
Přidá zdroj storage do ExampleProject a před zahájením projektu počká, až bude připravený.

Hostování kontrol stavu integrace

Integrace hostování služby Azure Storage automaticky přidá kontrolu stavu úložišťového prostředku. Přidá se jenom při spuštění jako emulátoru a ověří, že kontejner Azurite běží a že se k němu dá navázat připojení. Integrace hostování spoléhá na 📦 AspNetCore.HealthChecks.Azure. Storage.Blobs balíčku NuGet.

Client integrace

Pokud chcete začít s integrací klienta pro Tabulky dat .NET AspireAzure, nainstalujte balíček NuGet 📦Aspire.Azure.Data.Tables v projektu, který používá klienta, tj. v projektu aplikace, jež využívá klienta Azure Tabulky dat. Integrace klienta Azure Tabulky dat registruje instanci TableServiceClient, kterou můžete použít k interakci s Azure Table Storage.

.NET rozhraní příkazového řádku
PackageReference

dotnet add package Aspire.Azure.Data.Tables

<PackageReference Include="Aspire.Azure.Data.Tables"
                  Version="*" />

Přidej klienta Azure Table Storage

V souboru Program.cs projektu využívajícího klienta zavolejte metodu rozšíření AddAzureTableClient na jakémkoli IHostApplicationBuilder a zaregistrujte TableServiceClient pro použití prostřednictvím kontejneru pro injektování závislostí. Metoda přebírá parametr názvu připojení.

builder.AddAzureTableClient("tables");

Poté můžete instanci TableServiceClient získat pomocí injektáže závislostí. Například pro načtení klienta ze služby:

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

Konfigurace

Integrace .NET AspireAzure Table Storage poskytuje několik možností konfigurace TableServiceClient na základě požadavků a konvencí projektu.

Použití zprostředkovatelů konfigurace

Integrace .NET AspireAzure Table Storage podporuje Microsoft.Extensions.Configuration. Načte AzureDataTablesSettings a TableClientOptions z konfigurace pomocí klíče Aspire:Azure:Data:Tables. Následující fragment kódu je příkladem souboru appsettings.json, který konfiguruje některé z možností:

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

Kompletní schéma integrace klienta datových tabulek Azure najdete v Aspire.Azure.Data.Tables/ConfigurationSchema.json.

Použití vložených delegátů

Můžete delegáta Action<AzureDataTablesSettings> configureSettings také předat k nastavení některých nebo všech možností přímo, například pro konfiguraci ServiceUri.

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

Můžete také nastavit TableClientOptions pomocí Action<IAzureClientBuilder<TableServiceClient, TableClientOptions>> configureClientBuilder delegáta, druhého parametru metody AddAzureTableClient. Pokud chcete například nastavit ID TableServiceClient pro identifikaci klienta:

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

Client kontroly stavu integrace

Ve výchozím nastavení umožňují integrace .NET.NET Aspirekontroly stavu pro všechny služby. Další informace naleznete v tématu .NET.NET Aspire přehled integrací.

Integrace .NET AspireAzure datových tabulek:

Přidá kontrolu stavu systému, když je AzureDataTablesSettings.DisableHealthChecksfalse, která se pokusí připojit k Azure Table Storage.
Integruje se s koncovým bodem HTTP /health, který stanovuje, že všechny registrované kontroly stavu musí být úspěšné, aby aplikace byla považována za připravenou přijímat provoz.

Pozorovatelnost a telemetrie

.NET .NET Aspire integrace automaticky nastaví konfigurace protokolování, trasování a metrik, které se někdy označují jako pilíře pozorovatelnosti. Další informace o pozorovatelnosti a telemetrii integrace najdete v přehledu integrace .NET.NET Aspire. V závislosti na zálohovací službě můžou některé integrace podporovat pouze některé z těchto funkcí. Například některé integrace podporují protokolování a trasování, ale ne metriky. Funkce telemetrie je také možné zakázat pomocí technik uvedených v části Konfigurace.

Protokolování

Integrace tabulek dat .NET AspireAzure používá následující kategorie protokolů:

Azure.Core
Azure.Identity

Trasování

Integrace tabulek dat .NET AspireAzure generuje následující aktivity trasování pomocí OpenTelemetry:

Azure.Data.Tables.TableServiceClient

Metody měření

Integrace .NET AspireAzure datových tabulek v současné době nepodporuje metriky ve výchozím nastavení kvůli omezením Azure SDK.

Sdílet prostřednictvím