integrace .NET AspireAzure Queue Storage

Článek
12/14/2024

zahrnuje:integraci hostování a integraci Client

Azure Queue Storage je služba pro ukládání velkého počtu zpráv, ke kterým se dá přistupovat odkudkoli na světě prostřednictvím ověřených volání. Integrace .NET AspireAzure Queue Storage umožňuje připojit se k existujícím instancím Azure Queue Storage nebo vytvářet nové instance z aplikací .NET.

Integrace hostování

.NET .NET Aspire Azure Storage hostování integračních modelů 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 úložiště tabulek Azure.

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 Správa závislostí balíčků v aplikacích .NET.

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 přidat AzureStorageResource před přidáním jakéhokoli jiného úložného prostředku.

Důležitý

Když voláte AddAzureStorage, implicitně volá AddAzureProvisioning– což přidává podporu pro 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é zřizování Bicep

Pokud s Bicep začínáte, jedná se o jazyk specifický pro doménu pro definování Azure prostředků. Pomocí .NET.NET Aspirenemusíte psát Bicep ručně; zřizovací rozhraní API generuje Bicep za vás. Když publikujete aplikaci, vygenerovaný Bicep je uložen spolu se souborem manifestu. Když přidáte prostředek Azure Storage, vygeneruje se následující Bicep:

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

@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í modul Bicep je modul, který zřídí Azure Storage účet s následujícími výchozími nastaveními:

kind: Druh účtu úložiště. Výchozí hodnota je StorageV2.
sku: Skladová položka úč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í do účtu úložiště, aby vaše aplikace měla přístup. Další informace najdete v předdefinovaných rolí Azure řízení přístupu na základě role (Azure RBAC):

Role / ID	Popis
Přispěvatel dat Blob Storage `ba92f5b4-2d11-453d-a403-e96b0029c9fe`	Čtení, zápis a odstranění ukládacích kontejnerů a bloků Azure.
Přispěvatel dat úložné tabulky `0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3`	Číst, psát a mazat tabulky a entity služby Azure Storage.
Přispěvatel dat fronty služby Storage `974c5e8b-45b9-4653-ba55-5f855dd0fb88`	Čtení, zápis a odstraňování front služby Storage a zpráv ve frontě 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ůsobte infrastrukturu pro zřizování

Všechny zdroje .NET AspireAzure jsou podtřídy typu AzureProvisioningResource. Tento typ umožňuje přizpůsobení vygenerovaného Bicep tím, že poskytuje plynulé API pro konfiguraci prostředků Azure pomocí rozhraní 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.
- Dostupné prostředky se načtou voláním metody GetProvisionableResources().
- Načte se jeden StorageAccount.
- StorageAccount.AccessTier je přiřazen k StorageAccountAccessTier.Cool.
- StorageAccount.Sku je přiřazeno novému StorageSku s Name o PremiumZrs.
- 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ů aplikace, například:

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

Závislý prostředek má přístup k vloženého 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řidání prostředku emulátoru úložiště Azure

Pokud chcete přidat prostředek emulátoru úložiště Azure, zřetězte volání IResourceBuilder<AzureStorageResource> do 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 kontejnerových prostředků.

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í na sestavovatele prostředků kontejneru poskytnutého metodou 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 existující koncové body blob, queuea table kontejneru Azurite tak, aby naslouchaly na portech 27000, 27001a 27002. 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í

Pokud chcete nakonfigurovat kontejner Azurite s perzistentní životností, zavolejte metodu WithLifetime na zdroji 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 prostředku emulátoru úložiště Azure, zavolejte metodu WithDataVolume prostředku emulátoru Azure úložiště:

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 kontejneru Azurite s připojením složky s daty

Pokud chcete přidat datový bind mount 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í, kde jsou potřebné změny v reálném čase.

Připojování datových vazeb spoléhá na systém souborů hostitelského počítače k zachování dat Azurite během restartování kontejneru. Datový bind mount je připojen k cestě ../Azurite/Data na hostitelském počítači vzhledem k adresáři hostitele aplikace (IDistributedApplicationBuilder.AppHostDirectory) v kontejneru Azurite. Další informace o připojeních datových vazeb najdete v dokumentaci Docker: Připojení vazby.

Připojení k prostředkům úložiště

Když hostitel aplikace .NET.NET Aspire běží, 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á Průzkumník úložiště Azure.

Poznámka

Průzkumník úložiště Azure objeví zdroje úložiště Azurite za předpokladu, že jsou použity 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ě pomocí nástroje Azure Storage Explorer, postupujte takto:

