.NET Aspire Azure Queue Storage integrace

Článek
03/09/2025

zahrnuje: integraci hostování a Client integraci

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 modely integrace hostingu jsou různé prostředky úložiště rozděleny na 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 zdroj ú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é nasazení Bicep

Jestliže jste nováček v Bicep, je to jazyk specifický pro doménu sloužící k definici Azure prostředků. Pomocí .NET.NET Aspire nemusíte psát Bicep ručně; rozhraní API pro poskytování 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:

@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ý vytvoří Azure účet úložiště 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í do účtu úložiště, aby vaše aplikace měla přístup. Další informace najdete ve vestavěných rolích řízení přístupu na základě role (RBAC):

Role / Identifikátor	Popis
Přispěvatel dat úložiště Blob `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 mazá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ůsobte infrastrukturu pro nastavení

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 s 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 vytvoření nového prostředku Azure Storage můžete přidat připojovací řetězec do hostovacího prostředí aplikace. 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řidejte prostředek emulátoru úložiště Azure

Chcete-li přidat prostředek emulátoru úložiště Azure, navazujte volání na IResourceBuilder<AzureStorageResource> směrem k API 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 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`	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í 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(27000)
                                .WithQueuePort(27001)
                                .WithTablePort(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 k prostředku emulátoru úložiště Azure, zavolejte metodu WithDataVolume na prostředku 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 vázaným připojením, 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řiřazení dat mají omezenou funkčnost ve srovnání se svazky, které nabízejí lepší výkon, přenositelnost a zabezpečení, což je činí vhodnějšími 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. Pro více informací o připojování datových svazků si přečtěte dokumentaci Docker: Připojování svazků.

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.
Zobrazte podokno Průzkumník.
Výběrem odkazu Obnovit vše aktualizujte seznam účtů úložiště.
Rozbalte uzel Emulátor a Připojeno.
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 pomocí zřetězení volání AddQueues na instanci IResourceBuilder<IAzureStorageResource>, která je vrácena 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 pojmenovaný storage.
Přidá do prostředku úložiště frontu pojmenovanou 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í klienta .NET AspireAzure Queue Storage, nainstalujte balíček NuGet 📦Aspire.Azure. Storage.Queues v projektu, který spotřebovává klienta, tedy v projektu aplikace, která používá klienta Azure Queue Storage. Integrace klienta Azure Queue Storage registruje instanci QueueServiceClient, kterou můžete použít k interakci s Azure Queue Storage.

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Storage.Queues

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

Přidání klienta Azure Queue Storage

V souboru Program.cs ve vašem projektu využívajícím klienta zavolejte metodu rozšíření AddAzureQueueClient na libovolném IHostApplicationBuilder, abyste zaregistrovali QueueServiceClient pro použití prostřednictvím kontejneru pro injektování závislostí. Metoda přebírá parametr názvu připojení.

builder.AddAzureQueueClient("queue");

Potom můžete načíst instanci QueueServiceClient pomocí použití injektování závislostí. Například, abyste získali klienta 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ě lze použít řetězec připojení k úložišti Azure,.

{
  "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 klienta Azure Storage QueuesJSON viz 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. Pokud chcete například nastavit první část hlaviček uživatelského agenta pro všechny požadavky odeslané tímto klientem:

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.

Tato 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é zdravotní kontroly musí být úspěšné, aby mohla být aplikace považována za připravenou pro přijetí 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