.NET-Konfigurationsanbieter

Azure App Configuration ist ein verwalteter Dienst, mit dem Entwickler ihre Anwendungskonfigurationen einfach und sicher zentralisieren können. Die .NET-Konfigurationsanbieterbibliothek ermöglicht das Laden der Konfiguration aus einem Azure App-Konfigurationsspeicher auf verwaltete Weise. Diese Clientbibliothek fügt zusätzliche Funktionen über das Azure SDK für .NET hinzu.

Laden der Konfiguration

Der Azure App Configuration .NET-Konfigurationsanbieter ist in das .NET-Konfigurationssystem integriert, sodass Konfigurationswerte einfach aus Ihrem Azure App Configuration Store geladen werden können. Sie können den Anbieter während des Anwendungsstarts hinzufügen und zusammen mit anderen Konfigurationsquellen verwenden.

Installieren Sie das Paket, um den .NET-Konfigurationsanbieter zu verwenden:

dotnet add package Microsoft.Extensions.Configuration.AzureAppConfiguration

Sie rufen die Erweiterungsmethode AddAzureAppConfiguration auf IConfigurationBuilder auf, um Azure App Configuration als Konfigurationsanbieter Ihrer Anwendung hinzuzufügen.

Die Konfigurationsanbieterbibliothek implementiert eine Kombination aus Optionsmuster und Builder-Muster, um eine saubere, deklarative Methode zum Konfigurieren der AzureAppConfigurationOptions bereitzustellen. Die AddAzureAppConfiguration Methode akzeptiert einen Action<AzureAppConfigurationOptions> Delegatparameter, mit dem Sie den Anbieter über eine Fluent-API konfigurieren können.

Um eine Verbindung mit Ihrem Azure App-Konfigurationsspeicher herzustellen, rufen Sie die Connect Methode für die AzureAppConfigurationOptions Instanz auf, die dasselbe Optionsobjekt zurückgibt, um die Methodenkette zu aktivieren.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;
using Azure.Identity;

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
    {
        string endpoint = Environment.GetEnvironmentVariable("AppConfigurationEndpoint");
        options.Connect(new Uri(endpoint), new DefaultAzureCredential());
    });

var config = builder.Build();
Console.WriteLine(config["TestApp:Settings:Message"] ?? "Hello world!");

var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddAzureAppConfiguration(options =>
    {
        string endpoint = Environment.GetEnvironmentVariable("Endpoint");
        options.Connect(new Uri(endpoint), new DefaultAzureCredential());
    });

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;
using Azure.Identity;

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
    {
        string connectionString = Environment.GetEnvironmentVariable("ConnectionString");
        options.Connect(connectionString);
    });

var config = builder.Build();
Console.WriteLine(config["TestApp:Settings:Message"] ?? "Hello world!");

var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddAzureAppConfiguration(options =>
    {
        string connectionString = Environment.GetEnvironmentVariable("ConnectionString");
        options.Connect(connectionString);
    });

Nutzen der Konfiguration

Nachdem Sie den Azure App-Konfigurationsanbieter hinzugefügt haben, können Sie auf verschiedene Arten auf Ihre Konfigurationswerte zugreifen:

1. Direkter Zugriff

Der einfachste Ansatz besteht darin, Werte direkt aus der IConfiguration Instanz abzurufen:

// Directly get the configuration
string message = configuration["TestApp:Settings:Message"];

IConfigurationSection settingsSection = configuration.GetSection("TestApp:Settings");

2. Abhängigkeitsinjektion mit IConfiguration

In Diensten oder Controllern können Sie die IConfiguration Schnittstelle direkt einfügen und verwenden:

public class WeatherService
{
    private readonly IConfiguration _configuration;

    public WeatherService(IConfiguration configuration)
    {
        _configuration = configuration;
    }

    public Task<WeatherForecast> GetForecastAsync()
    {
        // Access configuration values directly from the injected instance
        string apiEndpoint = _configuration["TestApp:Weather:ApiEndpoint"];

        ...

        return Task.FromResult(new WeatherForecast());
    }
}