Spusťte hostitele aplikace .NET.NET Aspire.
Otevřete Průzkumníka služby Azure Storage.
Zobrazení podokna průzkumníka
Výběrem odkazu Obnovit vše aktualizujte seznam účtů úložiště.
Rozbalte uzel připojený k emulátoru &.
Rozbalte uzel účty úložiště .
Jako předponu by se měl zobrazit účet úložiště s 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řidání prostředku Azure Queue Storage

V hostitelském projektu aplikace zaregistrujte integraci Azure Queue Storage zřetězeným voláním AddQueues na instanci IResourceBuilder<IAzureStorageResource> vrácenou AddAzureStorage. Následující příklad demonstruje, jak přidat prostředek úložiště fronty Azure pojmenovaný storage a prostředek fronty pojmenovaný queues:

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

Předchozí kód:

Přidá úložný prostředek s názvem Azurenazvaný storage.
Přidá do prostředku úložiště frontu s názvem queues.
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 Queue Storage client, nainstalujte balíček NuGet 📦Aspire.Azure. Storage.Queues ve spotřebitelském projektu client, to jest v projektu pro aplikaci, která využívá Azure Queue Storage client. Integrace Azure Queue Storage client registruje instanci QueueServiceClient, kterou můžete použít k interakci s Azure Queue Storage.

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

dotnet add package Aspire.Azure.Storage.Queues

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

Přidání Azure queue Storage client

V souboru Program.cs projektu, který využívá client, zavolejte metodu rozšíření AddAzureQueueClient na libovolném IHostApplicationBuilder a zaregistrujte QueueServiceClient pro použití prostřednictvím kontejneru injektáže závislostí. Metoda přebírá parametr názvu připojení.

builder.AddAzureQueueClient("queue");

Potom můžete načíst instanci QueueServiceClient pomocí injektáže závislostí. Pokud chcete například načíst client ze služby:

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

Konfigurace

Integrace .NET AspireAzure Queue Storage nabízí několik možností konfigurace QueueServiceClient na základě požadavků a konvencí projektu.

Použijte připojovací řetězec

Při použití připojovacího řetězce z oddílu konfigurace ConnectionStrings můžete při volání AddAzureQueueClientzadat název připojovacího řetězce:

builder.AddAzureQueueClient("queue");

Připojovací řetězec se pak načte z oddílu konfigurace ConnectionStrings a podporují se dva formáty připojení:

URI služby

Doporučeným přístupem je použít ServiceUri, která pracuje s vlastností AzureStorageQueuesSettings.Credential pro navázání připojení. Pokud nejsou nakonfigurované žádné přihlašovací údaje, použije se Azure.Identity.DefaultAzureCredential.

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

Připojovací řetězec

Případně můžete použít připojovací řetězec Azure Storage,.

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

Další informace najdete v tématu Konfigurace připojovacích řetězců úložiště Azure.

Použití zprostředkovatelů konfigurace

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

{
  "Aspire": {
    "Azure": {
      "Storage": {
        "Queues": {
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "Diagnostics": {
              "ApplicationId": "myapp"
            }
          }
        }
      }
    }
  }
}

Pro úplné schéma integrace Azure Storage QueuesclientJSON se podívejte na Aspire.Azure. Data.Queues/ConfigurationSchema.json.

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

Můžete také předat delegáta Action<AzureStorageQueuesSettings> configureSettings a nastavit některé nebo všechny možnosti přímo, například nakonfigurovat zdravotní kontroly:

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

Můžete také nastavit QueueClientOptions pomocí Action<IAzureClientBuilder<QueueServiceClient, QueueClientOptions>> configureClientBuilder delegáta, druhého parametru metody AddAzureQueueClient. Například pokud chcete nastavit první část hlaviček user-agenta pro všechny požadavky generované tímto client:

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

Client kontroly stavu integrace

Integrace .NET.NET Aspire ve výchozím nastavení umožňují kontroly stavu pro všechny služby. Další informace naleznete v přehledu integrací .NET.NET Aspire.

Integrace .NET AspireAzure Queue Storage:

Přidá kontrolu stavu při AzureStorageQueuesSettings.DisableHealthChecksfalse, která se pokusí připojit k Azure Queue Storage.
Integruje se s HTTP koncovým bodem /health, který určuje, že všechny registrované kontroly stavu musí projít, aby byla aplikace považována za připravenou k přijímání provozu.

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 .NET AspireAzure Queue Storage používá následující kategorie protokolů:

Azure.Core
Azure.Identity

Trasování

Integrace .NET AspireAzure Queue Storage generuje pomocí OpenTelemetrynásledující aktivity trasování:

Azure.Storage.Queues.QueueClient

Metriky

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

Sdílet prostřednictvím