Overzicht van .NET AspireAzure-integraties

Azure is het populairste cloudplatform voor het bouwen en implementeren van .NET toepassingen. De Azure SDK voor .NET maakt eenvoudig beheer en gebruik van Azure services mogelijk. .NET Aspire biedt een set integraties met Azure services, waar u gratis nieuwe resources kunt toevoegen of verbinding kunt maken met bestaande resources. In dit artikel worden enkele algemene aspecten van alle Azure integraties in .NET Aspire beschreven en wordt uitgelegd hoe u deze kunt gebruiken.

Azure-resources toevoegen

Alle .NET AspireAzure hostingintegraties maken Azure resources beschikbaar en volgens de conventie worden toegevoegd met behulp van AddAzure* API's. Wanneer u deze resources toevoegt aan uw .NET Aspire app-host, vertegenwoordigen ze een Azure service. De AddAzure*-API retourneert een IResourceBuilder<T> waarbij T het type Azure resource is. Deze IResourceBuilder<T> (builder)-interfaces bieden een fluent-API waarmee u de onderliggende Azure-resource kunt configureren binnen het app-model. Er zijn API's voor het toevoegen van nieuwe Azure resources, het markeren van resources als bestaande en het configureren van het gedrag van de resources in verschillende uitvoeringscontexten.

Typische ontwikkelaarservaring

Wanneer uw .NET Aspire app-host Azure resources bevat en u deze lokaal uitvoert (typische ontwikkelaar F5- of dotnet run-ervaring), worden de Azure resources ingericht in uw Azure-abonnement. Hierdoor kunt u als ontwikkelaar lokaal fouten opsporen in de context van uw app-host.

.NET .NET Aspire streeft naar kostenminimalisatie door te kiezen voor Basic of StandardStock Keeping Unit (SKU) voor zijn Azure-integraties. Hoewel deze standaardinstellingen beschikbaar zijn, kunt u de middelen aanpassen Azure aan uw behoeften. Daarnaast ondersteunen sommige integraties emulators of containers, die nuttig zijn voor lokale ontwikkeling, testen en foutopsporing. Wanneer u uw app lokaal uitvoert, gebruiken de Azure resources standaard de werkelijke Azure-service. U kunt ze echter configureren voor het gebruik van lokale emulators of containers, waardoor kosten worden vermeden die zijn gekoppeld aan de werkelijke Azure-service tijdens lokale ontwikkeling.

Lokale emulators

Sommige Azure-services kunnen worden geëmuleerd om lokaal te worden uitgevoerd. Op dit moment ondersteunt .NET Aspire de volgende Azure emulators:

Als u uw Azure resources de lokale emulators wilt laten gebruiken, roept u de RunAsEmulator methode aan op de Azure resource builder. Met deze methode configureert u de Azure resource voor het gebruik van de lokale emulator in plaats van de werkelijke Azure-service.

Lokale containers

Sommige Azure resources kunnen lokaal worden vervangen met behulp van opensource- of on-premises containers. Als u een Azure resource lokaal in een container wilt vervangen, koppelt u een aanroep naar de RunAsContainer methode in de Azure resourcebouwer. Met deze methode configureert u de Azure-resource voor het gebruik van een in een container geplaatste versie van de service voor lokale ontwikkeling en testen, in plaats van de daadwerkelijke Azure-service.

Op dit moment ondersteunt .NET Aspire de volgende Azure services als containers:

Inzicht in Azure integratie-API's

.NET .NET Aspire's kracht ligt in zijn vermogen om een geweldige binnenste lus voor ontwikkelaars te bieden. De Azure-integraties zijn niet anders. Ze bieden een set algemene API's en patronen die worden gedeeld in alle Azure resources. Deze API's en patronen zijn zo ontworpen dat u eenvoudig op een consistente manier met Azure resources kunt werken.

In de voorgaande sectie containers hebt u gezien hoe u Azure services lokaal kunt uitvoeren in containers. Als u bekend bent met .NET.NET Aspire, vraagt u zich misschien af hoe het aanroepen van AddAzureRedis("redis").RunAsContainer() om een lokale docker.io/library/redis-container te krijgen verschilt van AddRedis("redis"), omdat deze beide resulteren in dezelfde lokale container.

Het antwoord is dat er geen verschil is bij het lokaal uitvoeren. Wanneer ze echter worden gepubliceerd, krijgt u verschillende resources:

Hetzelfde geldt voor SQL- en PostgreSQL-services:

Zie .NET.NET Aspire app-host: Uitvoeringscontextvoor meer informatie over het verschil tussen uitvoerings- en publicatiemodi.

API's voor het uitdrukken van Azure resources in verschillende modi

De gedistribueerde toepassingsbouwer, onderdeel van de app-host, gebruikt het bouwerpatroon om middelen toe te voegen aan het app-model. Ontwikkelaars kunnen deze resources configureren en hun gedrag definiëren in verschillende uitvoeringscontexten. Azure hostingintegraties bieden API's om op te geven hoe deze resources moeten worden 'gepubliceerd' en 'uitgevoerd'.

Wanneer de app-host wordt uitgevoerd, wordt de uitvoeringscontext gebruikt om te bepalen of de app-host zich in de modus Run of Publish bevindt. De naamconventies voor deze API's geven de beoogde actie voor de resource aan.

De volgende tabel bevat een overzicht van de naamconventies die worden gebruikt om Azure resources uit te drukken:

Zie Uitvoeringscontextvoor meer informatie over uitvoeringsmodi.

Algemene gebruiksscenario's voor de uitvoeringsmodus-API

Gebruik RunAsExisting wanneer u dynamisch moet communiceren met een bestaande resource tijdens runtime zonder deze te hoeven implementeren of bij te werken. Gebruik PublishAsExisting bij het declareren van bestaande resources als onderdeel van een implementatieconfiguratie, zodat de juiste bereiken en machtigingen worden toegepast. Gebruik ten slotte AsExisting<T>(IResourceBuilder<T>, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>) bij het declareren van bestaande resources in beide configuraties, met een vereiste om de verwijzingen te parameteriseren.

U kunt controleren of een resource is gemarkeerd als een bestaande resource, door de IsExisting(IResource)-extensiemethode aan te roepen op de IResource. Zie Bestaande Azure-resourcesgebruiken voor meer informatie.

Bestaande Azure-resources gebruiken

.NET Aspire biedt ondersteuning voor het verwijzen naar bestaande Azure resources. U markeert een bestaande resource via de PublishAsExisting, RunAsExistingen AsExisting API's. Met deze API's kunnen ontwikkelaars verwijzen naar al geïmplementeerde Azure resources, deze configureren en de juiste implementatiemanifesten genereren met behulp van Bicep-sjablonen.

Bestaande resources waarnaar wordt verwezen met deze API's kunnen worden uitgebreid met roltoewijzingen en andere aanpassingen die beschikbaar zijn met de infrastructuur van .NET.NET Aspireals codemogelijkheden. Deze API's zijn beperkt tot Azure resources die kunnen worden geïmplementeerd met Bicep-sjablonen.

Bestaande Azure-resources configureren voor de uitvoeringsmodus

De methode RunAsExisting wordt gebruikt wanneer een gedistribueerde toepassing wordt uitgevoerd in de uitvoeringsmodus. In deze modus wordt ervan uitgegaan dat de Azure resource waarnaar wordt verwezen, al bestaat en tijdens de uitvoering wordt geïntegreerd zonder de resource in te richten. Als u een Azure resource als bestaande wilt markeren, roept u de RunAsExisting methode aan in de opbouwfunctie voor resources. Bekijk het volgende voorbeeld:

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

De voorgaande code:

• Hiermee maakt u een nieuw builder-exemplaar.
• Hiermee voegt u een parameter met de naam existingServiceBusName toe aan de opbouwfunctie.
• Voegt een Azure Service Bus-resource met de naam messaging toe aan de bouwer.
• Roept de RunAsExisting-methode aan op de serviceBus-resourcebouwer, waarbij existingServiceBusName als parameter wordt doorgegeven. Als alternatief kunt u de overload van string gebruiken.
• Hiermee voegt u een wachtrij met de naam queue toe aan de serviceBus resource.

Standaard wordt ervan uitgegaan dat de Service Bus-parameterreferentie zich in dezelfde Azure resourcegroep bevindt. Als deze zich echter in een andere resourcegroep bevindt, kunt u de resourcegroep expliciet doorgeven als parameter om de juiste resourcegroep op te geven.

Bestaande Azure-resources configureren voor de publicatiemodus

