.NET Aspire Azure Blob Storage integracja

2025-06-18

Obejmuje: integrację hostingu — Client

Azure Blob Storage to usługa do przechowywania dużych ilości danych bez struktury. Integracja .NET AspireAzure Blob Storage umożliwia łączenie się z istniejącymi wystąpieniami Azure Blob Storage lub tworzenie nowych wystąpień z aplikacji .NET.

Integracja hostingu

.NET .NET Aspire Azure modele integracji hostingu modelują różne zasoby pamięci jako następujące typy:

AzureStorageResource: to zasób przechowywania Azure.
AzureStorageEmulatorResource: reprezentuje zasób emulatora usługi Azure Storage (Azurite).
AzureBlobStorageResource: Reprezentuje zasób usługi Blob Storage Azure.
AzureQueueStorageResource: reprezentuje zasób usługi Azure Queue Storage.
AzureTableStorageResource: reprezentuje zasób usługi przechowywania tabeli Azure.

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

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.Storage

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

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

Dodaj zasób pamięci Azure

W projekcie hosta aplikacji wywołaj AddAzureStorage, aby dodać i zwrócić konstruktor zasobu pamięci masowej Azure.

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, ujawnia to inne przydatne interfejsy API do dodawania Azure zasobów obiektów Blob, Queue i Table Storage. Innymi słowy, należy dodać AzureStorageResource przed dodaniem dowolnego innego zasobu pamięci masowej.

Ważny

Podczas wywoływania AddAzureStorageniejawnie uruchamia się AddAzureProvisioning, które umożliwia dynamiczne generowanie zasobów Azure podczas startu aplikacji. Aplikacja musi skonfigurować odpowiednią subskrypcję i lokalizację. Aby uzyskać więcej informacji, zobacz Lokalne przygotowanie: Konfiguracja.

Bicep wygenerowany przez prowizjonowanie

Jeśli dopiero zaczynasz korzystać z Bicep, to język domenowy 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, generowany plik Bicep jest zapisywany wraz z plikiem manifestu. Po dodaniu zasobu Azure Storage generowany jest 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 uprawnień są dodawane do konta przechowywania, aby zapewnić Twojej aplikacji dostęp. Aby uzyskać więcej informacji, zobacz wbudowane Azure role kontroli dostępu opartej na rolach (AzureRBAC):

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

Wygenerowany Bicep jest punktem wyjścia i ma wpływ na zmiany 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 poprzez zapewnienie elastycznego interfejsu API do konfigurowania zasobów Azure przy użyciu interfejsu API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Można na przykład skonfigurować kind, sku, propertiesi 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:

Łańcuch wywołania interfejsu API ConfigureInfrastructure:
- Parametr infra jest wystąpieniem typu AzureResourceInfrastructure.
- Zasoby możliwe do aprowizacji są pobierane przez wywołanie metody GetProvisionableResources().
- Pobierana jest pojedyncza StorageAccount.
- StorageAccount.AccessTier jest przypisywana do StorageAccountAccessTier.Cool.
- StorageAccount.Sku jest przypisany do nowego StorageSku z NamePremiumZrs.
- Do konta magazynu dodawany jest tag o kluczu ExampleKey i wartości Example value.

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łujesz RunAsEmulator, konfiguruje to zasoby magazynu do lokalnego uruchamiania przy użyciu emulatora. Emulator w tym przypadku jest Azurite. Emulator open-source Azurite udostępnia bezpłatne lokalne środowisko do testowania aplikacji Blob, Queue Storage i Table Storage oraz jest doskonałym towarzyszem integracji hostingu. 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.

