.NET Aspire Azure Adattáblák integrációja

Tartalmazza: Üzemeltetési integráció és Client integráció

Azure Table Storage strukturált NoSQL-adatok tárolására szolgáló szolgáltatás. A .NET AspireAzure adattáblák integrációja lehetővé teszi, hogy meglévő Azure Table Storage-példányokhoz csatlakozzon, vagy új példányokat hozzon létre .NET alkalmazásokból.

Üzemeltetési integráció

A .NET.NET AspireAzure Storage az alábbi típusokként modellezi a különböző tárolási erőforrásokat:

• AzureStorageResource: Egy Azure Storage-erőforrást jelöl.
• AzureStorageEmulatorResource: Egy Azure Storage emulátorerőforrást (Azurite) jelöl.
• AzureBlobStorageResource: Egy Azure Blob Storage-erőforrást jelöl.
• AzureQueueStorageResource: Egy Azure Queue Storage-erőforrást jelöl.
• AzureTableStorageResource: Egy Azure Table Storage-erőforrást jelöl.

Az ilyen típusok és API-k eléréséhez adja hozzá a 📦Aspire.Hosting.Azure.Storage NuGet-csomagot az alkalmazás-gazdagép projektjéhez.

dotnet add package Aspire.Hosting.Azure.Storage

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

További információ: dotnet add package vagy Csomagfüggőségek kezelése .NET alkalmazásokban.

Azure Storage-erőforrás hozzáadása

Az alkalmazásgazda projektben hívja meg a AddAzureStorage függvényt, hogy hozzáadjon és visszaadjon egy Azure Storage-erőforrás-építőt.

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

Amikor egy AzureStorageResource-t hozzáad az alkalmazásszolgáltatóhoz, azzal más hasznos API-kat is elérhet, amelyek lehetővé teszik Azure blob-, várólista- és táblatároló erőforrások hozzáadását. Más szóval a többi tárolási erőforrás hozzáadása előtt hozzá kell adnia egy AzureStorageResource.

Bicep által generált ellátás

Ha most ismerkedik a Bicepnyelvvel, ez egy tartományspecifikus nyelv az Azure erőforrások definiálására. A .NET.NET Aspireesetében nem kell kézzel írnia a Bicep-et, mert a kiépítési API-k generálják azt önnek. Az alkalmazás közzétételekor a generált *Bicep* kimenetként a jegyzékfájl mellett jelenik meg. Azure Storage-erőforrás hozzáadásakor a következő Bicep jön létre:

@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

Az előző Bicep egy modul, amely egy Azure Storage-fiókot helyez üzembe az alábbi alapértelmezett értékekkel:

• kind: A tárfiók típusa. Az alapértelmezett érték a StorageV2.
• sku: A tárolási fiók SKU-ja. Az alapértelmezett érték a Standard_GRS.
• properties: A tárfiók tulajdonságai:
  • accessTier: A tárfiók hozzáférési szintje. Az alapértelmezett érték a Hot.
  • allowSharedKeyAccess: Logikai érték, amely jelzi, hogy a tárfiók engedélyezi-e a fiók hozzáférési kulcsával való engedélyezést. Az alapértelmezett érték a false.
  • minimumTlsVersion: A tárfiók minimálisan támogatott TLS-verziója. Az alapértelmezett érték a TLS1_2.
  • networkAcls: A tárfiók hálózati ACL-jeit. Az alapértelmezett érték a { defaultAction: 'Allow' }.

A tárhelyfiók mellett egy blob tárolót is létrehoz.

A következő szerepkör-hozzárendelések lesznek hozzáadva a tárfiókhoz az alkalmazás hozzáférésének biztosításához. További információért lásd a beépített Azure szerepköralapú hozzáférés-vezérlési (Azure RBAC) szerepköröket.

A létrehozott Bicep kiindulási pont, és testre szabható az adott követelményeknek megfelelően.

Ellátási infrastruktúra testreszabása

Minden .NET AspireAzure erőforrás a AzureProvisioningResource típusú alosztály. Ez a típus lehetővé teszi a létrehozott Bicep testreszabását azáltal, hogy egy folyékony API-t biztosít a Azure erőforrások konfigurálásához – a ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API használatával. Konfigurálhatja például a kind, sku, propertiesstb. Az alábbi példa bemutatja, hogyan szabhatja testre a Azure Storage-erőforrást:

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