3. Optionsmuster für eine stark typisierten Konfiguration

// Define a strongly-typed settings class
public class Settings
{
    public string BackgroundColor { get; set; }
    public long FontSize { get; set; }
    public string FontColor { get; set; }
    public string Message { get; set; }
}

builder.Services.Configure<Settings>(builder.Configuration.GetSection("TestApp:Settings"));

Weitere Informationen zum Optionsmuster in .NET finden Sie in der Dokumentation.

JSON-Inhaltstypbehandlung

Sie können JSON-Schlüsselwerte in der App-Konfiguration erstellen. Wenn ein Schlüsselwert mit dem Inhaltstyp "application/json" gelesen wird, wird er vom Konfigurationsanbieter in einzelne Einstellungen innerhalb von IConfiguration vereinfacht. Für weitere Informationen gehen Sie zu Inhaltstyp verwenden, um JSON-Schlüsselwerte in der App-Konfiguration zu speichern.

Laden bestimmter Schlüsselwerte mithilfe von Selektoren

Standardmäßig lädt der Konfigurationsanbieter alle Schlüsselwerte ohne Bezeichnung aus der App-Konfiguration. Sie können Schlüsselwerte selektiv aus Ihrem App-Konfigurationsspeicher laden, indem Sie die Select Methode aufrufen AzureAppConfigurationOptions.

builder.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(endpoint), new DefaultAzureCredential())
        // Load configuration values with prefix "TestApp:" and no label
        .Select("App:Settings:*")
        // Load configuration values with prefix "TestApp:" and "Prod" label
        .Select("App:Settings:*", "Prod")
        // Load configuration values with prefix "TestApp:" and "Prod" label that have the tag "Group" with value "Contoso"
        .Select("App:Settings:*", "Prod", new[] { "Group=Contoso" })
});

Die Select Methode verwendet drei Parameter. Der erste Parameter ist ein Schlüsselfilter, der angibt, welche Schlüssel geladen werden sollen, der zweite Parameter ist ein Bezeichnungsfilter, der angibt, welche Schlüsselwerte mit bestimmten Beschriftungen geladen werden sollen, und der dritte Parameter gibt eine Auflistung von Tagfiltern an, die alle für einen zu ladenden Schlüsselwert vorhanden sein müssen.

Schlüsselfilter

Der Schlüsselfilterparameter bestimmt, welche Konfigurationsschlüssel eingeschlossen werden sollen:

• Genaue Übereinstimmung: Die Verwendung einer bestimmten Zeichenfolge stimmt nur mit Schlüsseln überein, die exakt mit dem Filter übereinstimmen.
• Präfix-Übereinstimmung: Durch das Hinzufügen eines Sternchens (*) am Ende wird ein Präfixfilter erstellt (z. B. werden alle Schlüssel geladen, App:Settings:* die mit "App:Settings:") beginnen.
• Mehrfachtastenauswahl: Die Verwendung eines Kommas (,) ermöglicht die Auswahl mehrerer expliziter Schlüssel (z. B Key1,Key2,Key3. ).
• Reservierte Zeichen: Die Zeichen Sternchen (*), Komma (,) und Backslash (\) sind reserviert und müssen mit einem Backslash versehen werden, wenn sie in Schlüsselnamen verwendet werden (z. B. gibt der Schlüsselfilter a\\b\,\*c* alle Schlüsselwerte zurück, deren Schlüssel mit a\b,*c beginnt.).

Etikettenfilter

Der Parameter "Bezeichnungsfilter" wählt Schlüsselwerte mit einer bestimmten Bezeichnung aus. Wenn nicht angegeben, wird die integrierte Funktion LabelFilter.Null verwendet.

Tag-Filter

Der Parameter "Tagfilter" wählt Schlüsselwerte mit bestimmten Tags aus. Ein Schlüsselwert wird nur geladen, wenn er alle Tags und die entsprechenden Werte enthält, die in den Filtern angegeben sind. Um einen Nullwert für ein tag anzugeben, kann das eingebaute TagValue.Null verwendet werden.

