Integratie van .NET AspireAzure gegevenstabellen

Artikel
12/15/2024

omvat:hostingintegratie en Client integratie

Azure Table Storage is een service voor het opslaan van gestructureerde NoSQL-gegevens. Met de integratie van .NET AspireAzure gegevenstabellen kunt u verbinding maken met bestaande Azure Table Storage exemplaren of nieuwe exemplaren maken vanuit .NET toepassingen.

Hostingintegratie

De .NET.NET AspireAzure Storage hosting integreert en modelleert de verschillende opslagbronnen als de volgende typen:

AzureStorageResource: vertegenwoordigt een Azure Storage-resource.
AzureStorageEmulatorResource: vertegenwoordigt een Azure Storage Emulator-resource (Azurite).
AzureBlobStorageResource: vertegenwoordigt een Azure Blob Storage-resource.
AzureQueueStorageResource: vertegenwoordigt een Azure Queue Storage-resource.
AzureTableStorageResource: vertegenwoordigt een Azure tabelopslaghulpmiddel.

Als u toegang wilt krijgen tot deze typen en API's om ze uit te drukken, voegt u het 📦Aspire.Hosting.Azure.Storage NuGet-pakket toe in het app-host project.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.Storage

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

Zie dotnet pakket toevoegen of Pakketafhankelijkheden beheren in .NET toepassingenvoor meer informatie.

Azure Storage-resource toevoegen

Roep in uw app-hostproject AddAzureStorage aan om een Azure Storage-resourcebouwer toe te voegen en te retourneren.

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

Wanneer u een AzureStorageResource toevoegt aan de app-host, worden er andere nuttige API's weergegeven om Azure Blob-, Queue- en Table Storage-resources toe te voegen. Met andere woorden, u moet een AzureStorageResource toevoegen voordat u een van de andere opslagbronnen toevoegt.

Belangrijk

Wanneer u AddAzureStorageaanroept, wordt impliciet AddAzureProvisioningaangeroepen. Hiermee wordt ondersteuning toegevoegd voor het dynamisch genereren van Azure resources tijdens het opstarten van de app. De app moet het juiste abonnement en de juiste locatie configureren. Zie Lokale inrichting: Configuratievoor meer informatie.

Gegenereerde voorziening Bicep

Als u nieuw bent met Bicep, het is een domeinspecifieke taal voor het definiëren van Azure-bronnen. Met .NET.NET Aspirehoeft u bicep niet handmatig te schrijven, in plaats daarvan genereren de inrichtings-API's Bicep voor u. Wanneer u uw app publiceert, wordt de gegenereerde Bicep samen met het manifestbestand geleverd. Wanneer u een Azure Storage-resource toevoegt, wordt de volgende Bicep gegenereerd:

wisselknop 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

De voorgaande Bicep is een module die een Azure Storage-account in richt met de volgende standaardwaarden:

kind: het type opslagaccount. De standaardwaarde is StorageV2.
sku: de SKU van het opslagaccount. De standaardwaarde is Standard_GRS.
properties: de eigenschappen van het opslagaccount:
- accessTier: de toegangslaag van het opslagaccount. De standaardwaarde is Hot.
- allowSharedKeyAccess: een Booleaanse waarde die aangeeft of het opslagaccount toestaat dat aanvragen worden geautoriseerd met de toegangssleutel voor het account. De standaardwaarde is false.
- minimumTlsVersion: de minimaal ondersteunde TLS-versie voor het opslagaccount. De standaardwaarde is TLS1_2.
- networkAcls: de netwerk-ACL's voor het opslagaccount. De standaardwaarde is { defaultAction: 'Allow' }.

Naast het opslagaccount wordt ook een blobcontainer ingericht.

De volgende roltoewijzingen worden toegevoegd aan het opslagaccount om uw toepassing toegang te verlenen. Zie de ingebouwde ingebouwde rollen voor Azure op rollen gebaseerd toegangsbeheer (Azure RBAC) voor meer informatie:

Rol/id	Beschrijving
Inzender voor opslagblobgegevens `ba92f5b4-2d11-453d-a403-e96b0029c9fe`	Lees-, schrijf- en verwijder Azure Storage-containers en -blobs.
Inzender voor opslagtabelgegevens `0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3`	Lees-, schrijf- en verwijder Azure Storage-tabellen en -entiteiten.
Inzender voor opslagwachtrijgegevens `974c5e8b-45b9-4653-ba55-5f855dd0fb88`	Lees-, schrijf- en verwijder Azure Storage-wachtrijen en wachtrijberichten.

De gegenereerde Bicep is een uitgangspunt en kan worden aangepast aan uw specifieke vereisten.

Voorzieningeninfrastructuur aanpassen

