Udostępnij za pośrednictwem

integracja usługi .NET AspireAzure Queue Storage

Obejmuje:integracja hostingu obejmuje integrację hostingu — Client integracja dołączonaClient

Azure Queue Storage to usługa do przechowywania dużej liczby komunikatów, do których można uzyskiwać dostęp z dowolnego miejsca na świecie za pośrednictwem uwierzytelnionych wywołań. Integracja usługi .NET AspireAzure Queue Storage umożliwia łączenie się z istniejącymi wystąpieniami usługi Queue Storage Azure lub tworzenie nowych wystąpień z poziomu aplikacji .NET.

Integracja hostingu

.NET .NET Aspire Azure Storage integracja hostingu modeluje różne zasoby przechowywania w następujących typach:

Aby uzyskać dostęp do tych typów i interfejsów API do ich wyrażania, dodaj pakiet NuGet 📦Aspire.Hosting.Azure.Storage w projekcie hosta aplikacji .

dotnet add package Aspire.Hosting.Azure.Storage

Aby uzyskać więcej informacji, zobacz dotnet add package lub Zarządzaj zależnościami pakietów w aplikacjach .NET.

Dodaj zasób magazynowania Azure

W projekcie hosta aplikacji wywołaj AddAzureStorage, aby dodać i zwrócić konstruktor zasobów 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...

Po dodaniu AzureStorageResource do hosta aplikacji można uzyskać dostęp do innych przydatnych interfejsów API, aby dodawać zasoby przechowywania typu Blob, kolejki i przechowywanie tabel. Innymi słowy, należy dodać AzureStorageResource przed dodaniem dowolnych innych zasobów magazynowych.

Ważny

Kiedy wywołujesz AddAzureStorage, niejawnie wywołuje AddAzureProvisioning, co umożliwia obsługę dynamicznego generowania zasobów Azure podczas uruchamiania aplikacji. Aplikacja musi skonfigurować odpowiednią subskrypcję i lokalizację. Aby uzyskać więcej informacji, zobacz Lokalne udostępnianie: Konfiguracja.

Bicep wygenerowany przez prowizjonowanie

Jeśli dopiero zaczynasz z Bicep, jest to język dedykowany określonej dziedzinie, służący do definiowania zasobów Azure. Dzięki .NET.NET Aspire, nie musisz pisać Bicep ręcznie, gdyż API aprowizacyjne generują Bicep za Ciebie. Podczas publikowania aplikacji, wygenerowany plik Bicep jest dołączany razem z plikiem manifestu. Po dodaniu zasobu usługi Azure Storage jest generowany następujący kod Bicep:

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

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
}

output blobEndpoint string = storage.properties.primaryEndpoints.blob

output queueEndpoint string = storage.properties.primaryEndpoints.queue

output tableEndpoint string = storage.properties.primaryEndpoints.table

output name string = storage.name

Poprzedni Bicep to moduł, który tworzy konto usługi Azure Storage z następującymi wartościami domyślnymi.

  • kind: Rodzaj konta magazynowego. Wartość domyślna to StorageV2.
  • sku: SKU konta magazynowego. Wartość domyślna to Standard_GRS.
  • properties: Właściwości konta magazynowego:
    • accessTier: warstwa dostępu konta przechowywania. Wartość domyślna to Hot.
    • allowSharedKeyAccess: wartość logiczna wskazująca, czy konto magazynowe dopuszcza autoryzację żądań przy użyciu klucza dostępu do konta. Wartość domyślna to false.
    • minimumTlsVersion: minimalna obsługiwana wersja protokołu TLS dla konta przechowywania. Wartość domyślna to TLS1_2.
    • networkAcls: ACL sieciowe dla konta pamięci masowej. Wartość domyślna to { defaultAction: 'Allow' }.

Oprócz konta magazynowego, tworzy również kontener obiektów blob.