Kürzen des Schlüsselpräfixes

Beim Laden von Konfigurationswerten mit bestimmten Präfixen können Sie die TrimKeyPrefix Methode verwenden, um diese Präfixe aus den Schlüsseln in Ihrer Konfiguration zu entfernen. Dadurch werden klare Konfigurationsschlüssel in Ihrer Anwendung erstellt, während die Organisation im App-Konfigurationsspeicher aufrechterhalten bleibt.

builder.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(endpoint), new DefaultAzureCredential())
        // Load configuration values with prefix "TestApp:" and trim the prefix
        .Select("TestApp:*")
        .TrimKeyPrefix("TestApp:");
});

Wenn ihr App-Konfigurationsspeicher z. B. einen Schlüssel mit dem Namen TestApp:Settings:Messageenthält, kann er in Ihrer Anwendung wie Settings:Message nach dem Kürzen des TestApp: Präfixes zugänglich sein.

Konfigurationseinstellungszuordnung

Beim Laden von Schlüsselwerten aus der Azure App-Konfiguration ruft der Anbieter diese zuerst als ConfigurationSetting Objekte ab, bevor sie dem .NET-Konfigurationssystem hinzugefügt werden. Mit der Map API können Sie diese Einstellungen während dieser Pipeline transformieren, sodass Sie steuern können, wie Konfigurationen in Ihrer Anwendung angezeigt werden.

Die Map-Methode akzeptiert eine Delegatfunktion, die ein ConfigurationSetting-Objekt empfängt. Diese Funktion ermöglicht es Ihnen, das Objekt zu ändern, und gibt ein ValueTask<ConfigurationSetting> zurück. Dies ist besonders hilfreich für Schlüsselnamentransformationen oder Wertformatierungen basierend auf Laufzeitbedingungen.

Das folgende Beispiel veranschaulicht die Verwendung der Map API, um doppelte Unterstriche (__) durch Doppelpunkte (:) in Konfigurationsschlüsseln zu ersetzen. Diese Transformation behält die hierarchische Struktur bei, die von der .NET-Konfiguration erwartet wird, wenn Schlüssel alternative Zeichen in der App-Konfiguration verwenden müssen:

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        .Map((setting) =>
        {
            // Transform keys from format "App__Settings__Message" to "App:Settings:Message"
            setting.Key = setting.Key.Replace("__", ":");
            
            return new ValueTask<ConfigurationSetting>(setting);
        });
});

Konfigurationsaktualisierung

Durch konfigurieren der Aktualisierung kann die Anwendung die neuesten Werte aus dem App-Konfigurationsspeicher abrufen, ohne neu starten zu müssen. Sie können die ConfigureRefresh Methode aufrufen, um die Aktualisierung des Schlüsselwerts zu konfigurieren.

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        // Load all keys that start with `TestApp:` and have no label
        .Select(keyFilter: "TestApp:*", labelFilter: LabelFilter.Null)
        .ConfigureRefresh(refreshOptions => {
            // Trigger full configuration refresh when any selected key changes.
            refreshOptions.RegisterAll()
            // Check for changes no more often than every 60 seconds
                .SetRefreshInterval(TimeSpan.FromSeconds(60));
        });
});

Innerhalb der ConfigureRefresh Methode rufen Sie die RegisterAll Methode auf, um den App-Konfigurationsanbieter anzuweisen, die Konfiguration neu zu laden, wenn eine Änderung in einem der ausgewählten Schlüsselwerte erkannt wird (beginnend mit TestApp: und ohne Bezeichnung).

Sie können der SetRefreshInterval-Methode einen Aufruf hinzufügen, um die Mindestzeit zwischen Konfigurationsaktualisierungen anzugeben. Wenn nicht festgelegt, beträgt das Standardaktualisierungsintervall 30 Sekunden.

Aktualisierung auslösen

