.NET Aspire PostgreSQL-Integration

Artikel
12/12/2024

umfasst:Hostingintegration und Client Integration

PostgreSQL ist ein leistungsfähiges, Open-Source-objektrelationales Datenbanksystem mit langjähriger aktiver Entwicklung, was ihm einen starken Ruf für Zuverlässigkeit, Funktionsvielfalt und Leistung verdient hat. Die .NET AspirePostgreSQL-Integration bietet eine Möglichkeit, eine Verbindung mit vorhandenen PostgreSQL-Datenbanken herzustellen oder neue Instanzen aus .NET mit dem docker.io/library/postgres Containerimagezu erstellen.

Hosting-Integration

Das PostgreSQL Hostintegrationsmodell bildet ein PostgreSQLserver als den PostgresServerResource Typ ab. Um auf diesen Typ und diese APIs zuzugreifen, mit denen Sie ihn zu Ihrem 📦Aspire.Hosting.PostgreSQL NuGet-Paket im Projekt App-Host hinzufügen können.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.PostgreSQL

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

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

Hinzufügen einer PostgreSQLserver Ressource

Rufen Sie in Ihrem App-Hostprojekt AddPostgres in der builder Instanz auf, um eine PostgreSQLserver Ressource hinzuzufügen, und rufen Sie dann AddDatabase für die instanz postgres auf, um eine Datenbankressource hinzuzufügen, wie im folgenden Beispiel gezeigt:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Wenn .NET.NET Aspire dem App-Host ein Containerimage hinzufügt, wie im vorherigen Beispiel mit dem docker.io/library/postgres-Image gezeigt, wird eine neue PostgreSQLserver Instanz auf dem lokalen Computer erstellt. Ein Verweis auf Ihre PostgreSQLserver und Ihre PostgreSQL-Datenbankinstanz (die postgresdb-Variable) wird verwendet, um dem ExampleProjecteine Abhängigkeit hinzuzufügen. Die PostgreSQLserver-Ressource enthält Standardanmeldeinformationen mit einem username von "postgres" und zufällig generierten password mithilfe der CreateDefaultPasswordParameter-Methode.

Die WithReference-Methode konfiguriert eine Verbindung im ExampleProject namens "messaging". Weitere Informationen finden Sie unter Containerressourcenlebenszyklus.

Trinkgeld

Wenn Sie lieber eine Verbindung mit einem vorhandenen PostgreSQLserverherstellen möchten, rufen Sie stattdessen AddConnectionString auf. Weitere Informationen finden Sie unter Referenzieren vorhandener Ressourcen.

Hinzufügen PostgreSQL pgAdmin-Ressource

Beim Hinzufügen von PostgreSQL Ressourcen zum builder mit der AddPostgres-Methode können Sie Aufrufe an WithPgAdmin verketten, um den dpage/pgadmin4 Container hinzuzufügen. Dieser Container ist eine plattformübergreifende client für PostgreSQL Datenbanken, das ein webbasiertes Administratordashboard bereitstellt. Betrachten Sie das folgende Beispiel:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgAdmin();

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

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

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

Der vorangehende Code fügt einen Container basierend auf dem docker.io/dpage/pgadmin4 Image hinzu. Der Container wird verwendet, um die PostgreSQL,server und Datenbankressourcen zu verwalten. Die WithPgAdmin-Methode fügt einen Container hinzu, der einem webbasierten Administratordashboard für PostgreSQL Datenbanken dient.

Hinzufügen der PostgreSQL pgWeb-Ressource

Beim Hinzufügen von PostgreSQL-Ressourcen zum builder können Sie mit der AddPostgres-Methode Aufrufe an WithPgWeb verknüpfen, um den sosedoff/pgweb-Container hinzuzufügen. Dieser Container ist eine plattformübergreifende client für PostgreSQL Datenbanken, die ein webbasiertes Administratordashboard dient. Betrachten Sie das folgende Beispiel:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgWeb();

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

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

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

Der vorangehende Code fügt einen Container basierend auf dem docker.io/sosedoff/pgweb Image hinzu. Alle registrierten PostgresDatabaseResource Instanzen werden verwendet, um eine Konfigurationsdatei pro Instanz zu erstellen, und jede Config ist an das Lesezeichenverzeichnis des pgweb Containers gebunden. Weitere Informationen finden Sie unter PgWeb-Dokumente: Server Verbindungsmarken.

Hinzufügen einer PostgreSQLserver-Ressource mit Datenvolumen

