.NET Aspire PostgreSQL-Integration

Artikel
01/23/2025

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

Die PostgreSQL Hosting-Integration modelliert einen PostgreSQL-Server als PostgresServerResource-Typ. 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 der Serverressource PostgreSQL

Rufen Sie in Ihrem App-Hostprojekt AddPostgres für die builder Instanz auf, um eine PostgreSQL Serverressource hinzuzufügen, und rufen Sie dann AddDatabase in der postgres Instanz 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 PostgreSQL Serverinstanz auf dem lokalen Computer erstellt. Ein Verweis auf den PostgreSQL-Server und die PostgreSQL-Datenbankinstanz (die postgresdb Variable) werden verwendet, um dem ExampleProjecteine Abhängigkeit hinzuzufügen. Die Serverressource PostgreSQL enthält Standard-Anmeldeinformationen mit einem username von "postgres" und zufällig generiertem 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 PostgreSQL Server herstellen 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 ein plattformübergreifender Client für PostgreSQL-Datenbanken, der ein web-basiertes Administrator-Dashboard bietet. 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 ein plattformübergreifender Client für PostgreSQL-Datenbanken, der ein webbasiertes Administrations-Dashboard bereitstellt. 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 PostgreSQL Serverressource mit Datenvolume

Um der PostgreSQL Serverressource ein Datenvolume hinzuzufügen, rufen Sie die WithDataVolume Methode für die PostgreSQL Serverressource auf:

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 PostgreSQL Serverdaten außerhalb des Lebenszyklus des Containers zu speichern. Das Datenvolume wird am /var/lib/postgresql/data Pfad im PostgreSQL Servercontainer bereitgestellt 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 der Serverressource PostgreSQL mit Datenbindemontage

Rufen Sie die WithDataBindMount-Methode auf, um der PostgreSQL Serverressource eine Datenbindung 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.

Datenbind-Mounts basieren auf dem Dateisystem des Hostcomputers, um die PostgreSQL-Serverdaten bei Containerneustarts beizubehalten. Die Datenbindungseinrichtung wird im PostgreSQL-Servercontainer auf dem Hostcomputer im Pfad C:\PostgreSQL\Data unter Windows (oder /PostgreSQL/Data auf Unix) bereitgestellt. Weitere Informationen zu Datenbindungsmounts finden Sie in den Docker Dokumentationen: Bind-Mounts.

Hinzufügen von PostgreSQL-Serverressource mit Init-Bind-Mount

Rufen Sie die WithInitBindMount-Methode auf, um der Serverressource PostgreSQL ein Init-Bind-Mount 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 Bind-Bereitstellung basiert auf dem Dateisystem des Hostcomputers, um die PostgreSQL Serverdatenbank mit den Containern init Ordner zu initialisieren. Dieser Ordner wird für die Initialisierung verwendet, wobei alle ausführbaren Shellskripts oder .sql Befehlsdateien ausgeführt werden, nachdem der Ordners mit Postgres-Daten erstellt wurde. Die Init-Bind-Mount wird an C:\PostgreSQL\Init unter Windows (oder an /PostgreSQL/Init auf Unix) Pfad des Hostcomputers im PostgreSQL-Servercontainer montiert.

Fügen Sie PostgreSQL-Server-Ressource mit Parametern hinzu

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 PostgreSQL Serverressource hinzu. Die Funktionsprüfung überprüft, ob der PostgreSQL-Server läuft und ob eine Verbindung hergestellt werden kann.

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

Client Integration

Um mit der .NET AspirePostgreSQL-Clientintegration zu beginnen, installieren Sie das 📦AspireNpgsql NuGet-Paket im Client-verwendenen Projekt, das heißt, das 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.

.NET CLI
PackageReference

dotnet add package Aspire.Npgsql

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

Hinzufügen des Npgsql-Clients

Rufen Sie in der Program.cs Datei Ihres verbraucherorientierten Projekts die AddNpgsqlDataSource Erweiterungsmethode auf einem beliebigen IHostApplicationBuilder auf, um eine NpgsqlDataSource für die Verwendung über den Dependency Injection-Container 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 Serverressourcehinzufü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 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
    }
  }
}

Das vollständige PostgreSQL Clientintegration 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="*" />

Fügen Sie die Serverressource AzurePostgreSQL hinzu

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

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

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.

Hinzufügen des authentifizierten Npgsql-Clients Azure

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

Freigeben über

.NET Aspire PostgreSQL-Integration

Hosting-Integration

Hinzufügen der Serverressource PostgreSQL

Hinzufügen PostgreSQL pgAdmin-Ressource

Hinzufügen der PostgreSQL pgWeb-Ressource

Hinzufügen PostgreSQL Serverressource mit Datenvolume

Hinzufügen der Serverressource PostgreSQL mit Datenbindemontage

Hinzufügen von PostgreSQL-Serverressource mit Init-Bind-Mount

Fügen Sie PostgreSQL-Server-Ressource mit Parametern hinzu

Hosten von Integritätsprüfungen für Integration

Client Integration

Hinzufügen des Npgsql-Clients

Hinzufügen des Npgsql-Clients mit Schlüsseln

Konfiguration

Verwenden Sie eine Verbindungszeichenfolge

Konfigurationsanbieter verwenden

Verwenden von Inlinedelegatn

Gesundheitschecks

Observability und Telemetrie

Protokollierung

Verfolgung

Kennzahlen

Azure PostgreSQL-Hosting-Integration

Fügen Sie die Serverressource AzurePostgreSQL hinzu

Hinzufügen des authentifizierten Npgsql-Clients Azure

Siehe auch

Zusätzliche Ressourcen