Übersicht über .NET AspireAzure Integrationen

Azure ist die beliebteste Cloudplattform zum Erstellen und Bereitstellen von .NET Anwendungen. Das Azure SDK für .NET ermöglicht eine einfache Verwaltung und Verwendung von Azure-Diensten. .NET Aspire bietet eine Reihe von Integrationen mit Azure Diensten, in denen Sie neue Ressourcen hinzufügen oder eine Verbindung mit vorhandenen herstellen können. In diesem Artikel werden einige allgemeine Aspekte aller Azure Integrationen in .NET Aspire erläutert und soll Ihnen helfen, zu verstehen, wie Sie diese verwenden können.

Azure Ressourcen hinzufügen

Alle .NET AspireAzure Hosting-Integrationen machen Azure Ressourcen verfügbar und werden nach der Konvention mithilfe von AddAzure* APIs hinzugefügt. Wenn Sie diese Ressourcen ihrem .NET Aspire App-Host hinzufügen, stellen sie einen Azure Dienst dar. Die AddAzure*-API gibt eine IResourceBuilder<T> zurück, wobei T der Typ der Azure-Ressource ist. Diese IResourceBuilder<T>-Schnittstellen (Generator) bieten eine flüssige API, mit der Sie die unterliegende Azure-Ressource innerhalb des -App-Modellskonfigurieren können. Es gibt APIs zum Hinzufügen neuer Azure Ressourcen, zum Markieren von Ressourcen als vorhanden und zum Konfigurieren des Verhaltens der Ressourcen in verschiedenen Ausführungskontexten.

Typische Entwicklererfahrung

Wenn Ihr .NET Aspire App-Host Azure Ressourcen enthält und Sie ihn lokal ausführen (also eine übliche Entwicklererfahrung mit F5 oder dotnet run), werden die Azure Ressourcen in Ihrem Azure Abonnement bereitgestellt. Auf diese Weise können Sie als Entwickler lokal im Kontext Ihres App-Hosts gegen sie debuggen.

.NET .NET Aspire zielt darauf ab, die Kosten zu minimieren, indem es die Lagereinheit (SKU) Basic oder Standard standardmäßig für seine Azure Integrationen verwendet. Während diese sinnvollen Standardwerte bereitgestellt werden, können Sie die Ressourcen an Ihre Anforderungen anpassen. Darüber hinaus unterstützen einige Integrationen Emulatoren oder Container, die für die lokale Entwicklung, Tests und Debugging nützlich sind. Wenn Sie Ihre App lokal ausführen, verwenden die Azure Ressourcen standardmäßig den tatsächlichen Azure Dienst. Sie können sie jedoch so konfigurieren, dass lokale Emulatoren oder Container verwendet werden, um Kosten zu vermeiden, die mit dem tatsächlichen Azure Dienst während der lokalen Entwicklung verbunden sind.

Lokale Emulatoren

Einige Azure Dienste können emuliert werden, um lokal ausgeführt zu werden. Derzeit unterstützt .NET Aspire die folgenden Azure Emulatoren:

Um Ihre Azure-Ressourcen die lokalen Emulatoren verwenden zu lassen, verketten Sie einen Aufruf der RunAsEmulator-Methode an den Azure-Ressourcen-Builder. Mit dieser Methode wird die Azure Ressource so konfiguriert, dass der lokale Emulator anstelle des tatsächlichen Azure Diensts verwendet wird.

Lokale Container

Einige Azure Ressourcen können lokal mithilfe von Open Source- oder lokalen Containern ersetzt werden. Um eine Azure-Ressource lokal in einem Container zu ersetzen, verketten Sie einen Aufruf der RunAsContainer-Methode am Azure-Ressource-Builder. Mit dieser Methode wird die Azure Ressource so konfiguriert, dass eine containerisierte Version des Diensts für lokale Entwicklung und Tests anstelle des tatsächlichen Azure Diensts verwendet wird.

Derzeit unterstützt .NET Aspire die folgenden Azure Dienste als Container:

Grundlegendes zu Azure Integrations-APIs

.NET .NET Aspire's Stärke liegt in der Fähigkeit, einen erstaunlichen Entwickler-Inner-Loop zu bieten. Die Azure-Integrationen sind ebenfalls nicht anders. Sie stellen eine Reihe allgemeiner APIs und Muster bereit, die für alle Azure Ressourcen freigegeben werden. Diese APIs und Muster sind so konzipiert, dass die Arbeit mit Azure Ressourcen auf einheitliche Weise erleichtert wird.

Im vorhergehenden Abschnitt über Container haben Sie erfahren, wie Sie Azure-Dienste lokal in Containern ausführen. Wenn Sie mit .NET.NET Aspirevertraut sind, fragen Sie sich vielleicht, wie sich das Aufrufen von AddAzureRedis("redis").RunAsContainer(), um einen lokalen docker.io/library/redis-Container zu erhalten, von AddRedis("redis")unterscheidet, da beide zu demselben lokalen Container führen.

Die Antwort lautet, dass es keinen Unterschied bei der lokalen Ausführung gibt. Wenn sie veröffentlicht werden, erhalten Sie jedoch unterschiedliche Ressourcen:

Das Gleiche gilt für SQL- und PostgreSQL-Dienste:

Weitere Informationen zum Unterschied zwischen Ausführungs- und Veröffentlichungsmodi finden Sie unter .NET.NET Aspire App-Host: Ausführungskontext.

APIs zum Ausdrücken von Azure Ressourcen in verschiedenen Modi

Der verteilte Anwendungsentwickler, Teil des App-Hosts, nutzt das Baukastenmuster, um Ressourcen dem AddAzure* hinzuzufügen . Entwickler können diese Ressourcen konfigurieren und ihr Verhalten in verschiedenen Ausführungskontexten definieren. Azure Hostingintegrationen stellen APIs bereit, um anzugeben, wie diese Ressourcen "veröffentlicht" und "ausführen" werden sollen.