Um die Aktualisierung auszulösen, müssen Sie die Methode TryRefreshAsync der IConfigurationRefresher aufrufen. Die Azure App-Konfiguration bietet je nach Anwendungsarchitektur mehrere Muster für die Implementierung.

1. Abhängigkeitsinjektion

Für Anwendungen mit Abhängigkeitsinjektion (einschließlich ASP.NET Core- und Hintergrunddienste) registrieren Sie den Aktualisierungsdienst:

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())            
           .ConfigureRefresh(refreshOptions =>
           {
                refreshOptions.RegisterAll()
                    .SetRefreshInterval(TimeSpan.FromSeconds(60));
           })
});

// Register refresher service with the DI container
builder.Services.AddAzureAppConfiguration();

builder.Services.AddAzureAppConfiguration() fügt den IConfigurationRefreshProvider Dienst dem DI-Container hinzu, der Ihnen den Zugriff auf die Aktualisierungen aller Azure App-Konfigurationsquellen in der Konfiguration der Anwendung ermöglicht.

ASP.NET Core-Anwendungen

Für ASP.NET Core-Anwendungen können Sie das Microsoft.Azure.AppConfiguration.AspNetCore Paket verwenden, um eine anforderungsgesteuerte Konfigurationsaktualisierung mit einer integrierten Middleware zu erzielen.

dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore

Rufen Sie nach der Registrierung des Diensts UseAzureAppConfiguration auf, um AzureAppConfigurationRefreshMiddleware zur App-Pipeline hinzuzufügen und die Konfiguration bei eingehenden Anforderungen automatisch zu aktualisieren.

...

// Call the AddAzureAppConfiguration to add refresher service to the DI container
builder.Services.AddAzureAppConfiguration();

var app = builder.Build();

// Call the app.UseAzureAppConfiguration() method as early as appropriate in your request pipeline so another middleware doesn't skip it
app.UseAzureAppConfiguration();

// Continue with other middleware registration
app.UseRouting();
...

Das AzureAppConfigurationRefreshMiddleware überprüft automatisch auf Konfigurationsänderungen im konfigurierten Aktualisierungsintervall. Dieser Ansatz ist effizient, da er nur aktualisiert wird, wenn beide Bedingungen erfüllt sind: eine HTTP-Anforderung wird empfangen, und das Aktualisierungsintervall ist abgelaufen.

Hintergrunddienste

Für Hintergrunddienste können Sie den IConfigurationRefresherProvider Dienst einfügen und die registrierten Aktualisierer manuell auffrischen.

public class Worker : BackgroundService
{
    private readonly IConfiguration _configuration;
    private readonly IEnumerable<IConfigurationRefresher> _refreshers;

    public Worker(IConfiguration configuration, IConfigurationRefresherProvider refresherProvider)
    {
        _configuration = configuration;
        _refreshers = refresherProvider.Refreshers;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        foreach (IConfigurationRefresher refresher in _refreshers)
        {
            refresher.TryRefreshAsync();
        }

        ...
    }
}

2. Direkter Zugriff

Für Anwendungen, die keine Abhängigkeitsinjektion verwenden, können Sie die Aktualisierung direkt aus den Optionen abrufen:

IConfigurationRefresher refresher = null;
var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())            
           .ConfigureRefresh(refreshOptions =>
           {
               refreshOptions.RegisterAll();
           });

    // Store the refresher for later use
    refresher = options.GetRefresher();
});

IConfiguration config = builder.Build();

// Later in your code, trigger refresh when needed
if (refresher != null)
{
    await refresher.TryRefreshAsync()
}

Console.WriteLine(config["TestApp:Settings:Message"]);

Aktualisieren bei einem Sentinelschlüssel

Ein Sentinel-Schlüssel ist ein Schlüssel, den Sie aktualisieren, nachdem Sie die Änderung aller anderen Schlüssel abgeschlossen haben. Der Konfigurationsanbieter überwacht den Sentinelschlüssel anstelle aller ausgewählten Schlüsselwerte. Wird eine Änderung erkannt, werden alle Konfigurationswerte von Ihrer App aktualisiert.

