integracja tabel danych .NET AspireAzure

Artykuł
12/15/2024

obejmuje:integrację hostingu oraz integrację Client

Azure Table Storage to usługa do przechowywania ustrukturyzowanych danych NoSQL. Tabele danych .NET AspireAzure umożliwiają łączenie się z istniejącymi wystąpieniami Azure Table Storage lub tworzenie nowych wystąpień z aplikacji .NET.

Integracja hostingu

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

AzureStorageResource: reprezentuje zasób usługi Azure Storage.
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 Table Storage 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 hosta aplikacji .

interfejsu wiersza polecenia.NET
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.

Dodawanie zasobu Azure Storage

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

Ważny

Podczas wywoływania AddAzureStorageautomatycznie wywoływane jest AddAzureProvisioning, co dodaje obsługę do dynamicznego generowania zasobów Azure podczas uruchamiania aplikacji. Aplikacja musi skonfigurować odpowiednią subskrypcję i lokalizację. Aby uzyskać więcej informacji, zobacz Lokalne wdrażanie: Konfiguracja.

Wygenerowana aprowizacja Bicep

Jeśli dopiero zaczynasz Bicep, to specyficzny dla domeny język do definiowania zasobów Azure. Dzięki .NET.NET Aspirenie musisz pisać Bicep ręcznie, natomiast interfejsy API do aprowizacji generują Bicep za Ciebie. Podczas publikowania aplikacji wygenerowany Bicep jest wyświetlany wraz z plikiem manifestu. Po dodaniu zasobu usługi Azure Storage jest generowany następujący kod Bicep:

przełącz Azure Storage Bicep.

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

param principalId string

param principalType string

resource storage 'Microsoft.Storage/storageAccounts@2024-01-01' = {
  name: take('storage${uniqueString(resourceGroup().id)}', 24)
  kind: 'StorageV2'
  location: location
  sku: {
    name: 'Standard_GRS'
  }
  properties: {
    accessTier: 'Hot'
    allowSharedKeyAccess: false
    minimumTlsVersion: 'TLS1_2'
    networkAcls: {
      defaultAction: 'Allow'
    }
  }
  tags: {
    'aspire-resource-name': 'storage'
  }
}

resource blobs 'Microsoft.Storage/storageAccounts/blobServices@2024-01-01' = {
  name: 'default'
  parent: storage
}

resource storage_StorageBlobDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe')
    principalType: principalType
  }
  scope: storage
}

resource storage_StorageTableDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3')
    principalType: principalType
  }
  scope: storage
}

resource storage_StorageQueueDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '974c5e8b-45b9-4653-ba55-5f855dd0fb88'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '974c5e8b-45b9-4653-ba55-5f855dd0fb88')
    principalType: principalType
  }
  scope: storage
}

output blobEndpoint string = storage.properties.primaryEndpoints.blob

output queueEndpoint string = storage.properties.primaryEndpoints.queue

output tableEndpoint string = storage.properties.primaryEndpoints.table

Poprzedni Bicep to moduł, który aprowizuje 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 magazynowego. Wartość domyślna to Hot.
- allowSharedKeyAccess: wartość logiczna wskazująca, czy konto magazynu zezwala na autoryzację żądań przy użyciu klucza dostępu do konta. Wartość domyślna to false.
- minimumTlsVersion: Minimalna obsługiwana wersja protokołu Transport Layer Security (TLS) dla konta magazynu. Wartość domyślna to TLS1_2.
- networkAcls: ACL sieciowe dla konta pamięci masowej. Wartość domyślna to { defaultAction: 'Allow' }.

Oprócz konta przechowywania, udostępnia również kontener obiektów blob.

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

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

Wygenerowany Bicep jest punktem wyjścia i można go dostosować, aby spełnić określone wymagania.

Dostosowywanie infrastruktury aprowizacji

Wszystkie zasoby .NET AspireAzure to podklasy typu AzureProvisioningResource. Ten typ umożliwia dostosowanie wygenerowanego skryptu Bicep dzięki zapewnieniu płynnego 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, 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:

