Aspire Azure Integrering av appkonfiguration

Inkluderar:Värdintegrering ingår Värdintegrering &–& integrering ingår integration

Azure App Configuration tillhandahåller en tjänst för att centralt hantera programinställningar och funktionsflaggor. Moderna program, särskilt program som körs i ett moln, har generellt många komponenter som är distribuerade. Om konfigurationsinställningar sprids mellan dessa komponenter kan det ge upphov till fel som är svåra att felsöka under en programdistribution. Med AspireAzure integreringen av appkonfiguration kan du ansluta till befintliga appkonfigurationsinstanser eller skapa nya instanser från din AppHost.

Integrering av värdtjänster

Appkonfigurationens AspireAzure värdintegration modellerar appkonfigurationsresursen som AzureAppConfigurationResource-typen. Om du vill komma åt den här typen och API:er som uttrycker resursen lägger du till 📦Aspire. Hosting.Azure. NuGet-paketet AppConfiguration i AppHost-projektet .

dotnet add package Aspire.Hosting.Azure.AppConfiguration

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

Mer information finns i dotnet lägg till paket eller Hantera paketberoenden i .NET applikationer.

Lägg till Azure appkonfigurationsresurs

I ditt AppHost-projekt anropar du AddAzureAppConfiguration för att lägga till och returnera en Azure appkonfigurationsresursbyggare.

var builder = DistributedApplication.CreateBuilder(args);

var appConfig = builder.AddAzureAppConfiguration("config");

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

builder.Build().Run();

När du lägger till en AzureAppConfigurationResource i AppHost exponeras andra användbara API:er.

Konfigurationsgenererad Bicep

Om du inte har använt Bicep tidigare är det ett domänspecifikt språk för att Azure definiera resurser. Med Aspirebehöver du inte skriva Bicep för hand, i stället genererar etablerings-API:erna Bicep åt dig. När du publicerar din app genereras Bicep-filen tillsammans med manifestfilen. När du lägger till en Azure App Configuration-resurs genereras följande Bicep:

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

resource config 'Microsoft.AppConfiguration/configurationStores@2024-06-01' = {
  name: take('config-${uniqueString(resourceGroup().id)}', 50)
  location: location
  properties: {
    disableLocalAuth: true
  }
  sku: {
    name: 'standard'
  }
  tags: {
    'aspire-resource-name': 'config'
  }
}

output appConfigEndpoint string = config.properties.endpoint

output name string = config.name

Den föregående Bicep-modulen är en modul som tillhandahåller en App Configuration-resurs. Dessutom skapas rolltilldelningar för resursen Azure i en separat modul:

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

param config_outputs_name string

param principalType string

param principalId string

resource config 'Microsoft.AppConfiguration/configurationStores@2024-06-01' existing = {
  name: config_outputs_name
}

resource config_AppConfigurationDataOwner 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(config.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '5ae67dd6-50cb-40e7-96ff-dc2bfa4b606b'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '5ae67dd6-50cb-40e7-96ff-dc2bfa4b606b')
    principalType: principalType
  }
  scope: config
}

Den genererade Bicep är en startpunkt och påverkas av ändringar i tillhandahållandeinfrastrukturen i C#. Anpassningar till Bicep-filen skrivs över direkt, så gör ändringar via C#-etablerings-API:erna för att säkerställa att de återspeglas i de genererade filerna.

Anpassa infrastruktur för provisionering

Alla AspireAzure resurser är underklasser av den AzureProvisioningResource typen. Den här typen möjliggör anpassning av den genererade Bicep genom att tillhandahålla ett flytande API för konfigurering av Azure-resurser med hjälp av ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>)-APIet. Du kan till exempel konfigurera sku, skydd mot rensning och mer. I följande exempel visas hur du anpassar appkonfigurationsresursen Azure :

builder.AddAzureAppConfiguration("config")
    .ConfigureInfrastructure(infra =>
    {
        var appConfigStore = infra.GetProvisionableResources()
                                  .OfType<AppConfigurationStore>()
                                  .Single();

        appConfigStore.SkuName = "Free";
        appConfigStore.EnablePurgeProtection = true;
        appConfigStore.Tags.Add("ExampleKey", "Example value");
    });

