Auf Englisch lesen

Teilen über

.NET Aspire PostgreSQL-Integration

  • Artikel

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 Integration von PostgreSQL hostet verschiedene PostgreSQL-Ressourcen als folgenden Typen.

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

.NET CLI 
dotnet add package Aspire.Hosting.PostgreSQL

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:

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

Tipp

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:

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

Konfigurieren des pgAdmin-Hostports

Rufen Sie zum Konfigurieren des Hostports für den pgAdmin-Container die WithHostPort-Methode für die PostgreSQL Serverressource auf. Das folgende Beispiel zeigt, wie Sie den Hostport für den pgAdmin-Container konfigurieren:

C# 
var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgAdmin(pgAdmin => pgAdmin.WithHostPort(5050));

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

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

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

Der vorangestellte Code fügt den Hostport für den pgAdmin-Container hinzu und konfiguriert ihn. Der Hostport wird andernfalls zufällig zugewiesen.

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 web-basiertes Administrator-Dashboard bietet. Betrachten Sie das folgende Beispiel:

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

Konfigurieren des pgWeb-Hostports

Rufen Sie zum Konfigurieren des Hostports für den pgWeb-Container die WithHostPort-Methode für die PostgreSQL Serverressource auf. Das folgende Beispiel zeigt, wie Sie den Hostport für den pgAdmin-Container konfigurieren:

C# 
var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgAdmin(pgWeb => pgWeb.WithHostPort(5050));

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 den Hostport für den pgWeb-Container hinzu und konfiguriert ihn. Der Hostport wird andernfalls zufällig zugewiesen.

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:

C# 
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 PostgreSQL-Methode auf, um der WithDataBindMount Serverressource eine Datenbindung hinzuzufügen:

C# 
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 C:\PostgreSQL\Data-Servercontainer auf dem Hostcomputer im Pfad /PostgreSQL/Data unter Windows (oder Unix auf PostgreSQL) 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 PostgreSQL-Methode auf, um der Serverressource WithInitBindMount ein Init-Bind-Mount hinzuzufügen.

C# 
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:

C# 
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 
dotnet add package Aspire.Npgsql

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.

C# 
builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Tipp

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 PostgreSQLhinzufügen .

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:

C# 
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:

C# 
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:

C# 
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:

C# 
builder.AddNpgsqlDataSource("postgresdb");

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

JSON 
{
  "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:

JSON 
{
  "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.

C# 
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 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 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 Tracing-Aktivitä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

Siehe auch