Freigeben über

.NET Aspire Azure PostgreSQL Integration

  • Artikel

umfasst:Hosting-Integration und Client-Integration

Azure Datenbank für PostgreSQL– Flexible Server ist ein relationaler Datenbankdienst, der auf dem Open Source-Postgres-Datenbankmodul basiert. Es ist ein vollständig verwalteter Datenbank-as-a-Service, der unternehmenskritische Workloads mit vorhersehbarer Leistung, Sicherheit, hoher Verfügbarkeit und dynamischer Skalierbarkeit verarbeiten kann. Die .NET AspireAzurePostgreSQL-Integration bietet eine Möglichkeit, eine Verbindung mit vorhandenen AzurePostgreSQL-Datenbanken herzustellen oder neue Instanzen aus .NET mit dem docker.io/library/postgres Containerimagezu erstellen.

Hosting-Integration

Das .NET AspireAzurePostgreSQL Hostintegrationsmodell bildet einen PostgreSQL flexiblen Server und eine flexible Datenbank vom Typ AzurePostgresFlexibleServerResource und AzurePostgresFlexibleServerDatabaseResource ab. Andere Typen, die in der Hostingintegration inhärent verfügbar sind, werden in den folgenden Ressourcen dargestellt:

Um auf diese Typen und APIs zuzugreifen, um sie als Ressourcen in Ihrem App-Host Projekt auszudrücken, installieren Sie die 📦Aspire. Hosting.Azure.PostgreSQL NuGet-Paket:

dotnet add package Aspire.Hosting.Azure.PostgreSQL

Weitere Informationen finden Sie unter dotnet add package.

Die AzurePostgreSQL-Hosting-Integration hat eine Abhängigkeit von dem -📦-Aspire-Hosting-PostgreSQL--NuGet-Paket, das erweitert wird, um Azurezu unterstützen. Alles, was Sie mit der .NET AspirePostgreSQL Integration und .NET AspirePostgreSQLEntity Framework Core Integration tun können, können Sie auch mit dieser Integration tun.

Serverressource AzurePostgreSQL hinzufügen