De methode PublishAsExisting wordt gebruikt in de modus Publiceren wanneer de intentie is om een reeds bestaande Azure resource te declareren en ernaar te verwijzen tijdens de publicatiemodus. Deze API vereenvoudigt het maken van manifesten en sjablonen die resourcedefinities bevatten die zijn toegewezen aan bestaande resources in Bicep.

Als u een Azure resource wilt markeren als bestaande in de modus Publiceren, roept u de PublishAsExisting-methode aan in de opbouwfunctie voor resources. Bekijk het volgende voorbeeld:

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

De voorgaande code:

• Hiermee maakt u een nieuw builder-exemplaar.
• Hiermee voegt u een parameter met de naam existingServiceBusName toe aan de opbouwfunctie.
• Voegt een Azure Service Bus-resource met de naam messaging toe aan de bouwer.
• Roept de PublishAsExisting methode aan op de serviceBus resourcebouwer, waarbij de parameter existingServiceBusName wordt doorgegeven. U kunt ook de string parameteroverbelasting gebruiken.
• Hiermee voegt u een wachtrij met de naam queue toe aan de serviceBus resource.

Nadat de app-host is uitgevoerd in de publicatiemodus, bevat het gegenereerde manifestbestand de parameter existingResourceName, die kan worden gebruikt om te verwijzen naar de bestaande Azure resource. Houd rekening met het volgende gegenereerde gedeeltelijke fragment van het manifestbestand:

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

Voor meer informatie over het manifestbestand, zie .NET.NET Aspire manifestindeling voor ontwerpers van deploytools.

Daarnaast bevat de gegenereerde Bicep-sjabloon de parameter existingResourceName, die kan worden gebruikt om te verwijzen naar de bestaande Azure-resource. Bekijk de volgende gegenereerde Bicep-sjabloon:

@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

Voor meer informatie over de gegenereerde Bicep-sjablonen, zie Infrastructure as code en overweeg andere publicatie-API's.

Bestaande Azure-resources configureren in alle modi

De methode AsExisting<T>(IResourceBuilder<T>, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>) wordt gebruikt wanneer de gedistribueerde toepassing wordt uitgevoerd in de modus Uitvoeren of Publiceren. Omdat de methode AsExisting in beide scenario's werkt, ondersteunt deze alleen een geparameteriseerde verwijzing naar de resourcenaam of resourcegroepnaam. Deze aanpak helpt bij het voorkomen van het gebruik van dezelfde resource in zowel test- als productieomgevingen.

Als u een Azure resource als bestaande wilt markeren, roept u de AsExisting methode aan in de opbouwfunctie voor resources. Bekijk het volgende voorbeeld:

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

De voorgaande code:

• Hiermee maakt u een nieuw builder-exemplaar.
• Hiermee voegt u een parameter met de naam existingServiceBusName toe aan de opbouwfunctie.
• Voegt een Azure Service Bus-resource met de naam messaging toe aan de bouwer.
• Roept de methode AsExisting op de resourcebouwer serviceBus aan, waarbij de parameter existingServiceBusName wordt doorgegeven.
• Hiermee voegt u een wachtrij met de naam queue toe aan de serviceBus resource.

Bestaande Azure-resources toevoegen met verbindingsreeksen

.NET .NET Aspire biedt de mogelijkheid om verbinding te maken met bestaande resources, inclusief Azure resources. Het uitdrukken van verbindingsreeksen is handig wanneer u bestaande Azure resources hebt die u wilt gebruiken in uw .NET Aspire-app. De AddConnectionString-API wordt gebruikt met de uitvoeringscontext van de app-host om voorwaardelijk een verbindingsreeks toe te voegen aan het app-model.

Bekijk het volgende voorbeeld, waarbij u in de publicatiemodus een Azure Storage-resource toevoegt, terwijl u in de uitvoermodus een verbindingsreeks toevoegt aan een bestaande Azure Storage:

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

De voorgaande code:

• Hiermee maakt u een nieuw builder-exemplaar.
• Hiermee wordt een Azure Storage-resource met de naam storage toegevoegd in de modus Publiceren.
• Hiermee voegt u een verbindingsreeks toe aan een bestaande Azure-opslag met de naam storage in de uitvoermodus.
• Hiermee voegt u een project met de naam api toe aan het bouwprogramma.
• Het api project verwijst naar de storage resource, ongeacht de modus.