Dieser Ansatz ist nützlich, wenn mehrere Schlüsselwerte aktualisiert werden. Wenn Sie den Sentinel-Schlüssel erst aktualisieren, nachdem alle anderen Konfigurationsänderungen abgeschlossen wurden, stellen Sie sicher, dass die Konfiguration der Anwendung nur einmal neu geladen wird, wobei die Konsistenz beibehalten wird.

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        // Load all keys that start with `TestApp:` and have no label
        .Select(keyFilter: "TestApp:*", labelFilter: LabelFilter.Null)
        .ConfigureRefresh(refreshOptions => {
            // Trigger full configuration refresh only if the `SentinelKey` changes.
            refreshOptions.Register("SentinelKey", refreshAll: true);
        });
});

Weitere Informationen zur Aktualisierungskonfiguration finden Sie im Lernprogramm: Verwenden der dynamischen Konfiguration in einer ASP.NET Core-App.

Featureflag

Featurekennzeichnungen in der Azure App-Konfiguration bieten eine moderne Möglichkeit, die Verfügbarkeit von Features in Ihren Anwendungen zu steuern. Im Gegensatz zu regulären Konfigurationswerten müssen Featurekennzeichnungen mithilfe der UseFeatureFlags Methode explizit geladen werden. Sie können FeatureFlagOptions so konfigurieren, dass bestimmte Feature-Flags mithilfe von Selektoren geladen und die Aktualisierungsintervalle für Feature-Flags festgelegt werden.

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        .UseFeatureFlags(featureFlagOptions => {
            // Load feature flags with prefix "TestApp:" and "dev" label
            featureFlagOptions.Select("TestApp:*", "dev")
            // Check for changes no more often than every 60 seconds
                .SetRefreshInterval(TimeSpan.FromSeconds(60));
        });
});

Innerhalb der UseFeatureFlags Methode rufen Sie die Select Methode auf, um Featurekennzeichnungen selektiv zu laden. Sie können Schlüsselfilter, Bezeichnungsfilter und Tagfilter verwenden, um die Featurekennzeichnungen auszuwählen, die Sie laden möchten. Wenn keine Select-Methode aufgerufen wird, lädt UseFeatureFlags standardmäßig alle Featureflags ohne Bezeichnung.

Abgesehen von Schlüsselwerten werden Featureflags automatisch für die Aktualisierung registriert, ohne dass explizite ConfigureRefresh-Aufruf erforderlich sind. Sie können die Mindestzeit zwischen Aktualisierungen von Feature Flags durch die Methode SetRefreshInterval angeben. Das Standardaktualisierungsintervall beträgt 30 Sekunden.

Funktionsverwaltung

Die Featureverwaltungsbibliothek bietet eine Möglichkeit, Anwendungsfunktionen basierend auf Featurekennzeichnungen zu entwickeln und verfügbar zu machen. Die Featureverwaltungsbibliothek ist so konzipiert, dass sie mit der Konfigurationsanbieterbibliothek zusammenarbeitet. Installieren Sie das Paket Microsoft.FeatureManagement:

dotnet add package Microsoft.FeatureManagement

Sie können AddFeatureManagement aufrufen, um IVariantFeatureManager und verwandte Dienste im DI-Container zu registrieren. Mit dieser Registrierung wird die Funktionalität von Feature Flags in der gesamten Anwendung über die Abhängigkeitsinjektion verfügbar gemacht.

using Microsoft.FeatureManagement;

...

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential());
    // Use feature flags
    options.UseFeatureFlags();
});

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

Im folgenden Beispiel wird die Verwendung des Feature-Manager-Diensts durch Abhängigkeitsinjektion veranschaulicht:

public class WeatherForecastController : ControllerBase
{
    private readonly IFeatureManager _featureManager;

    public WeatherForecastController(IVariantFeatureManager featureManager)
    {
        _featureManager = featureManager;
    }