Konfiguracja 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 hosta
`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ń konstruktora zasobów kontenera, które są dostępne dzięki metodzie 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 kontenera Azurite o identyfikatorach blob, queue, i table do nasłuchiwania na portach 27000, 27001, i 27002, odpowiednio. 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...

Wolumen danych jest używany do przechowywania 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 względem podłączania bind , zobacz dokumentację : Woluminy.

Konfigurowanie kontenera Azurite z zamontowanym powiązaniem danych

Aby dodać powiązanie danych do zasobu emulatora usługi Azure Storage, 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 montowania danych mają ograniczoną funkcjonalność w porównaniu z woluminami, które zapewniają lepszą wydajność, przenośność i bezpieczeństwo, czyniąc je bardziej odpowiednimi dla środowisk produkcyjnych. Jednak mounty wiążące umożliwiają bezpośredni dostęp i modyfikację plików w systemie hosta, co jest idealnym rozwiązaniem do pracy rozwojowej i testowania, gdzie potrzebne są zmiany w czasie rzeczywistym.

Montowanie danych zakłada korzystanie z systemu plików maszyny hosta, aby utrzymywać dane Azurite pomiędzy ponownymi uruchomieniami kontenera. Powiązanie danych jest zamontowane w ścieżce ../Azurite/Data na maszynie hosta względem katalogu hosta aplikacji (IDistributedApplicationBuilder.AppHostDirectory) w kontenerze Azurite. Aby uzyskać więcej informacji na temat wiązań danych, zobacz Docker dokumentację: Wiązania.

Łączenie z zasobami pamięci masowej

Po uruchomieniu hosta aplikacji .NET.NET Aspire, zasoby przechowywania mogą być uzyskiwane za pomocą narzędzi zewnętrznych, takich jak Azure Storage Explorer. Jeśli zasób magazynu jest uruchomiony lokalnie przy użyciu Azurite, zostanie on automatycznie wykryty przez Azure Storage Explorer.

Notatka

Eksplorator Azure Storage odnajduje zasoby magazynu Azurite, zakładając użycie portów domyślnych. 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:

Uruchom hosta aplikacji .NET.NET Aspire.
Otwórz Eksploratora usługi Azure Storage.
Wyświetl okienko Eksploratora.
Wybierz link Odśwież wszystkie, aby odświeżyć listę kont magazynowych.
Rozwiń węzeł Emulator & Podłączony.
Rozwiń węzeł Konta magazynu.
Powinieneś zobaczyć konto przechowywania z nazwą zasobu jako prefiks:

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

Dodawanie zasobu Azure Blob Storage

W projekcie hosta aplikacji zarejestruj integrację Azure Blob Storage, łącząc wywołanie AddBlobs z wystąpieniem IResourceBuilder<IAzureStorageResource> zwróconym przez AddAzureStorage. W poniższym przykładzie pokazano, jak dodać zasób Azure Blob Storage o nazwie storage i kontener obiektów BLOB o nazwie blobs:

var builder = DistributedApplication.CreateBuilder(args);

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

builder.AddProject<Projects.ExampleProject>()
       .WithReference(blobs)
       .WaitFor(blobs);

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

Powyższy kod:

Dodaje zasób przechowywania Azure o nazwie storage.
Łączy wywołanie RunAsEmulator, aby skonfigurować zasób pamięci masowej do działania lokalnie przy użyciu emulatora. Emulator w tym przypadku jest Azurite.
Dodaje kontener blobów o nazwie blobs do zasobu pamięci masowej.
Dodaje zasób blobs do ExampleProject i czeka, aż będzie gotowy przed rozpoczęciem projektu.

Bicep wygenerowany przez prowizjonowanie

Jeśli dopiero zaczynasz korzystać z Bicep, to język domenowy 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, generowany plik Bicep jest zapisywany wraz z plikiem manifestu. Po dodaniu zasobu Azure Storage generowany jest 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 uprawnień są dodawane do konta przechowywania, aby zapewnić Twojej aplikacji dostęp. Aby uzyskać więcej informacji, zobacz Azure

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

Wygenerowany Bicep jest punktem wyjścia i ma wpływ na zmiany 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

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:

Łańcuch wywołania interfejsu API ConfigureInfrastructure:
- Parametr infra jest wystąpieniem typu AzureResourceInfrastructure.
- Zasoby możliwe do aprowizacji są pobierane przez wywołanie metody GetProvisionableResources().
- Pobierana jest pojedyncza StorageAccount.
- StorageAccount.AccessTier jest przypisywana do StorageAccountAccessTier.Cool.
- StorageAccount.Sku jest przypisany do nowego StorageSku z NamePremiumZrs.
- Do konta magazynu dodawany jest tag o kluczu ExampleKey i wartości Example value.

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łujesz RunAsEmulator, konfiguruje to zasoby magazynu do lokalnego uruchamiania przy użyciu emulatora. Emulator w tym przypadku jest Azurite. Emulator open-source Azurite udostępnia bezpłatne lokalne środowisko do testowania aplikacji Blob, Queue Storage i Table Storage oraz jest doskonałym towarzyszem integracji hostingu. 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.

Konfiguracja 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 hosta
`blob`	10 000	dynamiczny
`queue`	10001	dynamiczny
`table`	10002	dynamiczny

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

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

Konfigurowanie kontenera Azurite z zamontowanym powiązaniem danych

Aby dodać powiązanie danych do zasobu emulatora usługi Azure Storage, 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

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 pod Sekrety użytkownika, w 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 dla IConfiguration.GetSection("ConnectionStrings")[name].

Łączenie z zasobami pamięci masowej

Notatka

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

Uruchom hosta aplikacji .NET.NET Aspire.
Otwórz Eksploratora usługi Azure Storage.
Wyświetl okienko Eksploratora.
Wybierz link Odśwież wszystkie, aby odświeżyć listę kont magazynowych.
Rozwiń węzeł Emulator & Podłączony.
Rozwiń węzeł Konta magazynu.
Powinieneś zobaczyć konto przechowywania z nazwą zasobu jako prefiks:

Kontrola stanu integracji hostingu

Integracja hostingu usługi Azure Storage automatycznie dodaje sprawdzenie kondycji 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.

Client integracja

Aby rozpocząć pracę z integracją klienta .NET AspireAzure Blob Storage, zainstaluj pakiet NuGet 📦Aspire.Azure.Storage.Blobs w projekcie wykorzystującym klienta, czyli w projekcie aplikacji używającej klienta Azure Blob Storage. Integracja klienta Azure Blob Storage rejestruje wystąpienie BlobServiceClient, którego można użyć do interakcji z Azure Blob Storage.

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Storage.Blobs

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

Dodaj klienta Azure Blob Storage

W pliku Program.cs projektu wykorzystującego klienta, wywołaj metodę rozszerzenia AddAzureBlobClient na dowolnym IHostApplicationBuilder, aby zarejestrować BlobServiceClient do użycia przez kontener wstrzykiwania zależności. Metoda przyjmuje parametr nazwy połączenia.

builder.AddAzureBlobClient("blobs");

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

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

Konfiguracja

Integracja .NET AspireAzure Blob Storage oferuje wiele opcji konfigurowania BlobServiceClient 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 AddAzureBlobClient:

builder.AddAzureBlobClient("blobs");

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ą AzureStorageBlobsSettings.Credential w celu nawiązania połączenia. Jeśli nie skonfigurowano żadnych poświadczeń, zostanie użyty Azure.Identity.DefaultAzureCredential.

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

Ciąg połączenia

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

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

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

Korzystanie z dostawców konfiguracji

Integracja .NET AspireAzure Blob Storage obsługuje Microsoft.Extensions.Configuration. AzureStorageBlobsSettings i BlobClientOptions ładowane są z konfiguracji za pomocą klucza Aspire:Azure:Storage:Blobs. Poniższy fragment kodu to przykład pliku appsettings.json, który konfiguruje niektóre opcje:

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

Aby uzyskać pełny schemat integracji klienta Azure Blob StorageJSON, zobacz Aspire.Azure. Storage.Blobs/ConfigurationSchema.json.

Używaj delegatów w linii

Możesz również przekazać delegata Action<AzureStorageBlobsSettings> configureSettings, aby skonfigurować niektóre lub wszystkie opcje wbudowane, na przykład w celu skonfigurowania kontroli kondycji:

builder.AddAzureBlobClient(
    "blobs",
    settings => settings.DisableHealthChecks = true);

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

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

Client przeglądy stanu integracji

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

Integracja .NET AspireAzure Blob Storage:

Dodaje sprawdzanie kondycji, gdy AzureStorageBlobsSettings.DisableHealthChecks jest false, co próbuje nawiązać połączenie z Azure Blob Storage.
Integruje się z punktem końcowym HTTP /health, który wymaga, aby wszystkie zarejestrowane kontrole sprawności były pomyślnie przeprowadzone, aby aplikacja została uznana za gotową do akceptowania ruchu.

Obserwowanie i telemetria

.NET .NET Aspire integracje automatycznie konfigurują logowanie, śledzenie i metryki, które są czasami nazywane filarami obserwowalności. 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 .NET AspireAzure Blob Storage używa następujących kategorii dzienników:

Azure.Core
Azure.Identity

Śledzenie

Integracja .NET AspireAzure Blob Storage emituje następujące działania śledzenia przy użyciu OpenTelemetry:

Azure.Storage.Blobs.BlobContainerClient

Metryki

Integracja .NET AspireAzure Blob Storage obecnie nie obsługuje domyślnie metryk z powodu ograniczeń SDK Azure.

Udostępnij za pośrednictwem

.NET Aspire Azure Blob Storage integracja

Integracja hostingu

Dodaj zasób pamięci Azure

Bicep wygenerowany przez prowizjonowanie

Dostosowywanie infrastruktury aprowizacji

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

Dodawanie zasobu emulatora usługi Azure Storage

Konfigurowanie kontenera Azurite

Konfiguracja portów kontenera Azurite

Konfigurowanie kontenera Azurite z trwałym okresem istnienia

Konfigurowanie kontenera Azurite za pomocą woluminu danych

Konfigurowanie kontenera Azurite z zamontowanym powiązaniem danych

Łączenie z zasobami pamięci masowej

Dodawanie zasobu Azure Blob Storage

Bicep wygenerowany przez prowizjonowanie

Dostosowywanie infrastruktury aprowizacji

Dodawanie zasobu emulatora usługi Azure Storage

Konfigurowanie kontenera Azurite

Konfiguracja portów kontenera Azurite

Konfigurowanie kontenera Azurite z trwałym okresem istnienia

Konfigurowanie kontenera Azurite za pomocą woluminu danych

Konfigurowanie kontenera Azurite z zamontowanym powiązaniem danych

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

Łączenie z zasobami pamięci masowej

Kontrola stanu integracji hostingu

Client integracja

Dodaj klienta Azure Blob Storage

Konfiguracja

Używanie parametrów połączenia

URI usługi

Ciąg połączenia

Korzystanie z dostawców konfiguracji

Używaj delegatów w linii

Client przeglądy stanu integracji

Obserwowanie i telemetria

Logowanie

Śledzenie

Metryki

Zobacz też

Dodatkowe zasoby