Het verbruikende API-project gebruikt de verbindingsreeksgegevens zonder dat u weet hoe de app-host dit heeft geconfigureerd. In de modus Publiceren wordt met de code een nieuwe Azure Storage-resource toegevoegd. Dit wordt weerspiegeld in het implementatiemanifest dienovereenkomstig. Wanneer de verbindingsreeks zich in de uitvoeringsmodus bevindt, komt deze overeen met een configuratiewaarde die zichtbaar is voor de app-host. Er wordt aangenomen dat alle roltoewijzingen voor de doelresource zijn geconfigureerd. Dit betekent dat u waarschijnlijk een omgevingsvariabele of een gebruikersgeheim configureert om de verbindingsreeks op te slaan. De configuratie wordt opgelost vanuit de configuratiesleutel ConnectionStrings__storage (of ConnectionStrings:storage). Deze configuratiewaarden kunnen worden weergegeven wanneer de app wordt uitgevoerd. Zie Resourcedetailsvoor meer informatie.

In tegenstelling tot bestaande resources die zijn gemodelleerd met de eersteklas AsExisting API-, kunnen bestaande resources die zijn gemodelleerd als verbindingsreeksen, niet worden uitgebreid met aanvullende roltoewijzingen of infrastructuuraanpassingen.

Publiceren als Azure container-app

.NET .NET Aspire kunt u primitieve resources publiceren als Azure Container Apps, een serverloos platform dat het infrastructuurbeheer vermindert. Ondersteunde resourcetypen omvatten:

• ContainerResource: Vertegenwoordigt een opgegeven container.
• ExecutableResource: Vertegenwoordigt een opgegeven uitvoerbaar proces.
• ProjectResource: Vertegenwoordigt een opgegeven .NET project.

Gebruik de volgende API's om deze resources te publiceren:

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

Deze API's configureren de resource die moet worden gepubliceerd als een Azure Container App en roept impliciet AddAzureContainerAppsInfrastructure(IDistributedApplicationBuilder) aan om de benodigde infrastructuur en Bicep-bestanden toe te voegen aan uw app-host. Bekijk bijvoorbeeld de volgende 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)
                     });
                 });

De voorgaande code:

• Hiermee maakt u een nieuw builder-exemplaar.
• Hiermee voegt u een parameter met de naam env toe aan de opbouwfunctie.
• Hiermee voegt u een project met de naam api toe aan het bouwprogramma.
• Roept de PublishAsAzureContainerApp methode aan op de api resourcebouwer, waarbij een lambda-expressie wordt doorgegeven waarmee de infrastructuur van de Azure Container App wordt geconfigureerd, waarbij infra de AzureResourceInfrastructure is en app de ContainerAppis.
  • Hiermee voegt u een omgevingsvariabele met de naam Hello toe aan de container-app met behulp van de parameter env.
  • De methode AsProvisioningParameter wordt gebruikt om env te behandelen als een nieuwe ProvisioningParameter in de infrastructuur of om een bestaande bicep-parameter opnieuw te gebruiken als er al een met dezelfde naam bestaat.

Zie ContainerApp en AsProvisioningParametervoor meer informatie.

Infrastructuur als code

De Azure SDK voor .NET biedt het 📦Azure.Provisioning NuGet-pakket en een reeks servicespecifieke Azure provisioningpakketten. Met deze Azure inrichtingsbibliotheken kunt u eenvoudig Azure infrastructuur declaratief opgeven in .NET. Met hun API's kunt u objectgeoriënteerde infrastructuur schrijven in C#, wat resulteert in Bicep. Bicep is een domeinspecifieke taal (DSL) voor het declaratief implementeren van Azure bronnen.

Hoewel het mogelijk is om Azure resources handmatig in te richten, vereenvoudigt .NET Aspire het proces door een set API's te bieden om Azure resources uit te drukken. Deze API's zijn beschikbaar als uitbreidingsmethoden in .NET AspireAzure hostingbibliotheken, waardoor de IDistributedApplicationBuilder-interface wordt uitgebreid. Wanneer u Azure resources aan uw app-host toevoegt, voegen ze impliciet de juiste inrichtingsfunctionaliteit toe. Met andere woorden, u hoeft geen inrichtings-API's rechtstreeks aan te roepen.