    [HttpGet]
    public async Task<IActionResult> Get()
    {
        // Check if a feature flag is enabled
        if (await _featureManager.IsEnabledAsync("WeatherForecast"))
        {
            var forecast = GenerateWeatherForecast();
            return Ok(forecast);
        }
        
        return NotFound("Weather forecast feature is not available");
    }
}

Weitere Informationen zur Verwendung der Feature-Management-Bibliothek finden Sie im Feature-Flag-Schnellstart.

Telemetriedaten für Feature-Flags

Wenn die Telemetrie mit Featurekennzeichnung aktiviert ist, fügt der Azure App-Konfigurationsanbieter zusätzliche Eigenschaften ein, um Telemetriedaten zu kennzeichnen. Diese Eigenschaften bieten mehr Kontext zum Feature-Flag und deren Auswertung:

• AllocationID: Ein eindeutiger Bezeichner, der den Status der Zuordnung des Featurekennzeichens darstellt.
• ETag: Das aktuelle ETag für das Feature-Flag.
• FeatureFlagReference: Ein Verweis auf das Feature-Flag im Format von <your_store_endpoint>kv/<feature_flag_key>. Wenn eine Bezeichnung vorhanden ist, enthält der Verweis ihn als Abfrageparameter: <your_store_endpoint>kv/<feature_flag_key>?label=<feature_flag_label>.

Das vollständige Schema finden Sie in der App-Konfigurations-Feature-Auswertungsereignis-Schemadefinition. Weitere Informationen zur Verwendung der Feature-Flag-Telemetrie finden Sie in der Anleitung zum Aktivieren der Telemetrie für Feature-Flags.

Key Vault-Verweis

Azure App Configuration unterstützt das Verweisen auf Geheimnisse, die in Azure Key Vault gespeichert sind. Sie können in App Configuration Schlüssel erstellen, die in Key Vault gespeicherten Geheimnissen zugeordnet sind. Die Geheimnisse werden sicher in Key Vault gespeichert, auf sie kann aber nach dem Laden wie auf jede andere Konfiguration zugegriffen werden.

Die Konfigurationsanbieterbibliothek ruft Key Vault-Verweise ab, wie dies auch für alle anderen Schlüssel der Fall ist, die in App Configuration gespeichert sind. Da der Client die Schlüssel als Key Vault-Verweise erkennt, verfügt er über einen eindeutigen Inhaltstyp, und der Client stellt eine Verbindung mit Key Vault bereit, um seine Werte für Ihre Anwendung abzurufen.

Verbindung mit Key Vault herstellen

Sie müssen die ConfigureKeyVault Methode aufrufen, um zu konfigurieren, wie eine Verbindung mit Key Vault hergestellt wird. Der Azure App-Konfigurationsanbieter bietet mehrere Möglichkeiten zur Authentifizierung und zum Zugriff auf Ihre Key Vault-Geheimnisse.

1. Registrieren der SecretClient Instanz

Sie können angegebene SecretClient-Instanzen registrieren, um Schlüsseltresorverweise für geheime Schlüssel aus dem zugeordneten Schlüsseltresor aufzulösen.

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

...

var secretClient = new SecretClient(new Uri(vaultUri), new DefaultAzureCredential());

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())  
        .ConfigureKeyVault(kv =>
        {
            // Register a SecretClient instance
            kv.Register(secretClient);
        });
});

2. Verwenden von Anmeldeinformationen

Sie können die Anmeldeinformationen festlegen, die für die Authentifizierung bei Schlüsseltresorn verwendet werden, für die keine SecretClient registriert sind.

using Azure.Identity;

...

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())  
        .ConfigureKeyVault(kv =>
        {
            // Use DefaultAzureCredential to access all Key Vaults
            kv.SetCredential(new DefaultAzureCredential());
        });
});

3. Verwenden des benutzerdefinierten geheimen Resolvers