Wenn der App-Host ausgeführt wird, wird der Ausführungskontext verwendet, um zu bestimmen, ob sich der App-Host im Run- oder Publish Modus befindet. Die Benennungskonventionen für diese APIs geben die beabsichtigte Aktion für die Ressource an.

In der folgenden Tabelle sind die Benennungskonventionen zusammengefasst, die verwendet werden, um Azure Ressourcen auszudrücken:

Weitere Informationen zu Ausführungsmodi finden Sie unter Ausführungskontext.

Allgemeine Ausführungsmodus-API-Anwendungsfälle

Verwenden Sie RunAsExisting, wenn Sie während der Laufzeit dynamisch mit einer vorhandenen Ressource interagieren müssen, ohne sie bereitstellen oder aktualisieren zu müssen. Verwenden Sie PublishAsExisting, wenn Sie vorhandene Ressourcen als Teil einer Bereitstellungskonfiguration deklarieren, um sicherzustellen, dass die richtigen Bereiche und Berechtigungen angewendet werden. Verwenden Sie schließlich AsExisting<T>(IResourceBuilder<T>, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>), wenn Sie vorhandene Ressourcen in beiden Konfigurationen deklarieren, mit der Anforderung, die Verweise zu parametrisieren.

Sie können abfragen, ob eine Ressource als vorhandene Ressource gekennzeichnet ist, indem Sie die IsExisting(IResource) Erweiterungsmethode für die IResourceaufrufen. Weitere Informationen finden Sie unter Verwenden vorhandener Azure Ressourcen.

Verwenden Sie vorhandene Azure-Ressourcen

.NET Aspire bietet Unterstützung für das Verweisen auf vorhandene Azure-Ressourcen. Sie markieren eine vorhandene Ressource über die APIs PublishAsExisting, RunAsExistingund AsExisting. Mit diesen APIs können Entwickler auf bereits bereitgestellte Azure Ressourcen verweisen, diese konfigurieren und geeignete Bereitstellungsmanifeste mithilfe von Bicep-Vorlagen generieren.

Vorhandene Ressourcen, auf die mit diesen APIs verwiesen wird, können mit Rollenzuweisungen und anderen Anpassungen erweitert werden, die mit .NET.NET AspireInfrastruktur als Codefunktionenverfügbar sind. Diese APIs sind auf Azure Ressourcen beschränkt, die mit Bicep-Vorlagen bereitgestellt werden können.

Konfigurieren vorhandener Azure Ressourcen für den Ausführungsmodus

Die RunAsExisting-Methode wird verwendet, wenn eine verteilte Anwendung im Modus "Ausführen" ausgeführt wird. In diesem Modus wird davon ausgegangen, dass die referenzierte Azure Ressource bereits vorhanden ist und während der Ausführung integriert wird, ohne die Ressource bereitzustellen. Um eine Azure Ressource als vorhanden zu kennzeichnen, rufen Sie die RunAsExisting-Methode für den Ressourcen-Generator auf. Betrachten Sie das folgende Beispiel:

var builder = DistributedApplication.CreateBuilder();

var existingServiceBusName = builder.AddParameter("existingServiceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("existingServiceBusResourceGroup");

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .RunAsExisting(existingServiceBusName, existingServiceBusResourceGroup);

serviceBus.AddServiceBusQueue("queue");

Der vorangehende Code:

• Erstellt eine neue builder-Instanz.
• Fügt dem Generator einen Parameter namens existingServiceBusName hinzu.
• Fügt dem Generator eine Azure Service Bus Ressource namens messaging hinzu.
• Ruft die RunAsExisting-Methode für den serviceBus Ressourcen-Generator auf, und übergibt den existingServiceBusName Parameter , alternativ können Sie die string Parameterüberladung verwenden.
• Fügt der queue Ressource eine Warteschlange mit dem Namen serviceBus hinzu.

Standardmäßig wird angenommen, dass sich der Parameterverweis "Service Bus" in derselben Azure Ressourcengruppe befindet. Wenn es sich jedoch in einer anderen Ressourcengruppe befindet, können Sie die Ressourcengruppe explizit als Parameter übergeben, um die entsprechende Ressourcengruppierung korrekt anzugeben.

Konfigurieren vorhandener Azure-Ressourcen für den Veröffentlichungsmodus

Die PublishAsExisting-Methode wird im Modus "veröffentlichen" verwendet, wenn die Absicht besteht, eine bereits vorhandene Azure Ressource während des Veröffentlichungsmodus zu deklarieren und darauf zu verweisen. Diese API erleichtert die Erstellung von Manifesten und Vorlagen, die Ressourcendefinitionen enthalten, die vorhandenen Ressourcen in Bicep zugeordnet sind.

Wenn Sie eine Azure Ressource im Modus "veröffentlichen" als vorhanden markieren möchten, rufen Sie die PublishAsExisting-Methode für den Ressourcen-Generator auf. Betrachten Sie das folgende Beispiel:

var builder = DistributedApplication.CreateBuilder();

var existingServiceBusName = builder.AddParameter("existingServiceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("existingServiceBusResourceGroup");

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .PublishAsExisting(existingServiceBusName, existingServiceBusResourceGroup);

serviceBus.AddServiceBusQueue("queue");

Der vorangehende Code:

• Erstellt eine neue builder-Instanz.
• Fügt dem Generator einen Parameter namens existingServiceBusName hinzu.
• Fügt dem Generator eine Azure Service Bus Ressource namens messaging hinzu.
• Ruft die PublishAsExisting-Methode für den serviceBus Ressourcen-Generator auf, und übergibt den existingServiceBusName Parameter , alternativ können Sie die string Parameterüberladung verwenden.
• Fügt der queue Ressource eine Warteschlange mit dem Namen serviceBus hinzu.

Nachdem der App-Host im Veröffentlichungsmodus ausgeführt wurde, enthält die generierte Manifestdatei den existingResourceName Parameter, der verwendet werden kann, um auf die vorhandene Azure Ressource zu verweisen. Betrachten Sie den folgenden generierten Teilausschnitt der Manifestdatei:

"messaging": {
  "type": "azure.bicep.v0",
  "connectionString": "{messaging.outputs.serviceBusEndpoint}",
  "path": "messaging.module.bicep",
  "params": {
    "existingServiceBusName": "{existingServiceBusName.value}",
    "principalType": "",
    "principalId": ""
  }
},
"queue": {
  "type": "value.v0",
  "connectionString": "{messaging.outputs.serviceBusEndpoint}"
}

Weitere Informationen zur Manifestdatei finden Sie unter .NET.NET Aspire Manifestformat für Bereitstellungstool-Generatoren.

Darüber hinaus enthält die generierte Bicep-Vorlage den existingResourceName-Parameter, der verwendet werden kann, um auf die vorhandene Azure-Ressource zu verweisen. Betrachten Sie die folgende generierte Bicep-Vorlage:

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

param existingServiceBusName string

param principalType string

param principalId string

resource messaging 'Microsoft.ServiceBus/namespaces@2024-01-01' existing = {
  name: existingServiceBusName
}

resource messaging_AzureServiceBusDataOwner 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(messaging.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '090c5cfd-751d-490a-894a-3ce6f1109419'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '090c5cfd-751d-490a-894a-3ce6f1109419')
    principalType: principalType
  }
  scope: messaging
}