Aangezien .NET Aspire modellen Azure resources binnen Azure hostingintegraties, wordt de Azure SDK gebruikt om deze resources te provisioneren. Bicep-bestanden worden gegenereerd die de Azure bronnen definiëren die je nodig hebt. De gegenereerde Bicep-bestanden worden uitgevoerd naast het manifestbestand wanneer u uw app publiceert.

Er zijn verschillende manieren om de gegenereerde Bicep-bestanden te beïnvloeden:

• Azure. Aanpassinginrichten:
  • Infrastructuur configureren: Azure resource-infrastructuur aanpassen.
  • Azure infrastructuur toevoegen: voeg Azure infrastructuur handmatig toe aan uw app-host.
• Aangepaste Bicep-sjablonen gebruiken:
  • Referentie Bicep-bestanden: Voeg een verwijzing toe naar een Bicep-bestand op de schijf.
  • Referentie Bicep inline: Voeg een inline Bicep-sjabloon toe.

Lokale voorziening en Azure.Provisioning

Om te voorkomen dat termen verward worden en om 'provisioning' duidelijk te maken, is het belangrijk om het onderscheid te begrijpen tussen lokale provisioning en Azure provisioning:

• Lokale voorziening:

  Wanneer u standaard een van de Azure hostintegratie-API's aanroept om Azure resources toe te voegen, wordt de AddAzureProvisioning(IDistributedApplicationBuilder)-API impliciet aangeroepen. Met deze API worden services geregistreerd in de container voor afhankelijkheidsinjectie (DI) die worden gebruikt om Azure resources in te richten wanneer de app-host wordt gestart. Dit concept staat bekend als lokale voorziening. Zie voor meer informatie Lokale Azure voorziening.

• Azure.Provisioning:

  Azure.Provisioning verwijst naar het NuGet-pakket en is een set bibliotheken waarmee u C# kunt gebruiken om Bicep te genereren. De Azure hostingintegraties in .NET Aspire maken op de achtergrond gebruik van deze bibliotheken om Bicep-bestanden te genereren die de Azure resources definiëren die u nodig hebt. Zie Azure.Provisioning aanpassingvoor meer informatie.

Azure.Provisioning aanpassen

Alle .NET AspireAzure hostingintegraties maken verschillende Azure resources beschikbaar en ze zijn allemaal subklassen van het AzureProvisioningResource type, die zelf de AzureBicepResourceovernemen. Hierdoor kunnen extensies, die specifiek op dit type zijn afgestemd, een vloeiende API bieden om de infrastructuur naar wens aan te passen. Hoewel .NET.NET Aspire standaardinstellingen biedt, kunt u de gegenereerde Bicep beïnvloeden met behulp van deze API's.

Infrastructuur configureren

Ongeacht de Azure-bron waarmee u werkt, koppelt u een aanroep naar de ConfigureInfrastructure-extensiemethode om de onderliggende infrastructuur te configureren. Met deze methode kunt u de infrastructuur van de Azure resource aanpassen door een configure gemachtigde van het type Action<AzureResourceInfrastructure>door te geven. Het AzureResourceInfrastructure type is een subklasse van de Azure.Provisioning.Infrastructure. Dit type maakt een enorme API-oppervlakte beschikbaar voor het configureren van de onderliggende infrastructuur van de Azure-resource.

Bekijk het volgende voorbeeld:

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

De voorgaande code:

• Hiermee voegt u een parameter toe met de naam storage-sku.
• Voegt Azure Storage toe met de AddAzureStorage-API met de naam storage.
• Koppelt een aanroep aan ConfigureInfrastructure om de Azure Storage-infrastructuur aan te passen:
  • Hiermee haalt u de voorzienbare middelen op.
  • Filtert naar één StorageAccount.
  • Hiermee wijst u de parameter storage-sku toe aan de eigenschap StorageAccount.Sku:
    • Aan een nieuw exemplaar van de StorageSku is de eigenschap Name toegewezen op basis van het resultaat van de AsProvisioningParameter-API.

Dit illustreert het stromen van een externe parameter naar de Azure Storage-infrastructuur, wat resulteert in het gegenereerde Bicep-bestand dat de gewenste configuratie weerspiegelt.

Azure-infrastructuur toevoegen