Az előző kód:

• A hívást az ConfigureInfrastructure API-hoz láncolja:
  • A infra paraméter a AzureResourceInfrastructure típusú példány.
  • A kiosztható erőforrások a GetProvisionableResources() metódus meghívásával kérhetők le.
  • Az egyetlen StorageAccount lekérve.
  • A StorageAccount.AccessTier hozzá van rendelve StorageAccountAccessTier.Cool.
  • A StorageAccount.Sku-t egy új StorageSku-hez rendelték hozzá NamePremiumZrs-ként.
  • A rendszer hozzáad egy címkét a tárfiókhoz egy ExampleKey kulccsal és egy Example valueértékkel.

A Azure Storage-erőforrás testreszabásához számos további konfigurációs lehetőség áll rendelkezésre. További információ: Azure.Provisioning.Storage.

Csatlakozás meglévő Azure Storage-fiókhoz

Lehet, hogy rendelkezik egy meglévő Azure Storage-fiókkal, amelyhez csatlakozni szeretne. Ahelyett, hogy új Azure Storage-erőforrást hozna létre, hozzáadhat egy kapcsolati karakterláncot az alkalmazáshoszthoz. Ha meglévő Azure Storage-fiókhoz szeretne kapcsolatot létesíteni, hívja meg a AddConnectionString metódust:

var builder = DistributedApplication.CreateBuilder(args);

var blobs = builder.AddConnectionString("blobs");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(blobs);

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

A kapcsolati sztring az alkalmazás futtató környezetének konfigurációjában van konfigurálva, általában a Felhasználói titkos kódokalatt, a ConnectionStrings részben. Az alkalmazásgazda környezeti változóként injektálja ezt a kapcsolati sztringet az összes függő erőforrásba, például:

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

A függő erőforrás a GetConnectionString metódus meghívásával és a kapcsolatnév paraméterként való átadásával érheti el az injektált kapcsolati sztringet, ebben az esetben "blobs". A GetConnectionString API a IConfiguration.GetSection("ConnectionStrings")[name]rövidítése.

Azure Storage Emulator-erőforrás hozzáadása

Ha egy Azure Storage emulátor erőforrást szeretne hozzáadni, akkor kapcsoljon össze egy hívást egy IResourceBuilder<AzureStorageResource>-re a RunAsEmulator API-val.

var builder = DistributedApplication.CreateBuilder(args);

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

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

Amikor meghívja RunAsEmulator, a tárolóerőforrásokat úgy konfigurálja, hogy helyileg fussanak egy emulátor használatával. Az emulátor ebben az esetben Azurite. Az Azurite nyílt forráskódú emulátor ingyenes helyi környezetet biztosít a Azure Blob-, Queue Storage- és Table Storage-alkalmazások teszteléséhez, és tökéletes társ a .NET AspireAzure üzemeltetési integrációjához. Az Azurite nincs telepítve, hanem konténerként érhető el .NETés.NET Aspire számára. Amikor hozzáad egy tárolót az alkalmazás gazda folyamathoz, ahogy az az előző példában látható a mcr.microsoft.com/azure-storage/azurite képpel, az alkalmazás gazda folyamat indításakor létrehozza és elindítja a tárolót. További információkért lásd: Tárolóerőforrás-életciklus.

Azurite-tároló konfigurálása

A tárolóerőforrások különböző konfigurációkkal érhetők el, például konfigurálhatja a tároló portjait, környezeti változóit, élettartamátstb.

Azurite-tárolóportok konfigurálása

Alapértelmezés szerint az Azurite-tároló .NET.NET Aspirekonfigurálásakor a következő végpontokat teszi elérhetővé:

Az a port, amelyen figyelnek, alapértelmezés szerint dinamikus. Amikor a tároló elindul, a portok egy véletlenszerűen kiválasztott portra kerülnek leképezésre a gazdagépen. A végpontportok konfigurálásához lánchívásokat kell futtatnia a RunAsEmulator metódus által biztosított tárolóerőforrás-szerkesztőn az alábbi példában látható módon:

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

Az előző kód konfigurálja az Azurite-tároló meglévő blob, queueés table végpontjait a portok 27000, 27001és 27002figyelésére. Az Azurite-tároló portja a gazdagépportok szerint van leképezve az alábbi táblázatban látható módon:

Az azurite-tároló konfigurálása állandó élettartammal

Ha az Azurite-tárolót állandó élettartammal szeretné konfigurálni, hívja meg az WithLifetime metódust az Azurite-tároló erőforrásán, és adja át a 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...

További információért lásd: Tárolóerőforrás élettartama.

Azurite-konténer konfigurálása adatkötettel

Ha adatkötetet szeretne hozzáadni a Azure Storage emulátor erőforráshoz, hívja meg a WithDataVolume metódust a Azure Storage emulátor erőforráson:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Az adatkötet az Azurite-adatok tárolójának életciklusán kívüli megőrzésére szolgál. Az adatkötet az Azurite-tároló /data elérési útjához van kapcsolva, és ha nincs megadva a name paraméter, a név .azurite/{resource name}-ként van formázva. További információt az adatmennyiségekről, valamint arról, hogy miért előnyösebbek a bind mountokkal szemben, lásd a Docker dokümentációban: Volumes.

Azurite tároló konfigurálása adathozzákötéssel

Ha adatkötési csatlakoztatást szeretne hozzáadni a Azure Storage Emulator erőforráshoz, hívja meg a WithDataBindMount metódust:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Az adatkapcsolási pontok a gazdagép fájlrendszerére támaszkodnak, hogy az Azurite adatokat megőrizzék a tároló újraindításai során. Az adatkötési pont a gazdagép ../Azurite/Data elérési útjára van csatolva az Azurite tároló alkalmazás könyvtárához (IDistributedApplicationBuilder.AppHostDirectory) képest. Az adatkötési csatlakoztatásokkal kapcsolatos további információkért lásd Docker dokumentumokat: Kötési csatlakoztatások.

Csatlakozás tárolási erőforrásokhoz

Amikor a .NET.NET Aspire alkalmazás gazdagépe fut, a tárolási erőforrások külső eszközökkel, például a Azure Storage Explorer, érhetők el. Ha a tárolási erőforrás helyileg fut az Azurite használatával, a Azure Storage Explorer automatikusan felveszi.

Ha Azure Storage Explorerből szeretne csatlakozni a tárolóerőforráshoz, kövesse az alábbi lépéseket:

1. Futtassa a .NET.NET Aspire alkalmazás hosztot.

2. Nyissa meg a Azure Storage Explorert.

3. Tekintse meg a Explorer panelt.

4. Válassza az Összes frissítése hivatkozást a tárfiókok listájának frissítéséhez.

5. Bontsa ki a Emulator & Csatolt csomópontot.

6. Bővítse ki a Tárfiókok csomópontot.

7. Látnia kell egy tárfiókot, amelynek előtagja az erőforrás neve:

   

A tárfiókot és annak tartalmát a Azure Storage Explorer használatával tekintheti meg. További információ a Azure Storage Explorer használatáról: A Storage Explorer használatának első lépései.

Azure Table Storage erőforrás hozzáadása

Az alkalmazásgazda projektben regisztrálja a Azure Table Storage integrációt azáltal, hogy láncol egy AddTables hívást a IResourceBuilder<IAzureStorageResource>által visszaadott AddAzureStorage példányon. Az alábbi példa bemutatja, hogyan vehet fel Azure Table Storagestorage nevű erőforrást és egy tablesnevű táblaerőforrást:

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

Az előző kód:

• Hozzáad egy Azurenevű storage Storage-erőforrást.
• Hozzáad egy tables nevű táblatároló-erőforrást a tárolóerőforráshoz.
• Hozzáadja a storage erőforrást a ExampleProject-hez, és megvárja, amíg az készen áll, mielőtt elkezdené a projektet.

Integrációs állapotellenőrzések üzemeltetése

A Azure Storage-üzemeltetés integrációja automatikusan hozzáadja a tárolási erőforrás állapot-ellenőrzését. Csak emulátorként való futtatáskor lesz hozzáadva, és ellenőrzi, hogy az Azurite-tároló fut-e, és hogy létre lehet-e hozni vele kapcsolatot. Az üzemeltetési integráció az AspNetCore.HealthChecks 📦 és a Storage.BlobsAzure NuGet-csomagra támaszkodik.

Client integráció