resource queue 'Microsoft.ServiceBus/namespaces/queues@2024-01-01' = {
  name: 'queue'
  parent: messaging
}

output serviceBusEndpoint string = messaging.properties.serviceBusEndpoint

Weitere Informationen zu den generierten Bicep-Vorlagen finden Sie unter Infrastruktur als Code und andere Veröffentlichungs-APIsin Betracht ziehen.

Konfigurieren Sie vorhandene Azure Ressourcen in allen Modi

Die AsExisting<T>(IResourceBuilder<T>, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>)-Methode wird verwendet, wenn die verteilte Anwendung im Modus "ausführen" oder "veröffentlichen" ausgeführt wird. Da die AsExisting-Methode in beiden Szenarien ausgeführt wird, unterstützt sie nur einen parametrisierten Verweis auf den Ressourcennamen oder ressourcengruppennamen. Dieser Ansatz trägt dazu bei, die Verwendung derselben Ressource sowohl in Test- als auch in Produktionsumgebungen zu verhindern.

Um eine Azure Ressource als vorhanden zu kennzeichnen, rufen Sie die AsExisting-Methode für den Ressourcen-Generator auf. Betrachten Sie das folgende Beispiel:

var builder = DistributedApplication.CreateBuilder();

var existingServiceBusName = builder.AddParameter("existingServiceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("existingServiceBusResourceGroup");

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .AsExisting(existingServiceBusName, existingServiceBusResourceGroup);

serviceBus.AddServiceBusQueue("queue");

Der vorangehende Code:

• Erstellt eine neue builder-Instanz.
• Fügt dem Generator einen Parameter namens existingServiceBusName hinzu.
• Fügt dem Generator eine Azure Service Bus Ressource namens messaging hinzu.
• Ruft die AsExisting-Methode für den serviceBus Ressourcen-Generator auf, und übergibt den existingServiceBusName-Parameter.
• Fügt der queue Ressource eine Warteschlange mit dem Namen serviceBus hinzu.

Hinzufügen vorhandener Azure Ressourcen mit Verbindungszeichenfolgen

.NET .NET Aspire bietet die Möglichkeit, eine Verbindung zu vorhandenen Ressourcen herzustellen, einschließlich Azure Ressourcen. Das Ausdrücken von Verbindungszeichenfolgen ist nützlich, wenn Sie über vorhandene Azure Ressourcen verfügen, die Sie in Ihrer .NET Aspire-App verwenden möchten. Die AddConnectionString-API wird mit dem Ausführungskontext des App-Hosts verwendet, um dem App-Modell eine Verbindungszeichenfolge bedingt hinzuzufügen.

Sehen Sie sich das folgende Beispiel an, in dem Sie im Veröffentlichungsmodus eine Speicherressource Azure hinzufügen, während Sie im Ausführungsmodus eine Verbindungszeichenfolge zu einem vorhandenen Speicher Azure hinzufügen:

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureStorage("storage")
    : builder.AddConnectionString("storage");

builder.AddProject<Projects.Api>("api")
       .WithReference(storage);

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

Der vorangehende Code:

• Erstellt eine neue builder-Instanz.
• Fügt eine Azure Speicherressource namens storage im Modus "Veröffentlichen" hinzu.
• Fügt eine Verbindungszeichenfolge zu einem vorhandenen Azure-Speicher namens storage im Modus „Ausführen“ hinzu.
• Fügt dem Generator ein Projekt mit dem Namen api hinzu.
• Das api Projekt verweist unabhängig vom Modus auf die storage Ressource.

Das verwendenden API-Projekt verwendet die Verbindungszeichenfolgeninformationen ohne Wissen darüber, wie der App-Host sie konfiguriert hat. Im Modus "Veröffentlichen" fügt der Code eine neue Azure Speicherressource hinzu, die sich im Bereitstellungsmanifest entsprechend widerspiegelt. Wenn sich das System im Modus "Ausführen" befindet, entspricht die Verbindungszeichenfolge einem Konfigurationswert, der für die Hostanwendung sichtbar ist. Es wird davon ausgegangen, dass alle Rollenzuweisungen für die Zielressource konfiguriert sind. Dies bedeutet, dass Sie wahrscheinlich eine Umgebungsvariable oder einen geheimen Benutzerschlüssel konfigurieren, um die Verbindungszeichenfolge zu speichern. Die Konfiguration wird aus dem Konfigurationsschlüssel ConnectionStrings__storage (oder ConnectionStrings:storage) ermittelt. Diese Konfigurationswerte können angezeigt werden, wenn die App ausgeführt wird. Weitere Informationen finden Sie unter Ressourcendetails.

Im Gegensatz zu vorhandenen Ressourcen, die mit der ersten Klasse AsExisting-API-modelliert wurden, können vorhandene Ressourcen, die als Verbindungszeichenfolgen modelliert wurden, nicht mit zusätzlichen Rollenzuweisungen oder Infrastrukturanpassungen erweitert werden.

Als Azure Container-App veröffentlichen

mit .NET.NET Aspire können Sie primitive Ressourcen als Azure Container Appsveröffentlichen, eine serverlose Plattform, die die Infrastrukturverwaltung reduziert. Zu den unterstützten Ressourcentypen gehören:

• ContainerResource: Stellt einen angegebenen Container dar.
• ExecutableResource: Stellt einen angegebenen ausführbaren Prozess dar.
• ProjectResource: Stellt ein angegebenes .NET Projekt dar.

Verwenden Sie zum Veröffentlichen dieser Ressourcen die folgenden APIs:

• AzureContainerAppContainerExtensions.PublishAsAzureContainerApp<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure,ContainerApp>)
• AzureContainerAppExecutableExtensions.PublishAsAzureContainerApp<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure,ContainerApp>)
• AzureContainerAppProjectExtensions.PublishAsAzureContainerApp<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure,ContainerApp>)