Ł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 przypisywany do nowego StorageSku o NamePremiumZrs.
- Tag dodawany jest do konta magazynu z kluczem 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. Zamiast reprezentować nowy zasób usługi Azure Storage, możesz dodać łańcuch 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 dla IConfiguration.GetSection("ConnectionStrings")[name].

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

Podczas połączenia z RunAsEmulator, program konfiguruje zasoby magazynowe do lokalnego uruchamiania przy użyciu emulatora. Emulator w tym przypadku jest Azurite. Emulator open-source usługi Azurite udostępnia bezpłatne środowisko lokalne do testowania Azure aplikacji Blob, Queue Storage i Table Storage oraz jest doskonałym towarzyszem integracji .NET AspireAzure hostingu. Azurite nie jest zainstalowany; jest dostępny 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, czas życiai więcej.

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

Port, na który nasłuchuje, jest domyślnie dynamiczny. Po uruchomieniu kontenera porty są mapowane na losowy port na maszynie hosta. Aby skonfigurować porty punktu końcowego, użyj łańcuchowych wywołań na konstruktorze 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("blob", 27000)
                                .WithQueuePort("queue", 27001)
                                .WithTablePort("table", 27002);
                     });

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

Poprzedni kod konfiguruje istniejące punkty końcowe blob, queuei table kontenera Azurite do nasłuchiwania na portach 27000, 27001i 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 jego 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 dlaczego są preferowane zamiast montowanych punktów , sprawdź dokumentację Docker: Woluminy.

Konfigurowanie kontenera Azurite przy użyciu zamocowania powiązania danych

Aby dodać powiązanie 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

Instalacje powiązane danych mają ograniczoną funkcjonalność w porównaniu z woluminami , co zapewnia lepszą wydajność, przenośność i bezpieczeństwo, co czyni je bardziej odpowiednimi dla środowisk produkcyjnych. Jednak wiązania umożliwiają bezpośredni dostęp i modyfikację plików w systemie hosta, co jest idealne do rozwoju i testowania, gdzie potrzebne są zmiany w czasie rzeczywistym.

Montowanie punktów powiązań danych polega na użyciu systemu plików maszyny hosta, aby utrwalić dane Azurite podczas ponownych uruchomień kontenera. Montowanie powiązania danych jest zamontowane w ścieżce ../Azurite/Data na maszynie hosta relatywnie do katalogu hosta aplikacji (IDistributedApplicationBuilder.AppHostDirectory) w kontenerze Azurite. Aby uzyskać więcej informacji na temat instalacji powiązań danych, zobacz Docker docs: Bind mounts.

Łączenie z zasobami pamięci masowej

Gdy host aplikacji .NET.NET Aspire jest uruchomiony, zasoby magazynowe mogą być dostępne za pomocą narzędzi zewnętrznych, takich jak Azure Storage Explorer. Jeśli zasób magazynu jest uruchomiony lokalnie przy użyciu usługi Azurite, zostanie on automatycznie odebrany przez eksploratora usługi Azure Storage.

Notatka

Eksplorator zasobów Azure Storage wyszukuje zasoby pamięci masowej 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 & Dołączony.
Rozwiń węzeł Konta magazynowe.
Powinieneś zobaczyć konto magazynowe z nazwą twojego zasobu jako prefiks:

Możesz bezpłatnie eksplorować konto magazynu i jego zawartość przy użyciu eksploratora 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 Table Storage

W projekcie hosta aplikacji zarejestruj integrację Azure Table Storage, łącząc wywołanie AddTables w wystąpieniu IResourceBuilder<IAzureStorageResource> zwróconym przez AddAzureStorage. W poniższym przykładzie pokazano, jak dodać zasób Azure Table Storage o nazwie storage i zasób tabeli o nazwie tables:

var builder = DistributedApplication.CreateBuilder(args);

var tables = builder.AddAzureStorage("storage")
                    .AddTables("tables");

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

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

Powyższy kod:

Dodaje zasób Storage Azure o nazwie storage.
Dodaje zasób magazynu tabel o nazwie tables do zasobu magazynu.
Dodaje zasób storage do ExampleProject i czeka, aż będzie gotowy przed rozpoczęciem projektu.