Następujące przypisania ról są dodawane do konta magazynowego, aby zapewnić dostęp do twojej aplikacji. Aby uzyskać więcej informacji, zobacz wbudowane Azure role kontroli dostępu opartej na rolach (AzureRBAC):

Rola i identyfikator Opis
Współautor danych obiektów blob Storage
ba92f5b4-2d11-453d-a403-e96b0029c9fe		 Odczytywanie, zapisywanie i usuwanie kontenerów i blobów Azure usługi Storage.
Współautor danych tabeli Storage
0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3		 Odczytywanie, zapisywanie i usuwanie tabel i jednostek usługi Storage Azure.
Współtwórca danych kolejki magazynowej
974c5e8b-45b9-4653-ba55-5f855dd0fb88		 Odczytywanie, zapisywanie i usuwanie Azure kolejek usługi Storage oraz wiadomości w kolejkach.

Wygenerowany Bicep jest punktem wyjścia i jest wynikiem zmian w infrastrukturze aprowizacji w języku C#. Modyfikacje pliku Bicep, które zostaną wprowadzone bezpośrednio, będą nadpisane. Dlatego należy wprowadzać je za pośrednictwem interfejsów API aprowizowania w języku C#, aby zapewnić, że zostaną odzwierciedlone w wygenerowanych plikach.

Dostosowywanie infrastruktury aprowizacji

Wszystkie zasoby .NET AspireAzure to podklasy typu AzureProvisioningResource. Ten typ umożliwia dostosowanie wygenerowanego kodu Bicep, zapewniając płynny interfejs API do konfigurowania zasobów Azure przy użyciu API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Można na przykład skonfigurować kind, sku, propertiesoraz inne. W poniższym przykładzie pokazano, jak dostosować zasób 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");
    });

Powyższy kod:

Dostępnych jest wiele innych opcji konfiguracji umożliwiających dostosowanie zasobu usługi Azure Storage. Aby uzyskać więcej informacji, zobacz Azure.Provisioning.Storage.

Nawiązywanie połączenia z istniejącym kontem usługi Azure Storage

Być może masz istniejące konto usługi Azure Storage, z którym chcesz nawiązać połączenie. Możesz łańcuchować wywołanie, aby wskazać, że AzureStorageResource jest istniejącym zasobem:

var builder = DistributedApplication.CreateBuilder(args);

var existingStorageName = builder.AddParameter("existingStorageName");
var existingStorageResourceGroup = builder.AddParameter("existingStorageResourceGroup");

var storageaccount = builder.AddAzureStorage("storage")
                    .AsExisting(existingStorageName, existingStorageResourceGroup)
                    .AddBlobs("blobs");

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

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

Aby uzyskać więcej informacji na temat traktowania Azure zasobów magazynu jako istniejących zasobów, zobacz Używanie istniejących Azure zasobów.

Notatka

Alternatywnie, zamiast reprezentować zasób konta magazynu Azure, możesz dodać ciąg połączenia do hosta aplikacji. Takie podejście jest słabo typizowane i nie działa z przypisaniami ról ani dostosowaniami infrastruktury. Aby uzyskać więcej informacji, zobacz Dodaj istniejące zasoby Azure z parametrami połączenia.

Dodawanie zasobu emulatora usługi Azure Storage

Aby dodać zasób emulatora usługi Azure Storage, połącz wywołanie IResourceBuilder<AzureStorageResource> z interfejsem API RunAsEmulator:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Gdy wywołasz RunAsEmulator, konfiguruje to Twoje zasoby magazynowe do lokalnego uruchamiania przy użyciu emulatora. Emulator w tym przypadku jest Azurite. Open-source emulator Azurite udostępnia bezpłatne lokalne środowisko do testowania aplikacji Azure Blob, Queue Storage i Table Storage i jest doskonałym towarzyszem integracji hostingu .NET AspireAzure. Azurite nie jest zainstalowana; zamiast tego, jest dostępna dla .NET.NET Aspire jako kontener. Po dodaniu kontenera do hosta aplikacji, jak pokazano w poprzednim przykładzie z obrazem mcr.microsoft.com/azure-storage/azurite, tworzy i uruchamia kontener po uruchomieniu hosta aplikacji. Aby uzyskać więcej informacji, zobacz Cykl życia zasobów kontenera.