Diese APIs konfigurieren die Ressource so, dass sie als Azure Container-App veröffentlicht wird, und rufen implizit AddAzureContainerAppsInfrastructure(IDistributedApplicationBuilder) auf, um die erforderliche Infrastruktur und Bicep-Dateien ihrem App-Host hinzuzufügen. Betrachten Sie beispielsweise den folgenden Code:

var builder = DistributedApplication.CreateBuilder();

var env = builder.AddParameter("env");

var api = builder.AddProject<Projects.AspireApi>("api")
                 .PublishAsAzureContainerApp<Projects.AspireApi>((infra, app) =>
                 {
                     app.Template.Containers[0].Value!.Env.Add(new ContainerAppEnvironmentVariable
                     {
                         Name = "Hello",
                         Value = env.AsProvisioningParameter(infra)
                     });
                 });

Der vorangehende Code:

• Erstellt eine neue builder-Instanz.
• Fügt dem Generator einen Parameter namens env hinzu.
• Fügt dem Generator ein Projekt mit dem Namen api hinzu.
• Ruft die PublishAsAzureContainerApp-Methode für den api Ressourcen-Generator auf und übergibt einen Lambda-Ausdruck, der die Azure Container-App-Infrastruktur konfiguriert, wobei infra die AzureResourceInfrastructure ist und app die ContainerAppist.
  • Fügt der Container-App mithilfe des env-Parameters eine Umgebungsvariable namens Hello hinzu.
  • Die AsProvisioningParameter-Methode wird verwendet, um env entweder als neue ProvisioningParameter in der Infrastruktur zu behandeln oder einen vorhandenen Bicep-Parameter wiederzuverwenden, wenn bereits ein Parameter mit demselben Namen vorhanden ist.

Weitere Informationen finden Sie unter ContainerApp und AsProvisioningParameter.

Infrastruktur als Code

Das SDK für stellt das .Provisioning NuGet-Paket und eine Suite von dienstspezifischen Bereitstellungspaketen zur Verfügung. Diese Azure Bereitstellungsbibliotheken erleichtern es, die Infrastruktur nativ in .NET anzugeben. Ihre APIs ermöglichen es Ihnen, objektorientierte Infrastruktur in C# zu schreiben, was zu Bicep führt. Bicep ist eine domänenspezifische Sprache (DSL) für die deklarative Bereitstellung der Azure Ressourcen.

Obwohl es möglich ist, Azure Ressourcen manuell bereitzustellen, vereinfacht .NET Aspire den Prozess, indem eine Reihe von APIs bereitgestellt wird, um Azure Ressourcen auszudrücken. Diese APIs sind als Erweiterungsmethoden in .NET AspireAzure Hostingbibliotheken verfügbar und erweitern die IDistributedApplicationBuilder-Schnittstelle. Wenn Sie Ihrem App-Host Azure Ressourcen hinzufügen, sorgen diese implizit für die entsprechende Bereitstellungsfunktionalität. Mit anderen Worten, Sie müssen keine Bereitstellungs-APIs direkt aufrufen.

Da das .NET Aspire Modelle die Ressourcen innerhalb von Azure Hostingintegrationen Azure modelliert, wird das Azure SDK verwendet, um diese Ressourcen bereitzustellen. Bicep-Dateien werden generiert, die die benötigten Azure Ressourcen definieren. Die generierten Bicep-Dateien werden zusammen mit der Manifestdatei ausgegeben, wenn Sie Ihre App veröffentlichen.

Es gibt verschiedene Möglichkeiten, die generierten Bicep-Dateien zu beeinflussen:

• Azure. Bereitstellungsanpassung:
  • Konfigurieren der Infrastruktur: Anpassen Azure Ressourceninfrastruktur.
  • Azure Infrastrukturhinzufügen: Fügen Sie Azure Infrastruktur manuell zu Ihrem Applikationshost hinzu.
• Verwenden Sie benutzerdefinierte Bicep-Vorlagen:
  • Referenz-Bicep-Dateien: Fügen Sie einen Verweis auf eine Bicep-Datei auf dem Datenträger hinzu.
  • Referenz-Bicep-Inline-: Fügen Sie eine Inline-Bicep-Vorlage hinzu.

Lokale Bereitstellung und Azure.Provisioning

Um eine Verwechslung von Begriffen zu vermeiden und zur Klärung des Begriffs "Bereitstellung" beizutragen, ist es wichtig, die Unterschiede zwischen lokaler Bereitstellung und Azure Bereitstellungzu verstehen.

• Lokale Bereitstellung:

  Standardmäßig wird die Azure-API implizit aufgerufen, wenn Sie eine der Azure-Hostintegrations-APIs aufrufen, um AddAzureProvisioning(IDistributedApplicationBuilder)-Ressourcen hinzuzufügen. Diese API registriert Dienste für Dependency Injection (DI) im Container, die verwendet werden, um Azure-Ressourcen bereitzustellen, wenn der App-Host gestartet wird. Dieses Konzept wird als lokale Bereitstellungbezeichnet. Weitere Informationen finden Sie unter Lokale Azure Bereitstellung.