Alle .NET AspireAzure resources zijn subklassen van het AzureProvisioningResource type. Met dit type kunt u de gegenereerde Bicep aanpassen doordat het een vloeiende API biedt om de Azure resources te configureren, door gebruik te maken van de ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API. U kunt bijvoorbeeld de kind, sku, propertiesen meer configureren. In het volgende voorbeeld ziet u hoe u de Azure Storage-resource aanpast:

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");
    });

De voorgaande code:

Koppelt een aanroep naar de ConfigureInfrastructure-API:
- De parameter infra is een exemplaar van het AzureResourceInfrastructure type.
- De voorzienbare resources worden opgehaald door middel van de GetProvisionableResources() methode.
- De enkele StorageAccount wordt opgehaald.
- De StorageAccount.AccessTier is toegewezen aan StorageAccountAccessTier.Cool.
- De StorageAccount.Sku wordt toegewezen aan een nieuwe StorageSku met een Name van PremiumZrs.
- Er wordt een tag toegevoegd aan het opslagaccount met een sleutel van ExampleKey en een waarde van Example value.

Er zijn nog veel meer configuratieopties beschikbaar om de Azure Storage-resource aan te passen. Zie Azure.Provisioning.Storagevoor meer informatie.

Verbinding maken met een bestaand Azure Storage-account

Mogelijk hebt u een bestaand Azure Storage-account waarmee u verbinding wilt maken. In plaats van een nieuwe Azure Storage-resource weer te geven, kunt u een verbindingsreeks toevoegen aan de app-host. Als u een verbinding wilt toevoegen aan een bestaand Azure Storage-account, roept u de methode AddConnectionString aan:

var builder = DistributedApplication.CreateBuilder(args);

var blobs = builder.AddConnectionString("blobs");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(blobs);

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

Notitie

Verbindingsreeksen worden gebruikt om een breed scala aan verbindingsgegevens weer te geven, waaronder databaseverbindingen, berichtbrokers, eindpunt-URI's en andere services. In .NET.NET Aspire nomenclatuur wordt de term "verbindingsreeks" gebruikt om alle soorten verbindingsgegevens weer te geven.

De verbindingsreeks is geconfigureerd in de configuratie van de app-host, meestal onder gebruikersgeheimen, onder de sectie ConnectionStrings. De app-host injecteert deze verbindingsreeks als een omgevingsvariabele in alle afhankelijke resources, bijvoorbeeld:

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

De afhankelijke resource heeft toegang tot de geïnjecteerde verbindingsreeks door de methode GetConnectionString aan te roepen en de verbindingsnaam door te geven als de parameter, in dit geval "blobs". De GetConnectionString-API is een afkorting voor IConfiguration.GetSection("ConnectionStrings")[name].

Resource voor Azure Storage-emulator toevoegen

Als u een Azure Storage-emulatorresource wilt toevoegen, koppelt u een aanroep op een IResourceBuilder<AzureStorageResource> aan de RunAsEmulator-API:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Wanneer u RunAsEmulatoraanroept, worden uw opslagbronnen geconfigureerd voor lokaal uitvoeren met behulp van een emulator. De emulator in dit geval is Azurite. De opensource-emulator Van Azurite biedt een gratis lokale omgeving voor het testen van uw Azure Blob-, Queue Storage- en Table Storage-apps en het is een perfecte aanvulling op de .NET AspireAzure hostingintegratie. Azurite is niet geïnstalleerd, maar is toegankelijk voor .NET.NET Aspire als container. Wanneer u een container toevoegt aan de app-host, zoals wordt getoond in het vorige voorbeeld met de afbeelding mcr.microsoft.com/azure-storage/azurite, wordt de container gemaakt en gestart wanneer de app-host wordt gestart. Zie levenscyclus van containerresourcesvoor meer informatie.

Azurite-container configureren

Er zijn verschillende configuraties beschikbaar voor containerresources. U kunt bijvoorbeeld de poorten van de container, omgevingsvariabelen, de levensduuren meer configureren.

Azurite-containerpoorten configureren

De Azurite-container stelt standaard, bij configuratie door .NET.NET Aspire, de volgende eindpunten bloot:

Eindpunt	Containerpoort	Hostpoort
`blob`	10.000	dynamisch
`queue`	10001	dynamisch
`table`	10002	dynamisch

De poort waarop ze luisteren, is standaard dynamisch. Wanneer de container wordt gestart, worden de poorten toegewezen aan een willekeurige poort op de hostcomputer. Als u de eindpuntpoorten wilt configureren, rijg dan aanroepen van de containerresourcebouwer zoals geleverd door de RunAsEmulator-methode aaneen, zoals wordt weergegeven in het volgende voorbeeld:

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