Konfigurowanie kontenera Azurite

Istnieją różne konfiguracje dostępne dla zasobów kontenera, na przykład można skonfigurować porty kontenera, zmienne środowiskowe, jego okres istnienia i nie tylko.

Konfigurowanie portów kontenera Azurite

Domyślnie kontener Azurite skonfigurowany przez .NET.NET Aspireuwidacznia następujące punkty końcowe:

Punkt końcowy Port kontenerowy Port główny
blob 10 000 dynamiczny
queue 10001 dynamiczny
table 10002 dynamiczny

Port, na którym nasłuchują, jest dynamiczny domyślnie. Po uruchomieniu kontenera porty są mapowane na losowy port na maszynie hosta. Aby skonfigurować porty punktu końcowego, użyj łańcucha wywołań na budowniczym zasobów kontenera dostarczonym przez metodę RunAsEmulator, jak pokazano w poniższym przykładzie:

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

Powyższy kod konfiguruje istniejące punkty końcowe blob, queuei table kontenera Azurite do nasłuchiwania na portach 27000, 27001i 27002odpowiednio. Porty kontenera Azurite są mapowane na porty hosta, jak pokazano w poniższej tabeli:

Nazwa punktu końcowego Mapowanie portów (container:host)
blob 10000:27000
queue 10001:27001
table 10002:27002
Konfigurowanie kontenera Azurite z trwałym okresem istnienia

Aby skonfigurować kontener Azurite z trwałym okresem istnienia, wywołaj metodę WithLifetime w zasobie kontenera Azurite i przekaż 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...

Aby uzyskać więcej informacji, zobacz okres istnienia zasobu kontenera.

Konfigurowanie kontenera Azurite za pomocą woluminu danych

Aby dodać wolumin danych do zasobu emulatora usługi Azure Storage, wywołaj metodę WithDataVolume w zasobie emulatora usługi Azure Storage:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Wolumin danych jest używany do utrwalania danych Azurite poza cyklem życia kontenera. Wolumin danych jest instalowany w ścieżce /data w kontenerze Azurite, a gdy nie podano parametru name, nazwa jest sformatowana jako .azurite/{resource name}. Aby uzyskać więcej informacji na temat woluminów danych i szczegółów, dlaczego są preferowane zamiast bind mountów, zobacz Docker dokumentację: Woluminy.

Konfigurowanie kontenera Azurite przy użyciu punktu montowania danych

Aby dodać montowanie powiązań danych do zasobu emulatora Storage Azure, wywołaj metodę WithDataBindMount.

var builder = DistributedApplication.CreateBuilder(args);

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

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

Ważny

Powiązania danych mają ograniczoną funkcjonalność w porównaniu do woluminów, które oferują lepszą wydajność, przenośność i bezpieczeństwo, co czyni je bardziej odpowiednimi dla środowisk produkcyjnych. Jednak podłączenia typu bind umożliwiają bezpośredni dostęp i modyfikację plików w systemie hosta, co jest idealne do rozwoju i testowania, gdy potrzebne są zmiany w czasie rzeczywistym.

Montowanie danych poprzez powiązania polega na użyciu systemu plików maszyny hosta w celu zachowania danych Azurite podczas ponownego uruchamiania kontenera. Powiązanie danych jest zamontowane w ścieżce ../Azurite/Data na maszynie hosta wobec katalogu hosta aplikacji (IDistributedApplicationBuilder.AppHostDirectory) w kontenerze Azurite. Aby uzyskać więcej informacji na temat zamontowań powiązań danych, zobacz Docker dokumentacja: Zamontowania powiązań.