• Azure.Provisioning:

  Azure.Provisioning bezieht sich auf das NuGet-Paket und ist eine Reihe von Bibliotheken, mit denen Sie C# zum Generieren von Bicep verwenden können. Die Azure Hostintegrationen in .NET Aspire verwenden diese Bibliotheken unter der Haube, um Bicep-Dateien zu generieren, die die benötigten Azure Ressourcen definieren. Weitere Informationen finden Sie unter Azure.Provisioning Anpassung.

Azure.Provisioning Anpassung

Alle .NET AspireAzure Hosting-Integrationen machen verschiedene Azure Ressourcen verfügbar, und sie sind alle Unterklassen des AzureProvisioningResource Typs, der selbst von AzureBicepResourceerbt. Dies ermöglicht Erweiterungen, die generisch typgeschränkt auf diesen Typ beschränkt sind, sodass eine Fluent-API die Infrastruktur nach Ihren Wünschen anpassen kann. Während .NET.NET Aspire Standardwerte bereitstellt, können Sie die generierte Bicep mithilfe dieser APIs beeinflussen.

Konfigurieren der Infrastruktur

Unabhängig von der Azure Ressource, mit der Sie arbeiten, führen Sie einen Aufruf der ConfigureInfrastructure Erweiterungsmethode durch, um die zugrunde liegende Infrastruktur zu konfigurieren. Mit dieser Methode können Sie die Infrastruktur der Azure Ressource anpassen, indem Sie einen configure Delegaten vom Typ Action<AzureResourceInfrastructure>übergeben. Der AzureResourceInfrastructure Typ ist eine Unterklasse der Azure.Provisioning.Infrastructure. Dieser Typ macht einen massiven API-Oberflächenbereich zum Konfigurieren der zugrunde liegenden Infrastruktur der Azure Ressource verfügbar.

Betrachten Sie das folgende Beispiel:

var sku = builder.AddParameter("storage-sku");

var storage = builder.AddAzureStorage("storage")
    .ConfigureInfrastructure(infra =>
    {
        var resources = infra.GetProvisionableResources();

        var storageAccount = resources.OfType<StorageAccount>().Single();

        storageAccount.Sku = new StorageSku
        {
            Name = sku.AsProvisioningParameter(infra)
        };
    });

Der vorangehende Code:

• Fügt einen Parameter namens storage-skuhinzu.
• Fügt den Speicher Azure mithilfe der API AddAzureStorage namens storage hinzu.
• Verkettet einen Aufruf an ConfigureInfrastructure, um die Azure Speicherinfrastruktur anzupassen:
  • Ruft die bereitstellbaren Ressourcen ab.
  • Filtert zu einem einzelnen StorageAccount.
  • Ordnet den Parameter storage-sku der Eigenschaft StorageAccount.Sku zu:
    • Einer neuen Instanz des StorageSku wird die Name-Eigenschaft mit dem Ergebnis der AsProvisioningParameter-API zugewiesen.

Dies veranschaulicht, dass ein externer Parameter in die Azure Storage-Infrastruktur fließt, was dazu führt, dass die generierte Bicep-Datei die gewünschte Konfiguration widerspiegelt.

Fügen Sie die Azure Infrastruktur hinzu

Nicht alle Azure Dienste werden als .NET Aspire Integrationen freigegeben. Auch wenn sie möglicherweise erst später zur Verfügung stehen, können Sie dennoch Dienste bereitstellen, die in Azure.Provisioning.*-Bibliotheken angeboten werden. Stellen Sie sich ein Szenario vor, in dem Sie über einen Arbeiterdienst verfügen, der für die Verwaltung eines Azure Container-Registers verantwortlich ist. Stellen Sie sich nun vor, dass ein App-Hostprojekt eine Abhängigkeit vom NuGet-Paket 📦Azure.Provisioning.ContainerRegistry nimmt.

Sie können die AddAzureInfrastructure-API verwenden, um Ihrer App-Host die Azure-Containerregistrierungs-Infrastruktur hinzuzufügen.

var acr = builder.AddAzureInfrastructure("acr", infra =>
{
    var registry = new ContainerRegistryService("acr")
    {
        Sku = new()
        {
            Name = ContainerRegistrySkuName.Standard
        },
    };
    infra.Add(registry);

    var output = new ProvisioningOutput("registryName", typeof(string))
    {
        Value = registry.Name
    };
    infra.Add(output);
});

builder.AddProject<Projects.WorkerService>("worker")
       .WithEnvironment(
            "ACR_REGISTRY_NAME",
            new BicepOutputReference("registryName", acr.Resource));

Der vorangehende Code:

• Ruft AddAzureInfrastructure mit dem Namen acrauf.
• Stellt einen configureInfrastructure Delegat zur Anpassung der Azure Containerregistrierungsinfrastruktur bereit.
  • Instanziiert eine ContainerRegistryService mit dem Namen acr und einer Standard-SKU.
  • Fügt den Azure Containerregistrierungsdienst zur Variable infra hinzu.
  • Instanziiert eine ProvisioningOutput mit dem Namen registryName, einem Typ von stringund einem Wert, der dem Namen der Azure Container-Registry entspricht.
  • Fügt die Ausgabe der infra Variablen hinzu.
• Fügt dem Generator ein Projekt mit dem Namen worker hinzu.
• Verkettet einen Aufruf an WithEnvironment, um die Umgebungsvariable ACR_REGISTRY_NAME im Projekt auf den Wert der Ausgabe registryName festzulegen.

Die Funktionalität veranschaulicht, wie Sie Ihrem App-Hostprojekt Azure Infrastruktur hinzufügen, auch wenn der Azure Dienst nicht direkt als .NET Aspire Integration verfügbar gemacht wird. Außerdem wird gezeigt, wie der Output der Azure Containerregistrierung in die Umgebung eines abhängigen Projekts überführt werden kann.

Betrachten Sie die resultierende Bicep-Datei:

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