De voorgaande code configureert de bestaande blob, queueen table eindpunten van de Azurite-container om respectievelijk te luisteren op poorten 27000, 27001en 27002. De poorten van de Azurite-container worden toegewezen aan de hostpoorten, zoals wordt weergegeven in de volgende tabel:

Eindpuntnaam	Poorttoewijzing (`container:host`)
`blob`	`10000:27000`
`queue`	`10001:27001`
`table`	`10002:27002`

Azurite-container configureren met een permanente levensduur

Als u de Azurite-container met een permanente levensduur wilt configureren, roept u de methode WithLifetime op de Resource van de Azurite-container aan en geeft u ContainerLifetime.Persistentdoor:

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage").RunAsEmulator(
                     azurite =>
                     {
                         azurite.WithLifetime(ContainerLifetime.Persistent);
                     });

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

Zie Levensduur van containerresourcesvoor meer informatie.

Azurite-container configureren met gegevensvolume

Als u een gegevensvolume wilt toevoegen aan de resource van de Azure Storage-emulator, roept u de WithDataVolume methode aan op de resource van de Azure Storage-emulator:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Het gegevensvolume wordt gebruikt om de Azurite-gegevens buiten de levenscyclus van de container te behouden. Het gegevensvolume wordt gekoppeld aan het /data pad in de Azure-container en wanneer er geen name parameter wordt opgegeven, wordt de naam opgemaakt als .azurite/{resource name}. Voor meer informatie over gegevensvolumes en details over waarom ze de voorkeur hebben boven bind mounts, zie Docker docs: Volumes.

Azurite-container configureren met gegevenskoppeling

Als u een koppeling voor gegevensbinding wilt toevoegen aan de resource van de Azure Storage-emulator, roept u de WithDataBindMount methode aan:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Belangrijk

Gegevens koppelen beperkte functionaliteit hebben in vergelijking met volumes, die betere prestaties, draagbaarheid en beveiliging bieden, waardoor ze geschikter zijn voor productieomgevingen. Bind mounts bieden echter directe toegang tot en wijziging van bestanden op het hostsysteem, wat ideaal is voor ontwikkeling en testen waarbij wijzigingen in real-time nodig zijn.

Gegevenskoppelpunten vertrouwen op het bestandssysteem van de hostmachine om de Azurite-gegevens te behouden bij het opnieuw opstarten van de container. De koppeling van de gegevensbinding wordt gekoppeld aan het ../Azurite/Data pad op de hostcomputer ten opzichte van de app-hostmap (IDistributedApplicationBuilder.AppHostDirectory) in de Azure-container. Zie Docker docs: Bindingskoppelingenvoor meer informatie over koppelingskoppelingen voor gegevens.

Verbinding maken met opslagbronnen

Wanneer de .NET.NET Aspire app-host wordt uitgevoerd, kunnen de opslagbronnen worden geopend door externe hulpprogramma's, zoals de Azure Storage Explorer-. Als uw opslagresource lokaal wordt uitgevoerd met behulp van Azurite, wordt deze automatisch opgehaald door de Azure Storage Explorer.

Notitie

De Azure Storage Explorer detecteert Opslagbronnen van Azurite, ervan uitgaande dat de standaardpoorten worden gebruikt. Als u de Azurite-container geconfigureerd voor het gebruik van verschillende poorten, moet u de Azure Storage Explorer configureren om verbinding te maken met de juiste poorten.

Voer de volgende stappen uit om vanuit Azure Storage Explorer verbinding te maken met de opslagresource:

Voer de .NET.NET Aspire-app-host uit.
Open de Azure Opslagverkenner.
Bekijk het deelvenster Explorer.
Selecteer de link Alles vernieuwen om de lijst met opslagaccounts te vernieuwen.
Vouw het knooppunt Emulator & Gekoppeld uit.
Vouw het knooppunt Opslagaccounts uit.
U zou een opslagaccount moeten zien met de naam van uw resource als voorvoegsel.

U kunt het opslagaccount en de inhoud ervan verkennen met behulp van de Azure Storage Explorer. Zie Azurevoor meer informatie over het gebruik van de Storage Explorer.

Azure Table Storage-resource toevoegen

Registreer de Azure Table Storage-integratie in uw app-hostproject door een aanroep naar AddTables te koppelen aan het IResourceBuilder<IAzureStorageResource>-exemplaar dat door AddAzureStoragewordt geretourneerd. In het volgende voorbeeld ziet u hoe u een Azure Table Storage resource met de naam storage en een tabelresource met de naam tablestoevoegt:

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

De voorgaande code:

Hiermee wordt een Azure Storage-resource met de naam storagetoegevoegd.
Hiermee voegt u een tabelopslagresource met de naam tables toe aan de opslagresource.
Voegt de storage resource toe aan de ExampleProject en wacht tot deze gereed is voordat het project wordt gestart.

Gezondheidscontroles voor hostingintegratie