Łączenie z zasobami przechowywania

Po uruchomieniu hosta aplikacji .NET.NET Aspire do zasobów magazynu można uzyskać dostęp za pomocą narzędzi zewnętrznych, takich jak Azure Storage Explorer. Jeśli zasób magazynowy działa lokalnie z wykorzystaniem Azurite, Azure Storage Explorer automatycznie go wykryje.

Notatka

Eksplorator Azure Storage odnajduje zasoby Azurite, zakładając, że używane są porty domyślne. Jeśli skonfigurowano kontener Azurite do używania różnych portów, należy skonfigurować eksploratora usługi Azure Storage, aby nawiązać połączenie z odpowiednimi portami.

Aby nawiązać połączenie z zasobem magazynu z poziomu eksploratora usługi Azure Storage, wykonaj następujące kroki:

  1. Uruchom hosta aplikacji .NET.NET Aspire.

  2. Otwórz Eksploratora usługi Azure Storage.

  3. Wyświetl okienko Eksploratora .

  4. Wybierz link Odśwież wszystkie, aby odświeżyć listę kont magazynowych.

  5. Rozwiń węzeł Emulator & Podłączony.

  6. Rozwiń węzeł Konta magazynowe.

  7. Powinieneś zobaczyć konto magazynowania, którego nazwa zaczyna się od nazwy twojego zasobu.

    Azure Eksplorator magazynu: odnaleziono zasób magazynowy Azurite.

Możesz swobodnie eksplorować konto usługi magazynowej i jego zawartość, korzystając z Azure Eksploratora magazynu. Aby uzyskać więcej informacji na temat korzystania z Eksploratora usługi Azure Storage, zobacz Wprowadzenie do Eksploratora usługi Storage.

Dodaj zasób usługi Queue Storage Azure

W projekcie hosta aplikacji zarejestruj integrację z usługą Azure Queue Storage, łańcuchowo wykonując wywołanie AddQueues na instancji IResourceBuilder<IAzureStorageResource>, którą zwraca AddAzureStorage. W poniższym przykładzie pokazano, jak dodać zasób usługi Queue Storage Azure o nazwie storage i zasób kolejki o nazwie 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...

Powyższy kod:

  • Dodaje zasób usługi Azure Storage o nazwie storage.
  • Dodaje kolejkę o nazwie queues do zasobu pamięci masowej.
  • Dodaje zasób storage do ExampleProject i czeka, aż będzie gotowy przed rozpoczęciem projektu.

Bicep wygenerowany przez prowizjonowanie

Jeśli dopiero zaczynasz z Bicep, jest to język dedykowany określonej dziedzinie, służący do definiowania zasobów Azure. W przypadku .NET.NET Aspire, nie musisz pisać Bicep ręcznie; zamiast tego, interfejsy API do aprowizacji generują dla Ciebie Bicep. Podczas publikowania aplikacji, wygenerowany plik Bicep jest dołączany razem z plikiem manifestu. Po dodaniu zasobu usługi Azure Storage jest generowany następujący kod Bicep:

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

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
}

output blobEndpoint string = storage.properties.primaryEndpoints.blob

output queueEndpoint string = storage.properties.primaryEndpoints.queue

output tableEndpoint string = storage.properties.primaryEndpoints.table

output name string = storage.name

Powyższy Bicep jest modułem, który udostępnia Azure zasób konta magazynowego. Ponadto w osobnym module tworzone są przypisania ról dla zasobu Azure.

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param storage_outputs_name string

param principalType string

param principalId string

resource storage 'Microsoft.Storage/storageAccounts@2024-01-01' existing = {
  name: storage_outputs_name
}

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
}

Oprócz konta magazynowego, tworzy również kontener obiektów blob.