Rufen Sie die WithDataVolume-Methode für die PostgreSQLserver-Ressource auf, um der PostgreSQLserver Ressource ein Datenvolume hinzuzufügen:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithDataVolume(isReadOnly: false);

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

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

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

Das Datenvolume wird verwendet, um die PostgreSQLserver Daten außerhalb des Lebenszyklus des Containers zu speichern. Das Datenvolume wird im /var/lib/postgresql/data Pfad im Container PostgreSQLserver gemountet und wenn kein name Parameter angegeben wird, wird der Name zufällig generiert. Weitere Informationen zu Datenvolumes und Details dazu, warum sie gegenüber Bind-Mountsbevorzugt werden, siehe Docker-Dokumentation: Volumes.

Hinzufügen PostgreSQLserver Ressource mit Datenbindungs-Bereitstellung

Rufen Sie die WithDataBindMount-Methode auf, um eine Datenbindung an die PostgreSQLserver-Ressource hinzuzufügen.

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithDataBindMount(
                          source: @"C:\PostgreSQL\Data",
                          isReadOnly: false);

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

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

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

Wichtig

Daten--Bindungsmounts haben eingeschränkte Funktionalität im Vergleich zu Volumes, die eine bessere Leistung, Portabilität und Sicherheit bieten, was sie für Produktionsumgebungen besser geeignet macht. Bind-Mounts ermöglichen jedoch direkten Zugriff auf Dateien auf dem Hostsystem und deren Änderung, ideal für Entwicklung und Tests, in denen Echtzeitänderungen erforderlich sind.

Datenbindungs-Bereitstellungen basieren auf dem Dateisystem des Hostcomputers, um die PostgreSQLserver Daten über Containerneustarts hinweg beizubehalten. Die Datenbindungsbereitstellung wird auf dem C:\PostgreSQL\Data unter Windows (oder /PostgreSQL/Data auf Unix) Pfad auf dem Hostcomputer im container PostgreSQLserver bereitgestellt. Weitere Informationen zu Datenbindungsmounts finden Sie in den Docker Dokumentationen: Bind-Mounts.

Fügen Sie die PostgreSQLserver-Ressource mit einem Init-Bind-Mount hinzu.

Rufen Sie die WithInitBindMount-Methode auf, um eine init bind mount an die PostgreSQLserver-Ressource hinzuzufügen:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithInitBindMount(@"C:\PostgreSQL\Init");

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

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

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

Die Init-Einbindung basiert auf dem Dateisystem des Hostcomputers, um die PostgreSQLserver Datenbank mit dem init Ordner der Container zu initialisieren. Dieser Ordner wird für die Initialisierung verwendet, wobei alle ausführbaren Shellskripts oder .sql Befehlsdateien ausgeführt werden, nachdem der ordner postgres-data erstellt wurde. Die Init-Bindung wird auf dem C:\PostgreSQL\Init-Pfad unter Windows (oder /PostgreSQL/Init auf Unix) auf dem Hostcomputer im PostgreSQLserver-Container eingebunden.

Ressource PostgreSQLserver mit Parametern hinzufügen

Wenn Sie explizit den Benutzernamen und das Kennwort angeben möchten, die vom Containerimage verwendet werden, können Sie diese Anmeldeinformationen in Form von Parametern bereitstellen. Betrachten Sie das folgende alternative Beispiel:

var builder = DistributedApplication.CreateBuilder(args);

var username = builder.AddParameter("username", secret: true);
var password = builder.AddParameter("password", secret: true);

var postgres = builder.AddPostgres("postgres", username, password);
var postgresdb = postgres.AddDatabase("postgresdb");

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

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

Weitere Informationen zum Bereitstellen von Parametern finden Sie unter externe Parameter.

Hosten von Integritätsprüfungen für Integration

Die PostgreSQL Hostingintegration fügt automatisch eine Integritätsprüfung für die PostgreSQLserver Ressource hinzu. Die Gesundheitsprüfung überprüft, ob die PostgreSQLserver läuft und ob eine Verbindung hergestellt werden kann.

Die Hostingintegration basiert auf dem 📦 AspNetCore.HealthChecks.Npgsql NuGet-Paket.

Client Integration

Um die Integration von .NET AspirePostgreSQLclient zu starten, installieren Sie das 📦AspireNpgsql NuGet-Paket im client-verbrauchenden Projekt, das heißt im Projekt für die Anwendung, die PostgreSQLclientnutzt. Die PostgreSQLclient-Integration registriert eine NpgsqlDataSource Instanz, die Sie für die Interaktion mit PostgreSQLverwenden können.