Niet alle Azure services worden weergegeven als .NET Aspire integraties. Hoewel ze op een later tijdstip kunnen zijn, kunt u nog steeds services inrichten die beschikbaar zijn in Azure.Provisioning.* bibliotheken. Stel dat u zich een scenario voorstelt waarin u een werknemerservice hebt die verantwoordelijk is voor het beheren van een Azure container registry. Stel nu dat een app-hostproject afhankelijk is van de 📦Azure. Provisioning.ContainerRegistry NuGet-pakket.

U kunt de AddAzureInfrastructure-API gebruiken om de Azure Container Registry-infrastructuur toe te voegen aan uw app-host:

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

De voorgaande code:

• Roept AddAzureInfrastructure aan met een naam van acr.
• Biedt een configureInfrastructure gemachtigde voor het aanpassen van de Azure Container Registry-infrastructuur:
  • Instantieert een ContainerRegistryService met de naam acr en een standaard-SKU.
  • Voegt de Azure Container Registry-service toe aan de variabele infra.
  • Instantieert een ProvisioningOutput met de naam registryName, een type stringen een waarde die overeenkomt met de naam van het Azure Container Registry.
  • Hiermee voegt u de uitvoer toe aan de variabele infra.
• Hiermee voegt u een project met de naam worker toe aan het bouwprogramma.
• Koppelt een aanroep aan WithEnvironment om de ACR_REGISTRY_NAME omgevingsvariabele in het project in te stellen op de waarde van de registryName-uitvoer.

De functionaliteit laat zien hoe u Azure infrastructuur toevoegt aan uw app-hostproject, zelfs als de Azure-service niet rechtstreeks wordt weergegeven als een .NET Aspire-integratie. Verder ziet u hoe u de uitvoer van het Azure Container Registry naar de omgeving van een gekoppeld project kunt leiden.

Bekijk het resulterende Bicep-bestand:

@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

Het Bicep-bestand weerspiegelt de gewenste configuratie van het Azure Container Registry, zoals gedefinieerd door de AddAzureInfrastructure-API.

Aangepaste Bicep-sjablonen gebruiken

Wanneer u zich richt op Azure als uw gewenste cloudprovider, kunt u Bicep gebruiken om uw infrastructuur als code te definiëren. Het is erop gericht de ontwerpervaring drastisch te vereenvoudigen met een schonere syntaxis en betere ondersteuning voor modulariteit en hergebruik van code.

Hoewel .NET.NET Aspire een set vooraf gemaakte Bicep-sjablonen biedt, kan het voorkomen dat u de sjablonen wilt aanpassen of uw eigen sjablonen wilt maken. In deze sectie worden de concepten en bijbehorende API's uitgelegd die u kunt gebruiken om de Bicep-sjablonen aan te passen.

Als onderdeel van het Azure implementatieverhaal voor .NET Aspirebiedt de Azure Developer CLI (azd) inzicht in uw .NET Aspire project en de mogelijkheid om het te implementeren in Azure. De azd CLI maakt gebruik van de Bicep-sjablonen om de toepassing te implementeren in Azure.

Aspire.Hosting.Azure-pakket installeren

Wanneer u wilt verwijzen naar Bicep-bestanden, is het mogelijk dat u geen van de Azure hostingintegraties gebruikt. In dit geval kunt u nog steeds verwijzen naar Bicep-bestanden door het Aspire.Hosting.Azure-pakket te installeren. Dit pakket biedt de benodigde API's om te verwijzen naar Bicep-bestanden en de Azure-resources aan te passen.

Om een van deze functionaliteiten te gebruiken, moet het 📦AspireHostingAzure NuGet-pakket geïnstalleerd zijn.

dotnet add package Aspire.Hosting.Azure

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

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

Wat u kunt verwachten van de voorbeelden

In alle voorbeelden in deze sectie wordt ervan uitgegaan dat u de Aspire.Hosting.Azure naamruimte gebruikt. Daarnaast wordt in de voorbeelden ervan uitgegaan dat u een IDistributedApplicationBuilder exemplaar hebt:

using Aspire.Hosting.Azure;

var builder = DistributedApplication.CreateBuilder(args);

// Examples go here...

builder.Build().Run();

Wanneer u een van de Bicep-gerelateerde API's aanroept, wordt standaard ook een aanroep uitgevoerd naar AddAzureProvisioning waarmee ondersteuning wordt toegevoegd voor het dynamisch genereren van Azure resources tijdens het opstarten van de toepassing. Voor meer informatie, zie Lokale inrichting en Azure.Provisioning.