resource acr 'Microsoft.ContainerRegistry/registries@2023-07-01' = {
  name: take('acr${uniqueString(resourceGroup().id)}', 50)
  location: location
  sku: {
    name: 'Standard'
  }
}

output registryName string = acr.name

Die Bicep-Datei spiegelt die gewünschte Konfiguration der Azure Container-Registry wider, wie von der AddAzureInfrastructure API definiert.

Benutzerdefinierte Bicep-Vorlagen verwenden

Wenn Sie auf Azure als gewünschten Cloudanbieter abzielen, können Sie Bicep verwenden, um Ihre Infrastruktur als Code zu definieren. Es zielt darauf ab, die Erstellungserfahrung mit einer saubereren Syntax drastisch zu vereinfachen und eine bessere Unterstützung für Modularität und Codewiederverwendung zu unterstützen.

Während .NET.NET Aspire eine Reihe vorgefertigter Bicep-Vorlagen bereitstellt, kann es vorkommen, dass Sie entweder die Vorlagen anpassen oder eigene erstellen möchten. In diesem Abschnitt werden die Konzepte und die entsprechenden APIs erläutert, mit denen Sie die Bicep-Vorlagen anpassen können.

Im Rahmen der Azure Bereitstellungsgeschichte für .NET Aspirebietet die Azure Developer CLI (azd) ein Verständnis für Ihr .NET Aspire-Projekt und die Möglichkeit, es auf Azurebereitzustellen. Die azd CLI verwendet die Bicep-Vorlagen, um die Anwendung für Azurebereitzustellen.

Installieren Sie das Aspire.Hosting.Azure-Paket

Wenn Sie auf Bicep-Dateien verweisen möchten, verwenden Sie möglicherweise keine der Azure Hosting-Integrationen. In diesem Fall können Sie weiterhin auf Bicep-Dateien verweisen, indem Sie das Aspire.Hosting.Azure-Paket installieren. Dieses Paket stellt APIs bereit, die notwendig sind, um Bicep-Dateien zu referenzieren und die Azure-Ressourcen anzupassen.

Um eine dieser Funktionen zu verwenden, muss das 📦Aspire.Hosting.Azure NuGet-Paket installiert sein.

dotnet add package Aspire.Hosting.Azure

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

Weitere Informationen finden Sie unter dotnet add package oder Paketabhängigkeiten in .NET Anwendungen verwalten.

Was sie von den Beispielen erwarten können

In allen Beispielen in diesem Abschnitt wird davon ausgegangen, dass Sie den Aspire.Hosting.Azure-Namespace verwenden. Darüber hinaus gehen die Beispiele davon aus, dass Sie über eine Instanz vom Typ IDistributedApplicationBuilder verfügen.

using Aspire.Hosting.Azure;

var builder = DistributedApplication.CreateBuilder(args);

// Examples go here...

builder.Build().Run();

Standardmäßig wird beim Aufruf einer der Bicep-bezogenen APIs auch ein Aufruf an AddAzureProvisioning ausgeführt, der die Unterstützung hinzufügt, um Azure-Ressourcen dynamisch während des Anwendungsstarts zu erstellen. Weitere Informationen finden Sie unter Lokale Bereitstellung und Azure.Provisioning.

Referenz-Bicep-Dateien

Stellen Sie sich vor, Sie haben eine Bicep-Vorlage in einer Datei namens storage.bicep, die ein Azure Speicherkonto bereitstellt.

param location string = resourceGroup().location
param storageAccountName string = 'toylaunch${uniqueString(resourceGroup().id)}'

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
  properties: {
    accessTier: 'Hot'
  }
}

Rufen Sie die AddBicepTemplate-Methode auf, um einen Verweis auf die Bicep-Datei auf dem Datenträger hinzuzufügen. Betrachten Sie das folgende Beispiel:

builder.AddBicepTemplate(
    name: "storage",
    bicepFile: "../infra/storage.bicep");

Der vorangehende Code fügt einen Verweis auf eine Bicep-Datei hinzu, die sich in ../infra/storage.bicepbefindet. Die Dateipfade sollten relativ zum App-Host Projekt sein. Diese Referenz führt zu einer AzureBicepResource, die der Ressourcenauflistung der Anwendung mit dem Namen "storage" hinzugefügt wird, und die API gibt eine IResourceBuilder<AzureBicepResource>-Instanz zurück, die verwendet werden kann, um die Ressource weiter zu konfigurieren.

Referenz Bicep inline

Obwohl eine Bicep-Datei auf dem Datenträger das am häufigsten verwendete Szenario ist, können Sie auch Bicep-Vorlagen inline hinzufügen. Inlinevorlagen können nützlich sein, wenn Sie eine Vorlage im Code definieren möchten oder wenn Sie die Vorlage dynamisch generieren möchten. Um eine Inline-Bicep-Vorlage hinzuzufügen, rufen Sie die AddBicepTemplateString-Methode mit der Bicep-Vorlage als string auf. Betrachten Sie das folgende Beispiel:

builder.AddBicepTemplateString(
        name: "ai",
        bicepContent: """
        @description('That name is the name of our application.')
        param cognitiveServiceName string = 'CognitiveService-${uniqueString(resourceGroup().id)}'

        @description('Location for all resources.')
        param location string = resourceGroup().location

        @allowed([
          'S0'
        ])
        param sku string = 'S0'

        resource cognitiveService 'Microsoft.CognitiveServices/accounts@2021-10-01' = {
          name: cognitiveServiceName
          location: location
          sku: {
            name: sku
          }
          kind: 'CognitiveServices'
          properties: {
            apiProperties: {
              statisticsEnabled: false
            }
          }
        }
        """
    );

In diesem Beispiel wird die Bicep-Vorlage als Inline-string definiert und mit dem Namen "ai"zur Ressourcenauflistung der Anwendung hinzugefügt. In diesem Beispiel wird eine Azure KI-Ressource bereitgestellt.

Parameter an Bicep-Vorlagen übergeben