Föregående kod:

• Kedjar ett anrop till ConfigureInfrastructure-API:et:
  • Parametern infra är en instans av den AzureResourceInfrastructure typen.
  • De tillgängliga resurserna hämtas genom att anropa GetProvisionableResources()-metoden.
  • Det enstaka AppConfigurationStore hämtas.
  • AppConfigurationStore.SkuName tilldelas till Free.
  • En tagg läggs till i App Configuration Store med nyckeln ExampleKey och värdet Example value.

Det finns många fler konfigurationsalternativ för att anpassa appkonfigurationsresursen Azure . Mer information finns i Azure.Provisioning.AppConfiguration. Mer information finns i Azure. Anpassning av provisionering.

Använda befintlig Azure appkonfigurationsresurs

Du kan ha ett befintligt Azure appkonfigurationsarkiv som du vill ansluta till. Om du vill använda ett befintligt Azure appkonfigurationsarkiv kan du göra det genom att anropa AsExisting metoden. Den här metoden accepterar konfigurationsarkivet och resursgruppens namn som parametrar och använder den för att ansluta till den befintliga Azure App Configuration Store-resursen.

var builder = DistributedApplication.CreateBuilder(args);

var configName = builder.AddParameter("configName");
var configResourceGroupName = builder.AddParameter("configResourceGroupName");

var appConfig = builder.AddAzureAppConfiguration("config")
                       .AsExisting(configName, configResourceGroupName);

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

builder.Build().Run();

Mer information finns i Använd befintliga Azure resurser.

Ansluta till befintlig Azure App Configuration Store

En alternativ metod för att använda API:erna *AsExisting gör det möjligt att lägga till en anslutningssträng i stället, där AppHost använder konfigurationen för att lösa anslutningsinformationen. Om du vill lägga till en anslutning till ett befintligt Azure appkonfigurationsarkiv anropar du AddConnectionString metoden:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Anslutningssträngen konfigureras i AppHost-konfigurationen, vanligtvis under Användarhemligheter, under avsnittet ConnectionStrings . AppHost matar in den här anslutningssträngen som en miljövariabel i alla beroende resurser, till exempel:

{
    "ConnectionStrings": {
        "config": "https://{store_name}.azconfig.io"
    }
}

Den beroende resursen kan komma åt den inmatade anslutningssträngen genom att anropa metoden GetConnectionString och skicka anslutningsnamnet som parameter, i det här fallet "config". API:et GetConnectionString är en förkortning för IConfiguration.GetSection("ConnectionStrings")[name].

Lägg till Azure appkonfigurationsemulatorresurs

Microsoft tillhandahåller appkonfigurationsemulatorn Azure för utvecklare som vill ha en lokal, enkel implementering av Azure App Configuration-tjänsten att koda och testa mot. I Aspirekan du använda den här emulatorn genom att anropa metoden när du lägger till resursen RunAsEmulator :

var builder = DistributedApplication.CreateBuilder(args);

var appConfig = builder.AddAzureAppConfiguration("config")
                       .RunAsEmulator();

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

builder.Build().Run();

Appkonfigurationsemulatorn Azure är inte installerad på den lokala datorn. I stället är den tillgänglig för Aspire som en container. Metoden RunAsEmulator skapar och startar containern när AppHost börjar använda avbildningen azure-app-configuration/app-configuration-emulator . Mer information finns i Livscykel för containerresurser.

Konfigurera Azure appkonfigurations-emulatorcontainer

Det finns olika konfigurationer tillgängliga för containerresurser. Du kan till exempel konfigurera containerns port, miljövariabler, dess livslängd och mycket mer.

Konfigurera värdporten för appkonfigurationsemulatorn Azure

Som standard Aspire tilldelar en slumpmässig värdport för emulatorcontainern. Om du vill använda en specifik port kedjar du anrop på containerresursverktyget som tillhandahålls av RunAsEmulator metoden enligt följande exempel:

var builder = DistributedApplication.CreateBuilder(args);

var appConfig = builder.AddAzureAppConfiguration("config")
                     .RunAsEmulator(
                         emulator =>
                         {
                             emulator.WithHostPort(28000);
                         });

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