Verwijzing naar Bicep-bestanden

Stel dat u een Bicep-sjabloon hebt in een bestand met de naam storage.bicep dat een Azure-opslagaccount inricht:

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'
  }
}

Als u een verwijzing naar het Bicep-bestand op schijf wilt toevoegen, roept u de methode AddBicepTemplate aan. Bekijk het volgende voorbeeld:

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

De voorgaande code voegt een verwijzing toe naar een Bicep-bestand dat zich in ../infra/storage.bicepbevindt. De bestandspaden moeten relatief zijn ten opzichte van de app-host project. Deze verwijzing resulteert erin dat een AzureBicepResource wordt toegevoegd aan de verzameling resources van de toepassing met de "storage"-naam, en de API retourneert een IResourceBuilder<AzureBicepResource>-instantie die kan worden gebruikt om de resource verder aan te passen.

Referentie Bicep in lijn

Hoewel een Bicep-bestand op schijf het meest voorkomende scenario is, kunt u ook Bicep-sjablonen inline toevoegen. Inlinesjablonen kunnen handig zijn wanneer u een sjabloon in code wilt definiëren of wanneer u de sjabloon dynamisch wilt genereren. Als u een inline Bicep-sjabloon wilt toevoegen, roept u de methode AddBicepTemplateString aan met de Bicep-sjabloon als een string. Bekijk het volgende voorbeeld:

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 dit voorbeeld wordt de Bicep-sjabloon gedefinieerd als inline string en toegevoegd aan de resourceverzameling van de toepassing met de naam "ai". In dit voorbeeld wordt een Azure AI-resource ingericht.

Parameters doorgeven aan Bicep-sjablonen

Bicep ondersteunt het accepteren van parameters, die kunnen worden gebruikt om het gedrag van de sjabloon aan te passen. Als u parameters wilt doorgeven aan een Bicep-sjabloon van .NET.NET Aspire, doet u dit door ketenoproepen te maken naar de methode WithParameter, zoals wordt weergegeven in het volgende voorbeeld:

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

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

De voorgaande code:

• Hiermee voegt u een parameter met de naam "region" toe aan het builder-exemplaar.
• Voegt een verwijzing toe naar een Bicep-bestand dat zich in ../infra/storage.bicepbevindt.
• Geeft de parameter "region" door aan de Bicep-sjabloon, die wordt opgelost met behulp van de standaard parameterresolutie.
• Geeft de "storageName"-parameter door aan de Bicep-sjabloon met een hardgecodeerde waarde.
• Geeft de parameter "tags" door aan de Bicep-sjabloon met een array van tekenreeksen.

Zie Externe parametersvoor meer informatie.

Bekende parameters

.NET .NET Aspire biedt een set bekende parameters die kunnen worden doorgegeven aan Bicep-sjablonen. Deze parameters worden gebruikt voor informatie over de toepassing en de omgeving voor de Bicep-sjablonen. De volgende bekende parameters zijn beschikbaar:

Als u een bekende parameter wilt gebruiken, geeft u de parameternaam door aan de methode WithParameter, zoals WithParameter(AzureBicepResource.KnownParameters.KeyVaultName). U geeft geen waarden door voor bekende parameters, omdat .NET.NET Aspire deze namens u oplost.

Bekijk een voorbeeld waarin u een Azure Event Grid-webhook wilt instellen. U kunt de Bicep-sjabloon als volgt definiëren:

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

Deze Bicep-sjabloon definieert verschillende parameters, waaronder de topicName, webHookEndpoint, principalId, principalTypeen de optionele location. Als u deze parameters wilt doorgeven aan de Bicep-sjabloon, kunt u het volgende codefragment gebruiken:

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

• Het webHookApi project wordt toegevoegd als verwijzing naar de builder.
• De parameter topicName krijgt een vastgelegde naamwaarde mee.
• De parameter webHookEndpoint wordt doorgegeven als een expressie die zich omzet in de URL vanuit het "https"-eindpunt van de api projectverwijzingen met de /hook route.
• De parameters principalId en principalType worden doorgegeven als bekende parameters.