Bicep unterstützt das Akzeptieren von Parametern, die zum Anpassen des Verhaltens der Vorlage verwendet werden können. Um Parameter an eine Bicep-Vorlage aus .NET.NET Aspire zu übergeben, rufen Sie die WithParameter-Methode auf, wie im folgenden Beispiel dargestellt wird.

var region = builder.AddParameter("region");

builder.AddBicepTemplate("storage", "../infra/storage.bicep")
       .WithParameter("region", region)
       .WithParameter("storageName", "app-storage")
       .WithParameter("tags", ["latest","dev"]);

Der vorangehende Code:

• Fügt einen Parameter namens "region" der Instanz builder hinzu.
• Fügt einen Verweis auf eine Bicep-Datei hinzu, die unter ../infra/storage.bicepgespeichert ist.
• Übergibt den "region"-Parameter an die Bicep-Vorlage, die mithilfe der Standardparameterauflösung aufgelöst wird.
• Übergibt den "storageName"-Parameter an die Bicep-Vorlage mit einem hartcodierten Wert.
• Übergibt den "tags"-Parameter in Form eines Arrays von Zeichenfolgen an die Bicep-Vorlage.

Weitere Informationen finden Sie unter Externe Parameter.

Bekannte Parameter

.NET .NET Aspire stellt eine Reihe bekannter Parameter zur Verfügung, die an Bicep-Vorlagen übergeben werden können. Diese Parameter werden verwendet, um Informationen über die Anwendung und die Umgebung für die Bicep-Vorlagen bereitzustellen. Die folgenden bekannten Parameter sind verfügbar:

Um einen bekannten Parameter zu verwenden, übergeben Sie den Parameternamen an die WithParameter-Methode, z. B. WithParameter(AzureBicepResource.KnownParameters.KeyVaultName). Sie übergeben keine Werte für bekannte Parameter, denn .NET.NET Aspire löst sie in Ihrem Auftrag auf.

Betrachten Sie ein Beispiel, in dem Sie einen Azure Event Grid-Webhook einrichten möchten. Sie können die Vorlage "Bicep" wie folgt definieren:

param topicName string
param webHookEndpoint string
param principalId string
param principalType string
param location string = resourceGroup().location

// The topic name must be unique because it's represented by a DNS entry. 
// must be between 3-50 characters and contain only values a-z, A-Z, 0-9, and "-".

resource topic 'Microsoft.EventGrid/topics@2023-12-15-preview' = {
  name: toLower(take('${topicName}${uniqueString(resourceGroup().id)}', 50))
  location: location

  resource eventSubscription 'eventSubscriptions' = {
    name: 'customSub'
    properties: {
      destination: {
        endpointType: 'WebHook'
        properties: {
          endpointUrl: webHookEndpoint
        }
      }
    }
  }
}

resource EventGridRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(topic.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'd5a91429-5739-47e2-a06b-3470a27159e7'))
  scope: topic
  properties: {
    principalId: principalId
    principalType: principalType
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'd5a91429-5739-47e2-a06b-3470a27159e7')
  }
}

output endpoint string = topic.properties.endpoint

Diese Bicep-Vorlage definiert mehrere Parameter, einschließlich der topicName, webHookEndpoint, principalId, principalTypeund der optionalen location. Um diese Parameter an die Bicep-Vorlage zu übergeben, können Sie den folgenden Codeausschnitt verwenden:

var webHookApi = builder.AddProject<Projects.WebHook_Api>("webhook-api");

var webHookEndpointExpression = ReferenceExpression.Create(
        $"{webHookApi.GetEndpoint("https")}/hook");

builder.AddBicepTemplate("event-grid-webhook", "../infra/event-grid-webhook.bicep")
       .WithParameter("topicName", "events")
       .WithParameter(AzureBicepResource.KnownParameters.PrincipalId)
       .WithParameter(AzureBicepResource.KnownParameters.PrincipalType)
       .WithParameter("webHookEndpoint", () => webHookEndpointExpression);

• Das Projekt webHookApi wird als Verweis auf builderhinzugefügt.
• Dem Parameter topicName wird ein fest einprogrammierter Namenswert übergeben.
• Der webHookEndpoint-Parameter wird als Ausdruck übergeben, der von dem "https"-Endpunkt des api Projekts mit der /hook Route in die URL aufgelöst wird.
• Die Parameter principalId und principalType werden als bekannte Parameter übergeben.

Die bekannten Parameter sind konventionsbasiert und sollten nicht mit einem entsprechenden Wert bei der Übergabe der WithParameter-API einhergehen. Bekannte Parameter vereinfachen einige häufig verwendete Funktionen, z. B. Rollenzuweisungen, wenn sie den Bicep-Vorlagen hinzugefügt werden, wie im vorhergehenden Beispiel gezeigt wird. Rollenzuweisungen sind erforderlich, damit der Event Grid-Webhook Ereignisse an den angegebenen Endpunkt sendet. Weitere Informationen finden Sie unter Rollenzuweisung von Ereignisrasterdaten-Absendern.

Ergebnisse aus Bicep-Verweisen abrufen

Zusätzlich zum Übergeben von Parametern an Bicep-Vorlagen können Sie auch Ausgaben aus Bicep-Vorlagen abrufen. Betrachten Sie die folgende Bicep-Vorlage, da sie eine output namens endpointdefiniert:

param storageName string
param location string = resourceGroup().location

resource myStorageAccount 'Microsoft.Storage/storageAccounts@2019-06-01' = {
  name: storageName
  location: location
  kind: 'StorageV2'
  sku:{
    name:'Standard_LRS'
    tier: 'Standard'
  }
  properties: {
    accessTier: 'Hot'
  }
}

output endpoint string = myStorageAccount.properties.primaryEndpoints.blob

Bicep definiert eine Ausgabe namens endpoint. Um die Ausgabe aus der Bicep-Vorlage abzurufen, rufen Sie die GetOutput-Methode für eine IResourceBuilder<AzureBicepResource>-Instanz auf, wie im folgenden C#-Codeausschnitt veranschaulicht:

var storage = builder.AddBicepTemplate(
        name: "storage",
        bicepFile: "../infra/storage.bicep"
    );

var endpoint = storage.GetOutput("endpoint");

In diesem Beispiel wird die Ausgabe der Bicep-Vorlage abgerufen und in einer endpoint Variablen gespeichert. In der Regel würden Sie diese Ausgabe als Umgebungsvariable an eine andere Ressource übergeben, die davon abhängt. Wenn Sie beispielsweise ein ASP.NET Core Minimales API-Projekt hatten, das von diesem Endpunkt abhängig ist, könnten Sie die Ausgabe als Umgebungsvariable an das Projekt übergeben. Verwenden Sie dazu den folgenden Codeausschnitt:

var storage = builder.AddBicepTemplate(
                name: "storage",
                bicepFile: "../infra/storage.bicep"
            );

var endpoint = storage.GetOutput("endpoint");

var apiService = builder.AddProject<Projects.AspireSample_ApiService>(
        name: "apiservice"
    )
    .WithEnvironment("STORAGE_ENDPOINT", endpoint);

Weitere Informationen finden Sie unter Bicep-Ergebnisse.

Erhalten von geheimen Daten aus Bicep-Referenzen

Es ist wichtig, ausgaben für geheime beim Arbeiten mit Bicep zu vermeiden. Wenn eine Ausgabe als geheimbetrachtet wird, was bedeutet, dass sie nicht in Protokollen oder an anderen Orten angezeigt werden sollte, können Sie sie entsprechend behandeln. Dies kann erreicht werden, indem das Geheimnis in Azure Key Vault gespeichert und in der Bicep-Vorlage referenziert wird. .NET Aspire's Azure-Integration bietet ein Muster zum sicheren Speichern von Ausgaben der Bicep-Vorlage, indem Ressourcen den keyVaultName-Parameter verwenden, um Geheimnisse in Azure Key Vault zu speichern.

Betrachten Sie die folgende Bicep-Vorlage als Beispiel, um dieses Konzept der Sicherung geheimer Ausgaben zu veranschaulichen:

param databaseAccountName string
param keyVaultName string

param databases array = []

@description('Tags that will be applied to all resources')
param tags object = {}

param location string = resourceGroup().location

var resourceToken = uniqueString(resourceGroup().id)

resource cosmosDb 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' = {
    name: replace('${databaseAccountName}-${resourceToken}', '-', '')
    location: location
    kind: 'GlobalDocumentDB'
    tags: tags
    properties: {
        consistencyPolicy: { defaultConsistencyLevel: 'Session' }
        locations: [
            {
                locationName: location
                failoverPriority: 0
            }
        ]
        databaseAccountOfferType: 'Standard'
    }

    resource db 'sqlDatabases@2023-04-15' = [for name in databases: {
        name: '${name}'
        location: location
        tags: tags
        properties: {
            resource: {
                id: '${name}'
            }
        }
    }]
}

var primaryMasterKey = cosmosDb.listKeys(cosmosDb.apiVersion).primaryMasterKey

resource vault 'Microsoft.KeyVault/vaults@2023-07-01' existing = {
    name: keyVaultName

    resource secret 'secrets@2023-07-01' = {
        name: 'connectionString'
        properties: {
            value: 'AccountEndpoint=${cosmosDb.properties.documentEndpoint};AccountKey=${primaryMasterKey}'
        }
    }
}

Die vorangehende Bicep-Vorlage erwartet unter anderem einen keyVaultName Parameter. Anschließend wird eine Ressource des Typs Azure Cosmos DB definiert und ein Geheimnis in Azure Key Vaultgepackt, das als connectionString benannt ist und die vollqualifizierte Verbindungszeichenfolge für die Cosmos DB-Instanz darstellt. Um auf diesen geheimen Verbindungszeichenfolgenwert zuzugreifen, können Sie den folgenden Codeausschnitt verwenden:

var cosmos = builder.AddBicepTemplate("cosmos", "../infra/cosmosdb.bicep")
    .WithParameter("databaseAccountName", "fallout-db")
    .WithParameter(AzureBicepResource.KnownParameters.KeyVaultName)
    .WithParameter("databases", ["vault-33", "vault-111"]);

var connectionString =
    cosmos.GetSecretOutput("connectionString");

builder.AddProject<Projects.WebHook_Api>("api")
    .WithEnvironment(
        "ConnectionStrings__cosmos",
        connectionString);

Im vorherigen Codeausschnitt wird die cosmos Bicep-Vorlage als Referenz zur builderhinzugefügt. Die geheime Ausgabe von connectionString wird aus der Bicep-Vorlage abgerufen und in einer Variablen gespeichert. Die geheime Ausgabe wird dann als Umgebungsvariable (ConnectionStrings__cosmos) an das api-Projekt übergeben. Diese Umgebungsvariable wird verwendet, um eine Verbindung mit der Cosmos DB Instanz herzustellen.

Wenn diese Ressource bereitgestellt wird, wird der zugrunde liegende Bereitstellungsmechanismus automatisch Geheimnisse aus Azure Key Vault referenzieren. Um die geheime Isolation zu gewährleisten, erstellt .NET.NET Aspire einen Key Vault pro Quelle.

Verlagswesen

Wenn Sie Ihre App veröffentlichen, wird die von der Azure generierte Bicep-Bereitstellung Azure Developer CLI verwendet, um die Azure-Ressourcen innerhalb Ihres Azure-Abonnements zu erstellen. .NET .NET Aspire gibt ein Veröffentlichungsmanifestaus, das zudem ein wesentlicher Bestandteil des Veröffentlichungsprozesses ist. Die Azure Developer CLI ist ein Befehlszeilentool, das eine Reihe von Befehlen zum Verwalten von Azure-Ressourcen bereitstellt.

Weitere Informationen zur Veröffentlichung und Bereitstellung finden Sie unter Bereitstellen eines .NET Aspire Projekts zum Azure Container Apps mithilfe des Azure Developer CLI (ausführlicher Leitfaden).