Następujące przypisania ról są dodawane do konta magazynowego, aby zapewnić dostęp do twojej aplikacji. Aby uzyskać więcej informacji, zobacz wbudowane Azure role kontroli dostępu opartej na rolach (AzureRBAC).

Rola i identyfikator Opis
Współautor danych obiektów blob Storage
ba92f5b4-2d11-453d-a403-e96b0029c9fe		 Odczytywanie, zapisywanie i usuwanie kontenerów i blobów Azure usługi Storage.
Współautor danych tabeli Storage
0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3		 Odczytywanie, zapisywanie i usuwanie tabel i jednostek usługi Storage Azure.
Współtwórca danych kolejki magazynowej
974c5e8b-45b9-4653-ba55-5f855dd0fb88		 Odczytywanie, zapisywanie i usuwanie Azure kolejek usługi Storage oraz wiadomości w kolejkach.

Wygenerowany Bicep jest punktem wyjścia i jest wynikiem zmian w infrastrukturze aprowizacji w języku C#. Jeśli wprowadzisz dostosowania bezpośrednio do pliku Bicep, zostaną one zastąpione, więc wprowadź zmiany za pośrednictwem interfejsów API aprowizacji języka C#, aby upewnić się, że zostaną one odzwierciedlone w wygenerowanych plikach.

Dostosowywanie infrastruktury aprowizacji

Wszystkie zasoby .NET AspireAzure to podklasy typu AzureProvisioningResource. Ten typ umożliwia dostosowanie wygenerowanego kodu Bicep, zapewniając płynny interfejs API do konfigurowania zasobów Azure przy użyciu API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Można na przykład skonfigurować kind, sku, propertiesoraz inne. W poniższym przykładzie pokazano, jak dostosować zasób 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");
    });

Powyższy kod:

Dostępnych jest wiele innych opcji konfiguracji umożliwiających dostosowanie zasobu usługi Azure Storage. Aby uzyskać więcej informacji, zobacz Azure.Provisioning.Storage.

Dodawanie zasobu emulatora usługi Azure Storage

Aby dodać zasób emulatora usługi Azure Storage, połącz wywołanie IResourceBuilder<AzureStorageResource> z interfejsem API RunAsEmulator:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Gdy wywołasz RunAsEmulator, konfiguruje to Twoje zasoby magazynowe do lokalnego uruchamiania przy użyciu emulatora. Emulator w tym przypadku jest Azurite. Open-source emulator Azurite udostępnia bezpłatne lokalne środowisko do testowania aplikacji Azure Blob, Queue Storage i Table Storage i jest doskonałym towarzyszem integracji hostingu .NET AspireAzure. Azurite nie jest zainstalowany; Zamiast tego jest dostępny .NET.NET Aspire jako kontener. Po dodaniu kontenera do hosta aplikacji, jak pokazano w poprzednim przykładzie z obrazem mcr.microsoft.com/azure-storage/azurite, tworzy i uruchamia kontener po uruchomieniu hosta aplikacji. Aby uzyskać więcej informacji, zobacz Cykl życia zasobów kontenera.

Konfigurowanie kontenera Azurite

Istnieją różne konfiguracje dostępne dla zasobów kontenera, na przykład można skonfigurować porty kontenera, zmienne środowiskowe, okres istnienia i nie tylko.

Konfigurowanie portów kontenera Azurite

Domyślnie kontener Azurite, skonfigurowany przez .NET.NET Aspire, uwidacznia następujące punkty końcowe:

Punkt końcowy Port kontenerowy Port główny
blob 10 000 dynamiczny
queue 10001 dynamiczny
table 10002 dynamiczny

Port, na którym nasłuchują, jest dynamiczny domyślnie. Po uruchomieniu kontenera porty są mapowane na losowy port na maszynie hosta. Aby skonfigurować porty punktu końcowego, użyj łańcucha wywołań na budowniczym zasobów kontenera dostarczonym przez metodę RunAsEmulator, jak pokazano w poniższym przykładzie:

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

