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ě Blob Azure.
AzureQueueStorageResource: Představuje prostředek Azure Queue Storage.
AzureTableStorageResource: Představuje prostředek Azure Table Storage.

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řidejte prostředek úložiště 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í prostředku Azure Storage se vygeneruje následující Bicep:

přepnout Azure Bicep úložiště.

@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

Předchozí bicep je modul, který zřídí účet Azure Storage 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ě zřídí také kontejner blob.

Následující přiřazení rolí se přidají 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 kontejnery a objekty blob služby Storage
Přispěvatel dat pro tabulky úložiště `0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3`	Čtení, zápis a odstranění tabulek úložiště Azure 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:

Zřetězí volání rozhraní API ConfigureInfrastructure:
- 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 představovali nový prostředek Azure Storage, můžete k hostiteli 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 vloží tento připojovací řetězec jako proměnnou prostředí do všech závislý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, proveďte zřetězení volání IResourceBuilder<AzureStorageResource> do rozhraní RunAsEmulator.

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 prostředků 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`	10000	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í tvůrce prostředků 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("blob", 27000)
                                .WithQueuePort("queue", 27001)
                                .WithTablePort("table", 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 připojení vazby, najdete v dokumentaci Docker: Svazky.

Konfigurace Azurite kontejneru s připojením svazku dat

Pokud chcete přidat datovou vazbu k prostředku 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.

Připojení vazby dat spoléhají na systém souborů hostitelského počítače k zachování dat Azurite napříč restartováními kontejneru. Datová vazba je připojena na cestu ../Azurite/Data na hostiteli vzhledem k umístění hostitelského adresáře aplikace (IDistributedApplicationBuilder.AppHostDirectory) v kontejneru Azurite. Další informace o připojeních datových vazeb najdete v dokumentaci Docker: Připojení vazby.

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

Když se hostitel aplikace .NET.NET Aspire spustí, můžou k prostředkům úložiště přistupovat externí nástroje, jako je Azure Průzkumník služby Storage. 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átoru 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 prostředek s názvem storage a prostředek tabulky s názvem 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 prostředku úložiště. 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.

integrace Client

Pokud chcete začít s integrací .NET AspireAzure Data Tables client, nainstalujte 📦Aspire.Azure.Data.Tables balíček NuGet v projektu, který využívá client, tj. projekt pro aplikaci, která používá Data Tables Azureclient. Integrace Azure datových tabulek client 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 Azure Table Storageclient

V souboru Program.cs projektu, který využívá client, zavolejte metodu rozšíření AddAzureTableClient na libovolném 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");

Potom můžete pomocí injekce závislostí načíst instanci TableServiceClient. Pokud chcete například načíst client 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 datových tabulek AzureclientJSON naleznete v odkazu Aspire.Azure. Data.Tables/ConfigurationSchema.json.

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

Můžete také předat delegáta Action<AzureDataTablesSettings> configureSettings a nastavit některé nebo všechny možnosti 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 client:

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, když je AzureDataTablesSettings.DisableHealthChecksfalse, kterýžto 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