.NET CLI
PackageReference-

dotnet add package Aspire.Npgsql

<PackageReference Include="Aspire.Npgsql" Version="*" />

Npgsql client hinzufügen

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

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Tipp

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

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 von keyed Npgsql client

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 der Abhängigkeitseinfügung 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: schlüsselbasierte Dienste.

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.

Konfigurationsanbieter verwenden

Die .NET AspirePostgreSQL-Integration unterstützt Microsoft.Extensions.Configuration. Es lädt NpgsqlSettings aus appsettings.json oder anderen Konfigurationsdateien mithilfe des Schlüssels Aspire:Npgsql. 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
    }
  }
}

Die vollständige PostgreSQLclient Integration JSON Schema finden Sie unter Aspire. Npgsql/ConfigurationSchema.json.

Verwenden von Inlinedelegatn

Sie können auch die Action<NpgsqlSettings> configureSettings-Delegierten übergeben, um einige oder alle Optionen direkt zu konfigurieren, z. B. um Integritätsprüfungen zu deaktivieren.

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

Gesundheitschecks

Standardmäßig aktivieren Integrationen .NET.NET Aspire Gesundheitsprüfungen für alle Dienste. Weitere Informationen finden Sie unter .NET.NET Aspire Integrationsübersicht.

Fügt den NpgSqlHealthCheckhinzu, der ü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 eingetragenen Gesundheitsprüfungen bestehen müssen, damit die App als bereit für den Empfang von Datenverkehr betrachtet wird.

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 unter .NET.NET Aspire Integrationsübersicht. Abhängig vom unterstützenden Dienst könnten einige Integrationen nur einige der Funktionen unterstützen. 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 gibt die folgenden Ablaufverfolgungsaktivitäten mithilfe von OpenTelemetryaus:

Npgsql

Kennzahlen

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

Azure PostgreSQL-Hosting-Integration

Um Ihre PostgreSQL-Ressourcen auf Azurebereitzustellen, installieren Sie das 📦Aspire.Hosting.Azure.PostgreSQL NuGet-Paket.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.PostgreSQL

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

Azure PostgreSQL server Ressource hinzufügen

Nachdem Sie die .NET AspireAzurePostgreSQL-Hosting-Integration installiert haben, rufen Sie die AddAzurePostgresFlexibleServer-Erweiterungsmethode im 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);

Der vorherige Aufruf von AddAzurePostgresFlexibleServer konfiguriert die PostgresSQL-server-Ressource, die als AzurePostgres Flexible Serverbereitgestellt werden soll.

Wichtig

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

Fügen Sie Azure authentifizierten Npgsql client hinzu

Wenn Sie AddAzurePostgresFlexibleServer in Ihrer PostgreSQL Hostingintegration aufrufen, wird standardmäßig 📦Azurekonfiguriert. Identity NuGet-Paket zum Aktivieren der Authentifizierung:

.NET CLI-
PackageReference

dotnet add package Azure.Identity

<PackageReference Include="Azure.Identity"
                  Version="*" />

Die PostgreSQL-Verbindung kann mithilfe der client-Integration 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.

Freigeben über

.NET Aspire PostgreSQL-Integration

Hosting-Integration

Hinzufügen einer PostgreSQLserver Ressource

Hinzufügen PostgreSQL pgAdmin-Ressource

Hinzufügen der PostgreSQL pgWeb-Ressource

Hinzufügen einer PostgreSQLserver-Ressource mit Datenvolumen

Hinzufügen PostgreSQLserver Ressource mit Datenbindungs-Bereitstellung

Fügen Sie die PostgreSQLserver-Ressource mit einem Init-Bind-Mount hinzu.

Ressource PostgreSQLserver mit Parametern hinzufügen

Hosten von Integritätsprüfungen für Integration

Client Integration

Npgsql client hinzufügen

Hinzufügen von keyed Npgsql client

Konfiguration

Verwenden Sie eine Verbindungszeichenfolge

Konfigurationsanbieter verwenden

Verwenden von Inlinedelegatn

Gesundheitschecks

Observability und Telemetrie

Protokollierung

Verfolgung

Kennzahlen

Azure PostgreSQL-Hosting-Integration

Azure PostgreSQL server Ressource hinzufügen

Fügen Sie Azure authentifizierten Npgsql client hinzu

Siehe auch

Zusätzliche Ressourcen