Powyższy kod konfiguruje istniejące punkty końcowe blob, queuei table kontenera Azurite do nasłuchiwania na portach 27000, 27001i 27002odpowiednio. Porty kontenera Azurite są mapowane na porty hosta, jak pokazano w poniższej tabeli:

Nazwa punktu końcowego Mapowanie portów (container:host)
blob 10000:27000
queue 10001:27001
table 10002:27002
Konfigurowanie kontenera Azurite z trwałym okresem istnienia

Aby skonfigurować kontener Azurite z trwałym okresem istnienia, wywołaj metodę WithLifetime w zasobie kontenera Azurite i przekaż 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...

Aby uzyskać więcej informacji, zobacz okres istnienia zasobu kontenera.

Konfigurowanie kontenera Azurite za pomocą woluminu danych

Aby dodać wolumin danych do zasobu emulatora usługi Azure Storage, wywołaj metodę WithDataVolume w zasobie emulatora usługi Azure Storage:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Wolumin danych jest używany do utrwalania danych Azurite poza cyklem życia kontenera. Wolumin danych jest instalowany w ścieżce /data w kontenerze Azurite, a gdy nie podano parametru name, nazwa jest sformatowana jako .azurite/{resource name}. Aby uzyskać więcej informacji na temat woluminów danych i szczegółów, dlaczego są preferowane zamiast bind mountów, zobacz Docker dokumentację: Woluminy.

Konfigurowanie kontenera Azurite przy użyciu punktu montowania danych

Aby dodać montowanie powiązań danych do zasobu emulatora Storage Azure, wywołaj metodę WithDataBindMount.

var builder = DistributedApplication.CreateBuilder(args);

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

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

Ważny

Powiązania danych mają ograniczoną funkcjonalność w porównaniu do woluminów, które oferują lepszą wydajność, przenośność i bezpieczeństwo, co czyni je bardziej odpowiednimi dla środowisk produkcyjnych. Jednak podłączenia typu bind umożliwiają bezpośredni dostęp i modyfikację plików w systemie hosta, co jest idealne do rozwoju i testowania, gdy potrzebne są zmiany w czasie rzeczywistym.

Montowanie danych poprzez powiązania polega na użyciu systemu plików maszyny hosta w celu zachowania danych Azurite podczas ponownego uruchamiania kontenera. Powiązanie danych jest zamontowane w ścieżce ../Azurite/Data na maszynie hosta wobec katalogu hosta aplikacji (IDistributedApplicationBuilder.AppHostDirectory) w kontenerze Azurite. Aby uzyskać więcej informacji na temat zamontowań powiązań danych, zobacz Docker dokumentacja: Zamontowania powiązań.

Nawiązywanie połączenia z istniejącym kontem usługi Azure Storage

Być może masz istniejące konto usługi Azure Storage, z którym chcesz nawiązać połączenie. Zamiast reprezentować nowy zasób usługi Azure Storage, możesz dodać ciąg połączenia do hosta aplikacji. Aby dodać połączenie z istniejącym kontem usługi Azure Storage, wywołaj metodę 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...

Notatka

Parametry połączenia służą do reprezentowania szerokiego zakresu informacji o połączeniu, w tym połączeń z bazą danych, brokerów komunikatów, identyfikatorów URI punktów końcowych i innych usług. W .NET.NET Aspire nomenklaturze termin "parametry połączenia" służy do reprezentowania wszelkich informacji o połączeniu.

Parametry połączenia są konfigurowane w konfiguracji hosta aplikacji, zazwyczaj w obszarze Wpisy tajne użytkownikaw sekcji ConnectionStrings. Host aplikacji wprowadza te parametry połączenia jako zmienną środowiskową do wszystkich zasobów zależnych, na przykład:

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