De bekende parameters zijn gebaseerd op conventies en moeten niet worden vergezeld van een bijbehorende waarde wanneer deze wordt doorgegeven met behulp van de WithParameter-API. Bekende parameters vereenvoudigen een aantal algemene functionaliteit, zoals roltoewijzingen, wanneer deze worden toegevoegd aan de Bicep-sjablonen, zoals wordt weergegeven in het voorgaande voorbeeld. Roltoewijzingen zijn vereist voor de Event Grid-webhook om gebeurtenissen naar het opgegeven eindpunt te verzenden. Zie Roltoewijzing event grid-gegevenszendervoor meer informatie.

Uitvoer verkrijgen van Bicep-verwijzingen

Naast het doorgeven van parameters aan Bicep-sjablonen, kunt u ook uitvoer krijgen van de Bicep-sjablonen. Houd rekening met de volgende Bicep-sjabloon, die een output met de naam endpoint definieert.

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

De uitvoer met de naam endpoint wordt gedefinieerd door Bicep. Als u de uitvoer van de Bicep-sjabloon wilt ophalen, roept u de methode GetOutput aan op een IResourceBuilder<AzureBicepResource> exemplaar, zoals gedemonstreerd in het volgende C#-codefragment.

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

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

In dit voorbeeld wordt de uitvoer van de Bicep-sjabloon opgehaald en opgeslagen in een endpoint variabele. Normaal gesproken geeft u deze uitvoer als een omgevingsvariabele door aan een andere resource die ervan afhankelijk is. Als u bijvoorbeeld een ASP.NET Core Minimaal API-project hebt dat afhankelijk is van dit eindpunt, kunt u de uitvoer als een omgevingsvariabele doorgeven aan het project met behulp van het volgende codefragment:

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

Zie Bicep-uitvoervoor meer informatie.

Geheime uitvoer verkrijgen uit Bicep-referenties

Het is belangrijk om uitvoer van geheimen te voorkomen wanneer u met Bicep werkt. Als een uitvoer wordt beschouwd als een geheim, wat betekent dat deze niet moet worden weergegeven in logboeken of andere plaatsen, kunt u deze als zodanig behandelen. Dit kan worden bereikt door het geheim op te slaan in Azure Key Vault en ernaar te verwijzen in de Bicep-sjabloon. .NET Aspireintegratie van Azure biedt een patroon voor het veilig opslaan van uitvoer van de Bicep-sjabloon door resources toe te staan de parameter keyVaultName te gebruiken om geheimen in Azure Key Vaultop te slaan.

Bekijk de volgende Bicep-sjabloon als voorbeeld waarmee u dit concept van het beveiligen van geheime uitvoer kunt demonstreren:

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}'
        }
    }
}

In de voorgaande Bicep-sjabloon wordt een parameter keyVaultName verwacht, samen met verschillende andere parameters. Vervolgens wordt een Azure Cosmos DB-resource gedefinieerd en wordt een geheim vastgelegd in Azure Key Vault, met de naam connectionString die de volledig gekwalificeerde verbindingsreeks aan het Cosmos DB-exemplaar vertegenwoordigt. Voor toegang tot deze geheime verbindingsreekswaarde kunt u het volgende codefragment gebruiken:

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

In het voorgaande codefragment wordt de cosmos Bicep-sjabloon toegevoegd als verwijzing naar de builder. De geheime uitvoer connectionString wordt uit de Bicep-sjabloon opgehaald en opgeslagen in een variabele. De geheime uitvoer wordt vervolgens doorgegeven als een omgevingsvariabele (ConnectionStrings__cosmos) aan het api project. Deze omgevingsvariabele wordt gebruikt om verbinding te maken met het Cosmos DB-exemplaar.

Wanneer deze resource wordt geïmplementeerd, zal het onderliggende implementatiemechanisme automatisch geheimen opvragen uit Azure Key Vault. Om geheime isolatie te garanderen, maakt .NET.NET Aspire een Key Vault per bron.

Publiceren

Wanneer u uw app publiceert, wordt de Azure inrichting gegenereerde Bicep gebruikt door de Azure Developer CLI om de Azure resources in uw Azure-abonnement te maken. .NET .NET Aspire genereert een publicatiemanifest, dat ook een essentieel onderdeel van het publicatieproces is. Het Azure Developer CLI is een opdrachtregelprogramma dat een set opdrachten biedt voor het beheren van Azure resources.

Zie Een .NET Aspire-project implementeren voor Azure Container Apps met behulp van de Azure Developer CLI (uitgebreide handleiding)voor meer informatie over het publiceren en implementeren.