Sprawdzanie stanu integracji hostingu

Integracja hostingu usługi Azure Storage automatycznie dodaje sprawdzanie kondycji zasobu magazynowego. 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 📦 AspNetCore.HealthChecks.Azure.Storage.Blobs pakiet NuGet.

integracja Client

Aby rozpocząć pracę z integracją tabel danych .NET AspireAzureclient, zainstaluj pakiet NuGet 📦Aspire.Azure.Data.Tables w projekcie korzystającym z client, to znaczy w projekcie aplikacji, która korzysta z tabel danych Azureclient. Integracja tabel danych Azureclient rejestruje wystąpienie TableServiceClient, którego można użyć do interakcji z Azure Table Storage.

interfejsu wiersza polecenia.NET
PackageReference

dotnet add package Aspire.Azure.Data.Tables

<PackageReference Include="Aspire.Azure.Data.Tables"
                  Version="*" />

Dodaj Azure Table Storageclient

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

builder.AddAzureTableClient("tables");

Następnie można pobrać instancję TableServiceClient przy użyciu wstrzykiwania zależności. Aby na przykład pobrać client z usługi:

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

Konfiguracja

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

Korzystanie z dostawców konfiguracji

Integracja .NET AspireAzure Table Storage obsługuje Microsoft.Extensions.Configuration. Przy użyciu klucza AzureDataTablesSettings ładuje TableClientOptions i Aspire:Azure:Data:Tables z konfiguracji. Poniższy fragment kodu to przykład pliku appsettings.json, który konfiguruje niektóre opcje:

{
  "Aspire": {
    "Azure": {
      "Data": {
        "Tables": {
          "ServiceUri": "YOUR_URI",
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "EnableTenantDiscovery": true
          }
        }
      }
    }
  }
}

Aby uzyskać pełny schemat integracji tabel danych AzureclientJSON, zobacz Aspire.Azure. Data.Tables/ConfigurationSchema.json.

Używanie delegatów wbudowanych

Możesz również przekazać delegata Action<AzureDataTablesSettings> configureSettings, aby skonfigurować niektóre lub wszystkie opcje bezpośrednio, na przykład w celu skonfigurowania ServiceUri:

builder.AddAzureTableClient(
    "tables",
    settings => settings.DisableHealthChecks = true);

Można również skonfigurować TableClientOptions przy użyciu delegata Action<IAzureClientBuilder<TableServiceClient, TableClientOptions>> configureClientBuilder, drugiego parametru metody AddAzureTableClient. Aby na przykład ustawić identyfikator TableServiceClient w celu zidentyfikowania client:

builder.AddAzureTableClient(
    "tables",
    configureClientBuilder: clientBuilder =>
        clientBuilder.ConfigureOptions(
            options => options.EnableTenantDiscovery = true));

Client kontrole kondycji integracji

Domyślnie integracje .NET.NET Aspire umożliwiają kontrole zdrowia dla wszystkich usług. Aby uzyskać więcej informacji, zobacz omówienie integracji .NET.NET Aspire.

Integracja tabel danych .NET AspireAzure:

Dodaje sprawdzanie kondycji, kiedy AzureDataTablesSettings.DisableHealthChecks ma false, co powoduje próbę nawiązania połączenia z Azure Table Storage.
Integruje się z punktem końcowym HTTP /health, który określa, że wszystkie zarejestrowane testy stanu muszą być zaliczone, aby aplikacja mogła być uznana za gotową do akceptowania ruchu.

Obserwowanie i telemetria

.NET .NET Aspire integracje automatycznie konfigurują ustawienia logowania, śledzenia i pomiarów, 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 z tabelami danych korzysta z następujących kategorii dzienników:

Azure.Core
Azure.Identity

Śledzenie

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

Azure.Data.Tables.TableServiceClient

Metryki

Integracja tabel danych .NET AspireAzure obecnie domyślnie nie obsługuje metryk z powodu ograniczeń pakietu Azure SDK.

Udostępnij za pośrednictwem