Föregående kod konfigurerar emulatorcontainerns slutpunkt för att lyssna på portar 28000.

Konfigurera Azure appkonfigurationsemulatorn med beständig livslängd

Om du vill konfigurera emulatorcontainern med en beständig livslängd anropar du WithLifetime metoden för emulatorns containerresurs och skickar ContainerLifetime.Persistent:

var builder = DistributedApplication.CreateBuilder(args);

var appConfig = builder.AddAzureAppConfiguration("config")
                     .RunAsEmulator(
                         emulator =>
                         {
                             emulator.WithLifetime(ContainerLifetime.Persistent);
                         });

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

Mer information finns i Livslängd för containerresurser.

Konfigurera Azure appkonfigurationsemulatorn med datavolym

Om du vill lägga till en datavolym i appkonfigurationsemulatorresursen AzureWithDataVolume anropar du metoden på emulatorresursen:

var builder = DistributedApplication.CreateBuilder(args);

var appConfig = builder.AddAzureAppConfiguration("config")
                       .RunAsEmulator(
                           emulator =>
                           {
                               emulator.WithDataVolume();
                           });

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

Datavolymen används för att bevara emulatordata utanför containerns livscykel. Datavolymen monteras på /data sökvägen i emulatorcontainern och när en name parameter inte anges genereras namnet automatiskt från program- och resursnamnen. Mer om datavolymer och varför de föredras framför bind mountsfinns i Docker dokument: Volymer.

Konfigurera Azure Appkonfigurationsemulatorn med databindning

Om du vill lägga till en databindningsmontering till appkonfigurationsemulatorresursen Azure anropar du WithDataBindMount metoden:

var builder = DistributedApplication.CreateBuilder(args);

var appConfig = builder.AddAzureAppConfiguration("config")
                       .RunAsEmulator(
                           emulator =>
                           {
                               emulator.WithDataBindMount("../Emulator/Data");
                           });

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

Databindningsmonteringar förlitar sig på värddatorns filsystem för att bevara emulatordata mellan omstarter av containrar. Databindningsmonteringen är monterad på sökvägen ../Emulator/Data på värddatorn, relativt till AppHost-katalogen (IDistributedApplicationBuilder.AppHostDirectory) i emulatorcontainern. Mer information om databindningspunkter finns i Docker dokumentationen: Bindningspunkter.

Client integration

Kom igång med klientintegrering av AspireAzure App Configuration genom att 📦Aspireinstallera . Microsoft.Extensions.Configuration.AzureAppConfiguration NuGet-paketet i det klientkrävande projektet, det vill: projektet för det program som använder appkonfigurationsklienten. Appkonfigurationsklientens integrering registrerar en CosmosClient instans som du kan använda för att interagera med App Configuration.

dotnet add package Aspire.Microsoft.Extensions.Configuration.AzureAppConfiguration

<PackageReference Include="Aspire.Microsoft.Extensions.Configuration.AzureAppConfiguration"
                  Version="*" />

I Program.cs-filen för ditt klientkonsumerande projekt anropar du AddAzureAppConfiguration-tilläggsmetoden på valfri IHostApplicationBuilder för att registrera de tjänster som krävs för att överföra Azure appkonfigurationsvärden till IConfiguration-instansen för användning via beroendeinsprutningscontainern. Metoden tar en parameter för anslutningsnamn.

builder.AddAzureAppConfiguration(connectionName: "config");

Du kan sedan hämta instansen IConfiguration genom beroendeinjektion. Om du till exempel vill hämta klienten från en exempeltjänst:

public class ExampleService(IConfiguration configuration)
{
    private readonly string _someValue = configuration["SomeKey"];
}

Använda funktionsflaggor

Om du vill använda funktionsflaggor installerar 📦 du NuGet-paketet Microsoft.FeatureManagement :

dotnet add package Microsoft.FeatureManagement

<PackageReference Include="Microsoft.FeatureManagement"
                  Version="*" />

Appkonfiguration läser inte in funktionsflaggor som standard. För att läsa in funktionsflaggor skickar du delegaten Action<AzureAppConfigurationOptions> configureOptions när du anropar builder.AddAzureAppConfiguration.

builder.AddAzureAppConfiguration(
    "config",
    configureOptions: options => options.UseFeatureFlags());