Sie können auch SetSecretResolver aufrufen, um einen benutzerdefinierten Secret Resolver hinzuzufügen, der verwendet wird, wenn keine registrierten SecretClient verfügbar sind oder die bereitgestellten Anmeldeinformationen nicht im Key Vault authentifiziert werden. Diese Methode akzeptiert eine Delegatfunktion, die einen Key Vault-URI in einen geheimen Wert aufgelöst. Das folgende Beispiel veranschaulicht die Verwendung eines Geheimnis-Resolvers, der während der Entwicklung ein Geheimnis aus Umgebungsvariablen abruft und Fallbackwerte nutzt, falls das Geheimnis nicht aus dem Key Vault abgerufen werden kann.

var secretClient = new SecretClient(new Uri(vaultUri), new DefaultAzureCredential());

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())  
        .ConfigureKeyVault(kv =>
        {
            // Add a custom secret resolver function
            kv.SetSecretResolver(async (Uri secretUri) =>
            {                
                if (builder.Environment.IsDevelopment())
                {
                    return Environment.GetEnvironmentVariable("FALLBACK_SECRET_VALUE");
                }

                try 
                {
                    var secret = await secretClient.GetSecretAsync(secretName);
                    return secret.Value;
                }
                catch (Exception ex)
                {
                    logger.LogWarning($"Failed to retrieve secret from {secretUri}: {ex.Message}");
                    
                    return Environment.GetEnvironmentVariable("FALLBACK_SECRET_VALUE");
                }
            });
        });
});

Key Vault-Geheimnisaktualisierung

Mit der Azure App-Konfiguration können Sie geheime Aktualisierungsintervalle unabhängig vom Aktualisierungszyklus der Konfiguration konfigurieren. Dies ist für die Sicherheit von entscheidender Bedeutung, da der Key Vault-Referenz-URI in der App-Konfiguration unverändert bleibt, der zugrunde liegende Schlüssel im Key Vault jedoch möglicherweise im Rahmen Ihrer Sicherheitspraktiken rotiert wird.

Um sicherzustellen, dass Ihre Anwendung immer die aktuellsten geheimen Werte verwendet, konfigurieren Sie die SetSecretRefreshInterval Methode. Dadurch wird der Anbieter gezwungen, frische geheime Werte aus Key Vault abzurufen, wenn:

• Ihre Anwendung ruft IConfigurationRefresher.TryRefreshAsync auf
• Das konfigurierte Aktualisierungsintervall für den geheimen Schlüssel ist abgelaufen.

Dieser Mechanismus funktioniert auch dann, wenn im App Configuration-Speicher keine Änderungen erkannt werden, um sicherzustellen, dass Ihre Anwendung mit rotierten geheimen Schlüsseln synchronisiert bleibt.

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        .ConfigureKeyVault(kv =>
        {
            kv.SetCredential(new DefaultAzureCredential());

            // Option 1: Set refresh interval for specific secrets
            kv.SetSecretRefreshInterval("ApiKey", TimeSpan.FromHours(12)); 
            
            // Option 2: Set a global refresh interval for all secrets with no refresh interval specified
            kv.SetSecretRefreshInterval(TimeSpan.FromHours(24));
        })
        .ConfigureRefresh(refreshOptions => refreshOptions.RegisterAll());
});

Weitere Informationen zur Verwendung der Key Vault-Referenz finden Sie im Lernprogramm: Verwenden von Key Vault-Verweisen in einer ASP.NET Core-App.

Schnappschuss

Snapshot ist eine benannte, unveränderliche Teilmenge der Schlüsselwerte eines App-Konfigurationsspeichers. Die Schlüsselwerte, aus denen eine Momentaufnahme besteht, werden während der Erstellungszeit durch die Verwendung von Schlüssel- und Bezeichnungsfiltern ausgewählt. Nachdem eine Momentaufnahme erstellt wurde, bleiben die darin enthaltenen Schlüsselwerte garantiert unverändert.

Sie können aufrufen SelectSnapshot , um Schlüsselwerte aus einer Momentaufnahme zu laden.

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential());
    // Select an existing snapshot by name. This adds all of the key-values and feature flags from the snapshot to this application's configuration.
    options.SelectSnapshot("SnapshotName");
});