Az .NET AspireAzure Adattáblák ügyfélintegrációjának megkezdéséhez telepítse a 📦Aspire.AzureData.Tables NuGet-csomagot abba a projektbe, amely az Azure Adattáblák ügyfelet használó alkalmazást tartalmazza. A Azure adattáblák ügyféloldali integrációja regisztrál egy TableServiceClient példányt, amelynek segítségével a felhasználó a Azure Table Storage-vel interakcióba léphet.

dotnet add package Aspire.Azure.Data.Tables

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

Azure Table Storage-ügyfél hozzáadása

A Program.cs fájlban az ügyfélprojektben hívja meg a AddAzureTableClient bővítménymetódusát bármelyik IHostApplicationBuilder-re, hogy regisztráljon egy TableServiceClient-at a függőséginjektáló konténerben való használatra. A metódus egy kapcsolatnévparamétert használ.

builder.AddAzureTableClient("tables");

Ezután függőséginjektálással lekérheti a TableServiceClient-példányt. Például, hogy gyorsan visszaszerezze az ügyfelet egy szolgáltatásból:

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

Konfiguráció

A .NET AspireAzure Table Storage integráció több lehetőséget is kínál a TableServiceClient konfigurálásához a projekt követelményei és konvenciói alapján.

Konfigurációs szolgáltatók használata

A .NET AspireAzure Table Storage integráció támogatja a Microsoft.Extensions.Configuration. A AzureDataTablesSettings és a TableClientOptions a Aspire:Azure:Data:Tables kulccsal kerül betöltésre a konfigurációból. Az alábbi kódrészlet egy példa egy appsettings.json fájlra, amely konfigurál néhány beállítást:

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

A Azure Adattáblák ügyfélintegrációs JSON sémáját lásd: Aspire.Azure. Data.Tables/ConfigurationSchema.json.

Beágyazott delegáltak használata

A Action<AzureDataTablesSettings> configureSettings delegáltat is átadhatja a beágyazott beállítások egy részének vagy mindegyikének beállításához, például a ServiceUrikonfigurálásához:

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

A TableClientOptions-t a Action<IAzureClientBuilder<TableServiceClient, TableClientOptions>> configureClientBuilder metódus második paramétereként megadott AddAzureTableClient delegált használatával is beállíthatja. Ha például a TableServiceClient azonosítót szeretné beállítani az ügyfél azonosításához:

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

Client integrációs állapotvizsgálatok

Alapértelmezés szerint az .NET.NET Aspire integrációk lehetővé teszik állapotellenőrzéseket az összes szolgáltatás esetében. További információ: .NET.NET Aspire integrációk áttekintése.

Az adattáblák .NET AspireAzure integrációja:

• Hozzáadja az állapot-ellenőrzést, amikor a AzureDataTablesSettings.DisableHealthChecks egyenlő false-gyel, mely megpróbál csatlakozni a Azure Table Storage-hez.
• Integrálható a /health HTTP-végponttal, amely meghatározza, hogy az összes regisztrált állapot-ellenőrzésnek át kell mennie ahhoz, hogy az alkalmazás készen álljon a forgalom elfogadására.

Megfigyelhetőség és telemetria

.NET .NET Aspire integrációk automatikusan beállítják a naplózási, nyomkövetési és metrikai konfigurációkat, amelyeket gyakran a megfigyelhetőség alappilléreinekneveznek. Az integráció megfigyelhetőségéről és telemetriáról további információt .NET.NET Aspire integrációk áttekintésében. A háttérszolgáltatástól függően egyes integrációk csak bizonyos funkciókat támogatnak. Egyes integrációk például támogatják a naplózást és a nyomkövetést, a metrikákat azonban nem. A telemetriai funkciók a Konfiguráció szakaszban ismertetett technikákkal is letilthatók.

Fakitermelés

A .NET AspireAzure adattáblák integrációja a következő naplókategóriákat használja:

• Azure.Core
• Azure.Identity

Nyomkövetés

A .NET AspireAzure adattáblák integrációja a következő nyomkövetési tevékenységeket bocsátja ki a OpenTelemetryhasználatával:

• Azure.Data.Tables.TableServiceClient

Mértékek

Az .NET AspireAzure adattáblák integrációja jelenleg nem támogatja alapértelmezés szerint a metrikákat a Azure SDK korlátozásai miatt.

Lásd még:

• Azure Table Storage dokumentumok
• .NET .NET Aspire integrációk
• .NET Aspire GitHub repo