De integratie van Azure Storage-hosting voegt automatisch een statuscontrole toe voor de opslagresource. Deze wordt alleen toegevoegd wanneer het als een emulator draait en controleert of de Azurite-container draait en of er een verbinding tot stand kan worden gebracht. De hostingintegratie is afhankelijk van de 📦 AspNetCore.HealthChecks.Azure. Storage.Blobs NuGet-pakket.

integratie van Client

Installeer de .NET AspireAzureom aan de slag te gaan met de integratie van client📦 gegevenstabellen Aspire.Azure. Data.Tables NuGet-pakket in het clientverbruikende project, dat wil gezegd, het project voor de toepassing die gebruikmaakt van de Azure Gegevenstabellen client. De integratie van Azure gegevenstabellen client registreert een TableServiceClient exemplaar dat u kunt gebruiken om met Azure Table Storagete communiceren.

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Data.Tables

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

Azure Table Storage client toevoegen

Roep in het Program.cs-bestand van uw project dat clientverbruikt, de AddAzureTableClient-extensiemethode aan op elke IHostApplicationBuilder om een TableServiceClient te registreren voor gebruik via de afhankelijkheidsinjectiecontainer. De methode gebruikt een verbindingsnaamparameter.

builder.AddAzureTableClient("tables");

Vervolgens kunt u het TableServiceClient exemplaar ophalen met behulp van afhankelijkheidsinjectie. Bijvoorbeeld om de client op te halen van een service:

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

Configuratie

De .NET AspireAzure Table Storage-integratie biedt meerdere opties voor het configureren van de TableServiceClient op basis van de vereisten en conventies van uw project.

Configuratieproviders gebruiken

De .NET AspireAzure Table Storage-integratie ondersteunt Microsoft.Extensions.Configuration. Hiermee worden de AzureDataTablesSettings en TableClientOptions vanuit de configuratie geladen met behulp van de Aspire:Azure:Data:Tables-sleutel. Het volgende codefragment is een voorbeeld van een appsettings.json-bestand waarmee een aantal van de opties wordt geconfigureerd:

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

Zie voor het volledige integratieschema van de data tabellen AzureclientJSONAspire.Azure. Data.Tables/ConfigurationSchema.json.

Inline gedelegeerden gebruiken

U kunt de Action<AzureDataTablesSettings> configureSettings gedelegeerde ook doorgeven om bepaalde of alle opties inline in te stellen, bijvoorbeeld om de ServiceUrite configureren:

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

U kunt de TableClientOptions ook instellen met de Action<IAzureClientBuilder<TableServiceClient, TableClientOptions>> configureClientBuilder delegate, de tweede parameter van de AddAzureTableClient-methode. Als u bijvoorbeeld de TableServiceClient-id wilt instellen om de clientte identificeren:

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

gezondheidscontroles voor Client-integratie

Standaard kunnen .NET.NET Aspire integraties statuscontroles voor alle services inschakelen. Zie .NET.NET Aspire overzicht van integratiesvoor meer informatie.

De integratie van .NET AspireAzure gegevenstabellen:

Hiermee wordt de gezondheidscontrole toegevoegd wanneer AzureDataTablesSettings.DisableHealthChecksfalseis, waarmee geprobeerd wordt verbinding te maken met de Azure Table Storage.
Kan worden geïntegreerd met het /health HTTP-eindpunt, waarin is gespecificeerd dat alle geregistreerde gezondheidscontroles moeten slagen voordat de app als gereed wordt beschouwd om verkeer te accepteren.

Waarneembaarheid en telemetrie

.NET .NET Aspire integraties stellen automatisch configuraties voor logging, tracering en metrieken in, die ook wel bekend staan als de pijlers van waarneembaarheid. Zie .NET.NET Aspire overzicht van integratieintegratiesvoor meer informatie over de waarneembaarheid en telemetrie van integraties. Afhankelijk van de back-upservice ondersteunen sommige integraties mogelijk slechts enkele van deze functies. Sommige integraties ondersteunen bijvoorbeeld logboekregistratie en tracering, maar geen metrische gegevens. Telemetriefuncties kunnen ook worden uitgeschakeld met behulp van de technieken die worden weergegeven in de sectie Configuratie.

Loggen

De integratie van .NET AspireAzure gegevenstabellen maakt gebruik van de volgende logboekcategorieën:

Azure.Core
Azure.Identity

Tracering

De integratie van .NET AspireAzure gegevenstabellen verzendt de volgende traceringsactiviteiten met behulp van OpenTelemetry:

Azure.Data.Tables.TableServiceClient

Statistieken

De integratie van .NET AspireAzure gegevenstabellen biedt momenteel geen ondersteuning voor metriek vanwege beperkingen met de Azure SDK.

Delen via