Nachdem Sie die .NET AspireAzurePostgreSQL Hostingintegration installiert haben, rufen Sie die AddAzurePostgresFlexibleServer Erweiterungsmethode in Ihrem App-Hostprojekt auf:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddAzurePostgresFlexibleServer("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

Durch den vorherigen Aufruf von AddAzurePostgresFlexibleServer wird die PostgresSQL-Serverressource so konfiguriert, dass sie als AzurePostgres Flexible Serverbereitgestellt wird.

Wichtig

Standardmäßig konfiguriert AddAzurePostgresFlexibleServer die Authentifizierung über Microsoft Entra ID. Dies erfordert Änderungen an Anwendungen, die eine Verbindung mit diesen Ressourcen herstellen müssen. Weitere Informationen finden Sie unter Client Integration.

Trinkgeld

Wenn Sie AddAzurePostgresFlexibleServeraufrufen, wird implizit AddAzureProvisioningaufgerufen, wodurch die Unterstützung zur dynamischen Generierung von Azure-Ressourcen während des App-Starts hinzugefügt wird. Die App muss das entsprechende Abonnement und den entsprechenden Standort konfigurieren. Weitere Informationen finden Sie unter Lokale Bereitstellung: Konfiguration.

Client Integration

Um mit der .NET AspirePostgreSQL-Clientintegration zu beginnen, installieren Sie das 📦Aspire.Npgsql NuGet-Paket im clientnutzenden Projekt, das heißt, dem Projekt für die Anwendung, die den PostgreSQL-Client verwendet. Die PostgreSQL Clientintegration registriert eine NpgsqlDataSource Instanz, die Sie für die Interaktion mit PostgreSQLverwenden können.

dotnet add package Aspire.Npgsql

Hinzufügen des Npgsql-Clients

Rufen Sie in der Program.cs-Datei Ihres clientnutzenden Projekts die AddNpgsqlDataSource-Erweiterungsmethode für jedes IHostApplicationBuilder auf, um eine NpgsqlDataSource für die Verwendung über den Abhängigkeitsinjektionscontainer zu registrieren. Die Methode verwendet einen Verbindungsnamenparameter.

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Trinkgeld

Der parameter connectionName muss mit dem Namen übereinstimmen, der beim Hinzufügen der PostgreSQL Serverressource im App-Hostprojekt verwendet wird. Weitere Informationen finden Sie unter Serverressource hinzufügen PostgreSQL.

Nachdem Sie NpgsqlDataSource zum Generator hinzugefügt haben, können Sie die NpgsqlDataSource Instanz mithilfe der Abhängigkeitseinfügung abrufen. Wenn Sie beispielsweise das Datenquellenobjekt aus einem Beispieldienst abrufen möchten, definieren Sie es als Konstruktorparameter, und stellen Sie sicher, dass die ExampleService Klasse im Container zum Einfügen von Abhängigkeiten registriert ist:

public class ExampleService(NpgsqlDataSource dataSource)
{
    // Use dataSource...
}

Weitere Informationen zur Abhängigkeitsinjektion finden Sie unter .NET Abhängigkeitsinjektion.

Hinzufügen des Npgsql-Clients mit Schlüsseln

Es kann Situationen geben, in denen Sie mehrere NpgsqlDataSource Instanzen mit unterschiedlichen Verbindungsnamen registrieren möchten. Rufen Sie die AddKeyedNpgsqlDataSource-Methode auf, um schlüsselierte Npgsql-Clients zu registrieren:

builder.AddKeyedNpgsqlDataSource(name: "chat");
builder.AddKeyedNpgsqlDataSource(name: "queue");

Anschließend können Sie die NpgsqlDataSource-Instanzen mithilfe von Dependency Injection abrufen. So rufen Sie beispielsweise die Verbindung aus einem Beispieldienst ab:

public class ExampleService(
    [FromKeyedServices("chat")] NpgsqlDataSource chatDataSource,
    [FromKeyedServices("queue")] NpgsqlDataSource queueDataSource)
{
    // Use data sources...
}

Weitere Informationen zu schlüsselbasierten Diensten finden Sie unter .NET Abhängigkeitsinjektion: Dienste mit Schlüsseln.

Konfiguration

Die .NET AspirePostgreSQL-Integration bietet mehrere Konfigurationsmethoden und -optionen, um die Anforderungen und Konventionen Ihres Projekts zu erfüllen.

Verwenden Sie eine Verbindungszeichenfolge

Wenn Sie eine Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings verwenden, können Sie beim Aufrufen der AddNpgsqlDataSource-Methode den Namen der Verbindungszeichenfolge angeben:

builder.AddNpgsqlDataSource("postgresdb");

Anschließend wird die Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings abgerufen:

{
  "ConnectionStrings": {
    "postgresdb": "Host=myserver;Database=postgresdb"
  }
}

Weitere Informationen finden Sie in der ConnectionString.

Verwenden von Konfigurationsanbietern

Die .NET AspirePostgreSQL-Integration unterstützt Microsoft.Extensions.Configuration. Sie lädt die NpgsqlSettings aus appsettings.json oder anderen Konfigurationsdateien mithilfe des Aspire:Npgsql Schlüssels. Beispiel appsettings.json, das einige der Optionen konfiguriert:

Das folgende Beispiel zeigt eine appsettings.json Datei, die einige der verfügbaren Optionen konfiguriert:

{
  "Aspire": {
    "Npgsql": {
      "ConnectionString": "Host=myserver;Database=postgresdb",
      "DisableHealthChecks": false,
      "DisableTracing": true,
      "DisableMetrics": false
    }
  }
}

Für das vollständige PostgreSQL Clientintegration JSON Schema sehen Sie Aspire. Npgsql/ConfigurationSchema.json.

Verwenden von Inlinedelegatn

Sie können auch den Action<NpgsqlSettings> configureSettings Delegat übergeben, um einige oder alle Optionen inline einzurichten, z. B. zum Deaktivieren von Integritätsprüfungen:

builder.AddNpgsqlDataSource(
    "postgresdb",
     static settings => settings.DisableHealthChecks = true);

Client Integrationsgesundheitsprüfungen

Standardmäßig sind bei .NET.NET AspireClient-IntegrationenGesundheitsprüfungen für alle Dienste aktiviert. Ebenso ermöglichen viele .NET.NET AspireHostingintegrationen auch Gesundheitsprüfungsendpunkte. Weitere Informationen finden Sie unter:

  • Fügt die NpgSqlHealthCheckhinzu, die überprüft, ob Befehle erfolgreich für die zugrunde liegende Postgres Datenbank ausgeführt werden können.
  • Integriert in den /health HTTP-Endpunkt, der angibt, dass alle registrierten Gesundheitsprüfungen erfolgreich sein müssen, damit die App bereit ist, Datenverkehr zu akzeptieren.

Observability und Telemetrie

.NET .NET Aspire Integrationen richten automatisch Protokollierungs-, Ablaufverfolgungs- und Metrikkonfigurationen ein, die manchmal als die Säulen der Beobachtbarkeitbezeichnet werden. Weitere Informationen zur Integrationsobservability und Telemetrie finden Sie in der Integrationsübersicht unter .NET.NET Aspire. Abhängig vom Sicherungsdienst unterstützen einige Integrationen möglicherweise nur einige dieser Features. Beispielsweise unterstützen einige Integrationen Protokollierung und Ablaufverfolgung, aber keine Metriken. Telemetriefeatures können auch mithilfe der techniken deaktiviert werden, die im Abschnitt Configuration dargestellt werden.

Protokollierung

Die .NET AspirePostgreSQL-Integration verwendet die folgenden Protokollkategorien:

  • Npgsql.Connection
  • Npgsql.Command
  • Npgsql.Transaction
  • Npgsql.Copy
  • Npgsql.Replication
  • Npgsql.Exception

Verfolgung

Die .NET AspirePostgreSQL-Integration wird die folgenden Verfolgungsaktivitäten mithilfe von OpenTelemetryausgeben:

  • Npgsql

Metriken

Die .NET AspirePostgreSQL Integration gibt die folgenden Metriken mithilfe von OpenTelemetryaus:

  • Npgsql:
    • ec_Npgsql_bytes_written_per_second
    • ec_Npgsql_bytes_read_per_second
    • ec_Npgsql_commands_per_second
    • ec_Npgsql_total_commands
    • ec_Npgsql_current_commands
    • ec_Npgsql_failed_commands
    • ec_Npgsql_prepared_commands_ratio
    • ec_Npgsql_connection_pools
    • ec_Npgsql_multiplexing_average_commands_per_batch
    • ec_Npgsql_multiplexing_average_write_time_per_batch

Hinzufügen eines Azure authentifizierten Clients von Npgsql

Wenn Sie AddAzurePostgresFlexibleServer in Ihrer PostgreSQL Hostingintegration aufrufen, wird standardmäßig das 📦AzureIdentity--NuGet-Paket konfiguriert, um die Authentifizierung zu aktivieren:

dotnet add package Azure.Identity

Die PostgreSQL-Verbindung kann mithilfe der Clientintegration und Azure.Identitygenutzt werden:

builder.AddNpgsqlDataSource(
    "postgresdb", 
    configureDataSourceBuilder: (dataSourceBuilder) =>
{
    if (!string.IsNullOrEmpty(dataSourceBuilder.ConnectionStringBuilder.Password))
    {
        return;
    }

    dataSourceBuilder.UsePeriodicPasswordProvider(async (_, ct) =>
    {
        var credentials = new DefaultAzureCredential();
        var token = await credentials.GetTokenAsync(
            new TokenRequestContext([
                "https://ossrdbms-aad.database.windows.net/.default"
            ]), ct);

        return token.Token;
    },
    TimeSpan.FromHours(24),
    TimeSpan.FromSeconds(10));
});

Im vorherigen Codeausschnitt wird veranschaulicht, wie Sie die DefaultAzureCredential-Klasse aus dem Azure.Identity-Paket verwenden, um sich mit Microsoft Entra ID zu authentifizieren und ein Token abzurufen, um eine Verbindung mit der PostgreSQL-Datenbank herzustellen. Die UsePeriodicPasswordProvider--Methode wird verwendet, um das Token für den Verbindungszeichenfolgen-Generator bereitzustellen.

Siehe auch