.NET Aspire Azure Queue Storage-integráció

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

Azure Queue Storage olyan szolgáltatás, amely nagy számú üzenetet tárol, amelyek hitelesített hívásokon keresztül a világ bármely pontjáról elérhetők. A .NET AspireAzure Queue Storage-integráció lehetővé teszi, hogy meglévő Azure Queue 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ípusok szerint 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áshoszt projektben.

dotnet add package Aspire.Hosting.Azure.Storage

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

További információért lásd: dotnet add package vagy a 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-t egy Azure Storage-erőforrás-építő hozzáadásához és visszaküldéséhez.

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 ad az alkalmazás gazdagéphez, az más hasznos API-kat tesz elérhetővé a Azure Blob-, Queue- és Table-tárolási erőforrások hozzáadásához. Más szóval a többi tárolási erőforrás hozzáadása előtt hozzá kell adnia egy AzureStorageResource.

Generált erőforrás-ellátás Bicep

Ha új az Bicep, az egy tartományspecifikus nyelv az Azure erőforrások definiálására. A .NET.NET Aspirehasználatával nem kell kézzel megírnia a Bicepet, mert a kiépítési API-k generálják azt ön helyett. Az alkalmazás közzétételekor a generált Bicep a kimeneti fájlok között jelenik meg a jegyzékfájl mellett. 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árfió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árolási fiók mellett egy blob-tároló konténert is biztosít.

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 tekintse meg a beépített Azure szerepköralapú hozzáférés-vezérlés (Azure RBAC) szerepköröket.

Az elkészített Bicep egy kiindulási pont, amelyet a C# kiépítési infrastruktúrájának változásai befolyásolnak. A Bicep-fájl közvetlen módosításai felülíródnak, ezért elengedhetetlen, hogy a C# kiépítési API-kkal végezzen módosításokat, hogy azok megjelenjenek a létrehozott fájlokban.

Hozzáférés-engedélyezé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:

• Meghívást láncol az ConfigureInfrastructure API-hoz:
  • 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 StorageAccount lekérése megtörtént.
  • StorageAccount.AccessTier hozzá van rendelve a StorageAccountAccessTier.Cool-hez.
  • Az StorageAccount.Sku-át egy új StorageSku-hez rendelik hozzá, NamePremiumZrs-vel.
  • 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. Az új Azure Storage-erőforrás helyett hozzáadhat egy kapcsolati karakterláncot az alkalmazáshoz. 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 karakterlánc az alkalmazás gazdagépének konfigurációjában található, általában a Felhasználói titkok alatt, a ConnectionStrings szakaszban. 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ített formája.

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

Azure Storage emulátor-erőforrás hozzáadásához egy hívást kell összekapcsolnia a IResourceBuilder<AzureStorageResource>-től a RunAsEmulator API-hoz.

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 .NETés.NET Aspire tárolóként érhető el. Amikor hozzáad egy tárolót az alkalmazásgazdához, ahogyan az a mcr.microsoft.com/azure-storage/azurite képpel ellátott előző példában látható, az létrehozza és elindítja a tárolót az alkalmazásgazda indításakor. További információé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, amelyre figyelnek, alapértelmezés szerint dinamikus. A tároló indításakor a portok véletlenszerűen egy portra vannak leképezve 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 konténer portjai a gazdagép portjaihoz vannak leképezve az alábbi táblázat szerint:

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 tekintse meg a(z) tárolóerőforrás élettartamacímű részt.

Azurite-tároló konfigurálása adatköteg segítségével

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án van csatolva, és ha nincs megadva name paraméter, a név a .azurite/{resource name} formátumot kapja. További információkért arról, hogy miért részesítik előnyben a köteteket a bind mount-ok-kal szemben, lásd a Docker dokumentációt: Kötetek.

Az Azurite tároló konfigurálása adat kötési csatolással

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 adatkötések a gazdagép fájlrendszerére támaszkodnak, hogy az Azurite-adatok a konténer újraindításai között megmaradjanak. Az adatkötés fel van csatolva a gazdagép ../Azurite/Data elérési útjára, az Azurite-konténerben található alkalmazás gazdagép könyvtárához (IDistributedApplicationBuilder.AppHostDirectory) viszonyítva. 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áshosztot.

2. Nyissa meg a Azure Storage Explorert.

3. Tekintse meg a Explorer panelt.

4. Válassza az Az összes frissítése hivatkozásra kattintva frissítse a tárfiókok listáját.

5. Nyissa meg a Emulator & Attached csomópontot.

6. Nyissa meg a Tárfiókok csomópontot.

7. Látnod kell egy tárfiókot, amely az erőforrásod nevével rendelkezik előtagként.

   

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 Queue Storage-erőforrás hozzáadása

Az alkalmazásgazdaprojektben regisztrálja a Azure Queue Storage-integrációt úgy, hogy láncol egy hívást a AddQueues által visszaadott IResourceBuilder<IAzureStorageResource>-példányon keresztül a AddAzureStorage metódusra. Az alábbi példa megmutatja, hogyan vehet fel egy Azure üzenetsor-tárolási erőforrást storage és egy queues nevű üzenetsor-erőforrást:

var builder = DistributedApplication.CreateBuilder(args);

var queues = builder.AddAzureStorage("storage")
                    .AddQueues("queues");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(queues);

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

Az előző kód:

• Hozzáad egy Azurenevű storage Storage-erőforrást.
• Hozzáad egy queues nevű sort a tárolási erőforráshoz.
• Hozzáadja a storage erőforrást a ExampleProject-hez, és megvárja, amíg készen áll, mielőtt megkezdené 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. A hosting integráció a 📦 AspNetCore.HealthChecksAzure.Storage.Blobs NuGet-csomagtól függ.

Client integráció

A .NET AspireAzure Queue Storage kliensintegráció elindításához telepítse a 📦Aspire.Azure.Storage.Queues NuGet-csomagot abban a projektben, amelyik a Azure Queue Storage klienst használja, vagyis az alkalmazást megvalósító projektben. A Azure Queue Storage-ügyfélintegráció regisztrál egy QueueServiceClient példányt, amellyel kezelheti Azure Queue Storage-t.

dotnet add package Aspire.Azure.Storage.Queues

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

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

Az ügyfélfogyasztó projekt Program.cs fájljában hívja meg a AddAzureQueueClient kiterjesztési metódusát bármelyik IHostApplicationBuilder-on, hogy regisztráljon egy QueueServiceClient-at a függőséginjektáló konténeren keresztüli használatra. A metódus egy kapcsolatnévparamétert használ.

builder.AddAzureQueueClient("queue");

Ezután függőséginjektálással lekérheti a QueueServiceClient-példányt. Például az ügyfél adatainak lekérése egy szolgáltatásból:

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

Konfiguráció

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

Kapcsolati karakterlánc használata

Ha kapcsolati sztringet használ a ConnectionStrings konfigurációs szakaszból, megadhatja a kapcsolati sztring nevét AddAzureQueueClienthívásakor:

builder.AddAzureQueueClient("queue");

Ezután a kapcsolati sztringet lekérjük a ConnectionStrings konfigurációs szakaszból, és két kapcsolati formátum támogatott:

Szolgáltatás URI-ja

Az ajánlott módszer egy ServiceUrihasználata, amely a AzureStorageQueuesSettings.Credential tulajdonsággal együttműködve hoz létre kapcsolatot. Ha nincs hitelesítő adat konfigurálva, a rendszer a Azure.Identity.DefaultAzureCredential használja.

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

Kapcsolati karakterlánc

Másik lehetőségként egy Azure Storage kapcsolati karakterlánc is használható.

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

További információkért lásd a tárolási kapcsolati láncok Azure konfigurálása részt.

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

A .NET AspireAzure Queue Storage-integráció támogatja a Microsoft.Extensions.Configuration. A AzureStorageQueuesSettings-t és QueueClientOptions-t a konfigurációból tölti be, a Aspire:Azure:Storage:Queues kulcs használatával. 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": {
      "Storage": {
        "Queues": {
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "Diagnostics": {
              "ApplicationId": "myapp"
            }
          }
        }
      }
    }
  }
}

A teljes Azure Storage Queues ügyfél-integrációs JSON sémát lásd: Aspire.Azure. Data.Queues/ConfigurationSchema.json.

Használjon beágyazott delegáltakat.

A Action<AzureStorageQueuesSettings> configureSettings delegáltat is átadhatja, hogy a beállítások egy részét vagy egészét közvetlenül meghatározza, például az állapotellenőrzések konfigurálásához.

builder.AddAzureQueueClient(
    "queue",
    settings => settings.DisableHealthChecks = true);

A QueueClientOptions metódus második paramétereként a Action<IAzureClientBuilder<QueueServiceClient, QueueClientOptions>> configureClientBuilder is beállítható a AddAzureQueueClient delegált használatával. Például, ha be szeretné állítani a felhasználói ügynök fejléceinek első részét az ügyfél által küldött összes kéréshez:

builder.AddAzureQueueClient(
    "queue",
    configureClientBuilder: clientBuilder =>
        clientBuilder.ConfigureOptions(
            options => options.Diagnostics.ApplicationId = "myapp"));

Client integráció állapotfelmérései

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.

A .NET AspireAzure Queue Storage integrációja:

• Hozzáadja az állapot-ellenőrzést, amely megpróbál csatlakozni a AzureStorageQueuesSettings.DisableHealthChecks Queue Storagehöz, ha falseAzureállapotban van.
• 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 metrikakonfigurációkat, amelyeket más néven a megfigyelhetőség alappillérei. 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 Queue Storage-integráció a következő naplókategóriákat használja:

• Azure.Core
• Azure.Identity

Nyomkövetés

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

• Azure.Storage.Queues.QueueClient

Metrikák

A .NET AspireAzure Queue Storage 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 Üzenetsor-adattárolás dokumentumok
• .NET .NET Aspire integrációk
• .NET Aspire GitHub repozitórium