Informationen zur Verwendung von Momentaufnahmen finden Sie unter „Erstellen und Verwenden von Momentaufnahmen“.

Schnappschussreferenz

Eine Momentaufnahmereferenz ist eine Konfigurationseinstellung, die auf eine Momentaufnahme im selben App-Konfigurationsspeicher verweist. Beim Laden löst der Anbieter ihn und fügt alle Schlüsselwerte aus dieser Momentaufnahme hinzu. Die Verwendung von Momentaufnahmen ermöglicht das Wechseln zwischen Momentaufnahmen zur Laufzeit, im Gegensatz zu SelectSnapshot("..."), das Codeänderungen und/oder Neustarts erfordert, um zu einer neuen Momentaufnahme zu wechseln.

Neustart-Versuch

Beim Laden der Konfiguration handelt es sich um einen kritischen Pfadvorgang beim Starten der Anwendung. Um die Zuverlässigkeit zu gewährleisten, implementiert der Azure App-Konfigurationsanbieter während der anfänglichen Konfigurationslast einen robusten Wiederholungsmechanismus. Dadurch wird Ihre Anwendung vor vorübergehenden Netzwerkproblemen geschützt, die andernfalls den erfolgreichen Start verhindern können.

Sie können dieses Verhalten mithilfe der ConfigureStartupOptions Methode anpassen:

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        .ConfigureStartupOptions(startupOptions =>
        {
            // Set the time-out for the initial configuration load
            startupOptions.Timeout = TimeSpan.FromSeconds(60);
        });
});

Georeplikation

Informationen zur Verwendung der Georeplikation finden Sie unter Aktivieren der Georeplikation.

Verteilte Ablaufverfolgung

Der Azure App Configuration .NET-Anbieter enthält integrierte Unterstützung für die verteilte Ablaufverfolgung, sodass Sie Konfigurationsvorgänge in Ihrer gesamten Anwendung überwachen und beheben können. Der Anbieter macht eine ActivitySource namens "Microsoft.Extensions.Configuration.AzureAppConfiguration" verfügbar, die Activity für Schlüsselvorgänge wie laden der Konfiguration und Aktualisierung der Konfiguration startet.

Im folgenden Beispiel wird veranschaulicht, wie Sie OpenTelemetry konfigurieren, um verteilte Traces zu erfassen und zu überwachen, die vom Konfigurationsanbieter erzeugt werden:

List<Activity> exportedActivities = new();
builder.Services.AddOpenTelemetry()
    .WithTracing(traceBuilder => {
        traceBuilder.AddSource(["Microsoft.Extensions.Configuration.AzureAppConfiguration"]);
            .AddInMemoryExporter(exportedActivities)
    });

Weitere Informationen zu OpenTelemetry in .NET finden Sie in der OpenTelemetry .NET-Dokumentation.

Integritätsprüfung

Der .NET-Anbieter für die Azure App-Konfiguration unterstützt .NET-App-Integritätsprüfungen. Um Integritätsprüfungen zu aktivieren, können Sie die Methode AddAzureAppConfiguration() auf IHealthChecksBuilder aufrufen. So wird ein IHealthCheck mit dem Standardregistrierungsnamen "Microsoft.Extensions.Configuration.AzureAppConfiguration" hinzugefügt.

builder.Configuration.AddAzureAppConfiguration(options => 
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential()));

builder.Services.AddHealthChecks()
    .AddAzureAppConfiguration();

Der .NET-Anbieter wird als fehlerhaft betrachtet, wenn der letzte Lade- oder Aktualisierungsversuch fehlgeschlagen ist.

Weitere Informationen zu Integritätsprüfungen in .NET finden Sie in der Dokumentation zur .NET-Integritätsüberwachung.

Nächste Schritte

Um zu erfahren, wie Sie den .NET-Konfigurationsanbieter verwenden, fahren Sie mit dem folgenden Lernprogramm fort.