Zasób zależny może uzyskać dostęp do wstrzykiwanych parametrów połączenia, wywołując metodę GetConnectionString i przekazując nazwę połączenia jako parametr, w tym przypadku "blobs". Interfejs API GetConnectionString jest skrótem od IConfiguration.GetSection("ConnectionStrings")[name].

Łączenie z zasobami przechowywania

Po uruchomieniu hosta aplikacji .NET.NET Aspire do zasobów magazynu można uzyskać dostęp za pomocą narzędzi zewnętrznych, takich jak Azure Storage Explorer. Jeśli zasób magazynowy działa lokalnie z wykorzystaniem Azurite, Azure Storage Explorer automatycznie go wykryje.

Notatka

Eksplorator Azure Storage odnajduje zasoby Azurite, zakładając, że używane są porty domyślne. Jeśli skonfigurowano kontener Azurite do używania różnych portów, należy skonfigurować eksploratora usługi Azure Storage, aby nawiązać połączenie z odpowiednimi portami.

Aby nawiązać połączenie z zasobem magazynu z poziomu eksploratora usługi Azure Storage, wykonaj następujące kroki:

  1. Uruchom hosta aplikacji .NET.NET Aspire.

  2. Otwórz Eksploratora usługi Azure Storage.

  3. Wyświetl okienko Eksploratora .

  4. Wybierz link Odśwież wszystkie, aby odświeżyć listę kont magazynowych.

  5. Rozwiń węzeł Emulator & Podłączony.

  6. Rozwiń węzeł Konta magazynowe.

  7. Powinieneś zobaczyć konto magazynowania, którego nazwa zaczyna się od nazwy twojego zasobu.

    Azure Eksplorator magazynu: odnaleziono zasób magazynowy Azurite.

Możesz swobodnie eksplorować konto usługi magazynowej i jego zawartość, korzystając z Azure Eksploratora magazynu. Aby uzyskać więcej informacji na temat korzystania z Eksploratora usługi Azure Storage, zobacz Wprowadzenie do Eksploratora usługi Storage.

Monitorowanie kondycji integracji systemów

Integracja hostingu usługi Azure Storage automatycznie dodaje kontrolę stanu zasobu pamięci. Jest on dodawany tylko w przypadku uruchamiania jako emulator i sprawdza, czy kontener Azurite jest uruchomiony i że można nawiązać z nim połączenie. Integracja hostingu opiera się na pakiecie NuGet 📦 AspNetCore.HealthChecks.Azure.Storage.Blobs.

integracja Client

Aby rozpocząć integrację z klientem usługi .NET AspireAzure Queue Storage, zainstaluj pakiet NuGet 📦Aspire.Azure.Storage.Queues w projekcie korzystającym z tego klienta, czyli w projekcie aplikacji, która używa klienta usługi Queue Storage Azure. Integracja klienta usługi Azure Queue Storage rejestruje wystąpienie QueueServiceClient, którego można użyć do interakcji z usługą Azure Queue Storage.

dotnet add package Aspire.Azure.Storage.Queues

Dodanie klienta usługi Azure Queue Storage

W pliku Program.cs projektu korzystającego z klienta wywołaj metodę rozszerzenia AddAzureQueueClient na dowolnym IHostApplicationBuilder, aby zarejestrować QueueServiceClient do użycia za pośrednictwem kontenera wstrzykiwania zależności. Metoda przyjmuje parametr nazwy połączenia.

builder.AddAzureQueueClient("queue");

Następnie można pobrać wystąpienie QueueServiceClient za pomocą wstrzykiwania zależności. Aby na przykład pobrać klienta z usługi:

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

Konfiguracja

Integracja .NET AspireAzure Queue Storage oferuje wiele opcji konfigurowania QueueServiceClient na podstawie wymagań i konwencji projektu.

Używanie parametrów połączenia

W przypadku używania parametrów połączenia z sekcji konfiguracji ConnectionStrings można podać nazwę parametrów połączenia podczas wywoływania AddAzureQueueClient:

builder.AddAzureQueueClient("queue");

Następnie parametry połączenia są pobierane z sekcji konfiguracji ConnectionStrings, a obsługiwane są dwa formaty połączenia:

URI usługi

Zalecaną metodą jest użycie ServiceUri, która współpracuje z właściwością AzureStorageQueuesSettings.Credential w celu nawiązania połączenia. Jeśli nie skonfigurowano poświadczeń, zostanie użyta wartość Azure.Identity.DefaultAzureCredential.

{
  "ConnectionStrings": {
    "queue": "https://{account_name}.queue.core.windows.net/"
  }
}
Ciąg połączenia

Alternatywnie można użyć ciągu połączeniowego Azure Storage.

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

Aby uzyskać więcej informacji, zobacz Configure Azure Storage connection strings.

Korzystanie z dostawców konfiguracji

Integracja usługi .NET AspireAzure Queue Storage obsługuje Microsoft.Extensions.Configuration. Ładuje AzureStorageQueuesSettings i QueueClientOptions z konfiguracji przy użyciu klucza Aspire:Azure:Storage:Queues. Poniższy fragment kodu to przykład pliku appsettings.json, który konfiguruje niektóre opcje:

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

Aby uzyskać pełny schemat integracji klienta Azure Storage QueuesJSON, zobacz Aspire.Azure.Data.Queues/ConfigurationSchema.json.

Użyj delegatów wbudowanych

Możesz również przekazać delegata Action<AzureStorageQueuesSettings> configureSettings, aby bezpośrednio skonfigurować niektóre lub wszystkie opcje, na przykład do sprawdzania stanu:

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

Można również skonfigurować QueueClientOptions przy użyciu delegata Action<IAzureClientBuilder<QueueServiceClient, QueueClientOptions>> configureClientBuilder, drugiego parametru metody AddAzureQueueClient. Aby na przykład ustawić pierwszą część nagłówków user-agent dla wszystkich żądań wysyłanych przez tego klienta:

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

Client sprawdzanie stanu integracji

Domyślnie .NET.NET Aspire integracje włączają kontrole kondycji dla wszystkich usług. Aby uzyskać więcej informacji, zobacz omówienie integracji .NET.NET Aspire.

Integracja .NET AspireAzure z Queue Storage.

  • Dodaje kontrolę kondycji, gdy AzureStorageQueuesSettings.DisableHealthChecks jest false, która próbuje nawiązać połączenie z usługą Azure Queue Storage.
  • Integruje się z punktem końcowym HTTP /health, który określa, że wszystkie zarejestrowane kontrole zdrowia muszą zostać pomyślnie zakończone, aby aplikacja została uznana za gotową do akceptowania ruchu.

Obserwowanie i telemetria

.NET .NET Aspire integracje automatycznie konfigurują konfiguracje rejestrowania, śledzenia i metryk, które są czasami nazywane filarami możliwości obserwowania. Aby uzyskać więcej informacji na temat możliwości obserwacji integracji i telemetrii, zobacz omówienie integracji .NET.NET Aspire. W zależności od usługi pomocniczej niektóre integracje mogą obsługiwać tylko niektóre z tych funkcji. Na przykład niektóre integracje obsługują rejestrowanie i śledzenie, ale nie metryki. Funkcje telemetrii można również wyłączyć przy użyciu technik przedstawionych w sekcji konfiguracji .

Logowanie

Integracja usługi .NET AspireAzure Queue Storage używa następujących kategorii dzienników:

  • Azure.Core
  • Azure.Identity

Śledzenie

Integracja usługi .NET AspireAzure Queue Storage generuje następujące działania śledzenia przy użyciu OpenTelemetry:

  • Azure.Storage.Queues.QueueClient

Metryki

Obecnie integracja .NET AspireAzure Queue Storage nie obsługuje metryk domyślnie z powodu ograniczeń w SDK Azure.

Zobacz też