// Register feature management services
builder.Services.AddFeatureManagement();

Du kan sedan använda IFeatureManager för att utvärdera funktionsflaggor i din app. Tänk dig följande exempel ASP.NET Core på minimal API-app:

using Microsoft.Extensions.Hosting;
using Microsoft.FeatureManagement;

var builder = WebApplication.CreateBuilder(args);

builder.AddAzureAppConfiguration(
    "config",
    configureOptions: options => options.UseFeatureFlags());

// Register feature management services
builder.Services.AddFeatureManagement();

var app = builder.Build();

app.MapGet("/", async (IFeatureManager featureManager) =>
{
    if (await featureManager.IsEnabledAsync("NewFeature"))
    {
        return Results.Ok("New feature is enabled!");
    }

    return Results.Ok("Using standard implementation.");
});

app.Run();

Mer information finns i .NET Funktionshantering.

Konfiguration

Appkonfigurationsbiblioteket AspireAzure innehåller flera alternativ för att konfigurera appkonfigurationsanslutningen Azure baserat på kraven och konventionerna i ditt projekt. Appkonfigurationsslutpunkten måste anges, antingen i AzureAppConfigurationSettings.Endpoint eller med hjälp av en anslutningssträng.

Använda en anslutningssträng

När du använder en anslutningssträng från ConnectionStrings konfigurationsavsnittet kan du ange namnet på anslutningssträngen när du anropar builder.AddAzureAppConfiguration():

builder.AddAzureAppConfiguration("config");

Sedan hämtas appkonfigurationsslutpunkten från konfigurationsavsnittet ConnectionStrings . App Configuration Store-URI:n fungerar med AzureAppConfigurationSettings.Credential egenskapen för att upprätta en anslutning. Om inga autentiseringsuppgifter har konfigurerats används DefaultAzureCredential.

{
  "ConnectionStrings": {
    "config": "https://{store_name}.azconfig.io"
  }
}

Använda konfigurationsprovidrar

Appkonfigurationsbiblioteket AspireAzure stöder Microsoft.Extensions.Configuration. Den läser in AzureAppConfigurationSettings från konfigurationen med hjälp av Aspire:Microsoft:Extensions:Configuration:AzureAppConfiguration-nyckeln. Exempel appsettings.json som konfigurerar några av alternativen:

{
  "Aspire": {
    "Microsoft": {
      "Extensions": {
        "Configuration": {
          "AzureAppConfiguration": {
            "Endpoint": "YOUR_APPCONFIGURATION_ENDPOINT_URI"
          }
        }
      }
    }
  }
}

Det fullständiga klientintegreringsschemat JSON för App Configuration finns i ./ConfigurationSchema.json.

Använd inline-delegater

Du kan också skicka delegeringen Action<AzureAppConfigurationSettings> configureSettings för att konfigurera några eller alla alternativ direkt, till exempel för att ange AppKonfiguration-slutpunkt direkt i koden.

builder.AddAzureAppConfiguration(
    "config",
    configureSettings: settings => settings.Endpoint = "http://YOUR_URI");

Observerbarhet och telemetri

Aspire integreringar konfigurerar automatiskt konfigurationer för loggning, spårning och mått, som ibland kallas grundpelarna för observerbarhet. Mer information om integreringsobservabilitet och telemetri finns i Aspire översikten över integreringar. Beroende på säkerhetskopieringstjänsten kanske vissa integreringar bara stöder vissa av dessa funktioner. Vissa integreringar stöder till exempel loggning och spårning, men inte mått. Telemetrifunktioner kan också inaktiveras med hjälp av de tekniker som visas i avsnittet Konfiguration .

Loggning / Skogsavverkning

Integreringen AspireAzure av appkonfigurationen använder följande loggkategorier:

• Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh

Spårning

Appkonfigurationsintegreringen AspireAzure använder inga aktivitetskällor, vilket innebär att ingen spårning är tillgänglig.

Mätvärden

Appkonfigurationsintegreringen AspireAzure stöder för närvarande inte mått.

Se även

• Azure Dokumentation för App Configuration
• Aspire översikt över integreringar
• Aspire Azure översikt över integreringar
• Aspire GitHub Repo