Freigeben über


.NET Aspire PostgreSQL Entity Framework Core integration

umfasst:Hosting-Integration und Client-Integration

PostgreSQL ist ein leistungsfähiges, Open-Source-objektrelationales Datenbanksystem mit langjähriger aktiver Entwicklung, die ihm einen starken Ruf für Zuverlässigkeit, umfangreiche Funktionen und Leistung eingebracht hat. Die .NET AspirePostgreSQLEntity Framework Core-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.

Integration von Hosting

Die PostgreSQL Hosting-Integration modelliert ein PostgreSQLserver als Typ PostgresServerResource. Um auf diesen Typ und die APIs zuzugreifen, mit denen Sie ihn zu Ihrem 📦Aspire.Hosting.PostgreSQL NuGet-Paket im -App-Host--Projekt hinzufügen können.

dotnet add package Aspire.Hosting.PostgreSQL

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

Ressource hinzufügen PostgreSQLserver

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 Standard-Anmeldeinformationen mit einem username-Wert von "postgres" und zufällig generierten password unter Verwendung der CreateDefaultPasswordParameter-Methode.

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

Tipp

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

pgAdmin-Ressource PostgreSQL hinzufügen

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, die ein webbasiertes Administratordashboard dient. 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 mit der AddPostgres-Methode können Sie Aufrufe an WithPgWeb verketten, um den sosedoff/pgweb-Container hinzuzufügen. Dieser Container ist ein plattformübergreifender client für PostgreSQL Datenbanken, der ein webbasiertes Administratordashboard verwaltet. 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 Konfiguration ist an das pgweb Container-Lesezeichenverzeichnis gebunden. Weitere Informationen finden Sie unter PgWeb-Dokumente: Server Verbindungsmarken.

Hinzufügen PostgreSQLserver Ressource mit Datenvolume

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 Datenvolumen wird verwendet, um die PostgreSQLserver Daten über den Lebenszyklus des Containers hinaus zu speichern. Das Datenvolumen wird im /var/lib/postgresql/data Pfad im Container PostgreSQLserver bereitgestellt und wenn kein name Parameter angegeben wird, wird der Name zufällig generiert. Weitere Informationen zu Volumes und Details, warum sie gegenüber Bind-Mountsbevorzugt werden, finden Sie in der Dokumentation Docker: Volumes.

Hinzufügen der Ressource PostgreSQLserver mit Datenbind-Mount

Rufen Sie die WithDataBindMount-Methode auf, um der PostgreSQLserver-Ressource eine Datenbindungs-Bereitstellung 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--Bindemounts- haben eine eingeschränkte Funktionalität im Vergleich zu -Volumes-, die eine bessere Leistung, Portabilität und Sicherheit bieten und somit für Produktionsumgebungen besser geeignet sind. Bind-Mounts ermöglichen jedoch direkten Zugriff auf und Änderungen von Dateien auf dem Hostsystem, was ideal für Entwicklung und Tests ist, bei 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 Daten-Bind-Mounts finden Sie unter Docker-Dokumentation: Bind Mounts.

Fügen Sie 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-Bind-Mount 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. Der Init-Bind-Mount ist unter Windows an C:\PostgreSQL\Init (oder an /PostgreSQL/Init auf Unix) auf dem Hostcomputer im PostgreSQLserver-Container montiert.

Eine PostgreSQLserver Ressource 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 als Parameter angeben. 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 Hosting-Integration fügt automatisch eine Gesundheitsprüfung für die PostgreSQLserver Ressource hinzu. Die Gesundheitsprüfung überprüft, ob die PostgreSQLserver ausgeführt wird und dass eine Verbindung zu ihr hergestellt werden kann.

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

Client Integration

Installieren Sie die 📦Aspire, um mit der .NET AspirePostgreSQLEntity Framework Coreclient-Integration zu beginnen. Npgsql.EntityFrameworkCore.PostgreSQL NuGet-Paket im projekt client-verbrauchend, d. h. das Projekt für die Anwendung, die die PostgreSQLclientverwendet. Die .NET AspirePostgreSQLEntity Framework Coreclient Integration registriert Ihre gewünschten DbContext Unterklasseninstanzen, die Sie für die Interaktion mit PostgreSQLverwenden können.

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

Npgsql-Datenbankkontext hinzufügen

Rufen Sie in der Datei Program.cs Ihres client-verbrauchenden Projekts die AddNpgsqlDbContext-Erweiterungsmethode bei einem IHostApplicationBuilder auf, um Ihre DbContext-Unterklasse für die Verwendung im Dependency Injection Container zu registrieren. Die Methode verwendet einen Verbindungsnamenparameter.

builder.AddNpgsqlDbContext<YourDbContext>(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 YourDbContext zum Generator hinzugefügt haben, können Sie die YourDbContext 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(YourDbContext context)
{
    // Use context...
}

Weitere Informationen zur Abhängigkeits-Injektion finden Sie unter .NET Abhängigkeits-Injektion.

Hinzufügen des Npgsql-Datenbankkontexts mit Anreicherung

Rufen Sie die Methode EnrichNpgsqlDbContext auf, um die DbContext durch zusätzliche Dienste wie automatische Wiederholungen, Funktionsüberprüfungen, Protokollierung und Telemetrie zu erweitern.

builder.EnrichNpgsqlDbContext<YourDbContext>(
    connectionName: "postgresdb",
    configureSettings: settings =>
    {
        settings.DisableRetry = false;
        settings.CommandTimeout = 30;
    });

Der settings-Parameter ist eine Instanz der NpgsqlEntityFrameworkCorePostgreSQLSettings Klasse.

Konfiguration

Die .NET AspirePostgreSQLEntity Framework Core 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, geben Sie beim Aufrufen der AddNpgsqlDbContext-Methode den Namen der Verbindungszeichenfolge an:

builder.AddNpgsqlDbContext<MyDbContext>("pgdb");

Die Verbindungszeichenfolge wird aus dem Konfigurationsabschnitt ConnectionStrings abgerufen:

{
  "ConnectionStrings": {
    "pgdb": "Host=myserver;Database=test"
  }
}

Der EnrichNpgsqlDbContext wird den ConnectionStrings Konfigurationsabschnitt nicht verwenden, da erwartet wird, dass zum Zeitpunkt des Aufrufs ein DbContext registriert wird.

Weitere Informationen finden Sie im ConnectionString.

Verwenden von Konfigurationsanbietern

Die .NET AspirePostgreSQLEntity Framework Core-Integration unterstützt Microsoft.Extensions.Configuration. Sie lädt die NpgsqlEntityFrameworkCorePostgreSQLSettings aus Konfigurationsdateien wie appsettings.json mithilfe des Aspire:Npgsql:EntityFrameworkCore:PostgreSQL-Schlüssels. Wenn Sie Ihre Konfigurationen im Abschnitt Aspire:Npgsql:EntityFrameworkCore:PostgreSQL eingerichtet haben, können Sie die Methode einfach aufrufen, ohne Parameter zu übergeben.

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

{
  "Aspire": {
    "Npgsql": {
      "EntityFrameworkCore": {
        "PostgreSQL": {
          "ConnectionString": "Host=myserver;Database=postgresdb",
          "DbContextPooling": true,
          "DisableHealthChecks": true,
          "DisableTracing": true
        }
      }
    }
  }
}

Die vollständige PostgreSQLEntity Framework Coreclient Integration des JSON Schemas finden Sie unter Aspire. Npgsql.EntityFrameworkCore.PostgreSQL/ConfigurationSchema.json.

Verwenden Sie Inline-Delegaten

Sie können auch den Action<NpgsqlEntityFrameworkCorePostgreSQLSettings> Delegate übergeben, um einige oder alle Optionen inline einzurichten, z. B. um die ConnectionStringfestzulegen:

builder.AddNpgsqlDbContext<YourDbContext>(
    "pgdb",
    static settings => settings.ConnectionString = "<YOUR CONNECTION STRING>");

Konfigurieren mehrerer DbContext-Klassen

Wenn Sie mehrere DbContext mit unterschiedlicher Konfiguration registrieren möchten, können Sie den Namen des $"Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:{typeof(TContext).Name}"-Konfigurationsabschnitts verwenden. Die json-Konfiguration würde wie folgt aussehen:

{
  "Aspire": {
    "Npgsql": {
      "EntityFrameworkCore": {
        "PostgreSQL": {
          "ConnectionString": "<YOUR CONNECTION STRING>",
          "DbContextPooling": true,
          "DisableHealthChecks": true,
          "DisableTracing": true,
          "AnotherDbContext": {
            "ConnectionString": "<ANOTHER CONNECTION STRING>",
            "DisableTracing": false
          }
        }
      }
    }
  }
}

Anschließend würde das Aufrufen der AddNpgsqlDbContext-Methode mit dem AnotherDbContext-Typ-Parameter die Einstellungen aus dem Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:AnotherDbContext-Abschnitt laden.

builder.AddNpgsqlDbContext<AnotherDbContext>();

Gesundheitschecks

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

Standardmäßig wird die .NET AspirePostgreSQLEntity Framework Core Integration wie folgt behandelt:

  • Fügt DbContextHealthCheckhinzu, die die CanConnectAsync-Methode von EF Coreaufruft. Der Name der Gesundheitsprüfung ist der Name des Typs TContext.
  • Integriert mit dem /health HTTP-Endpunkt, der angibt, dass alle registrierten Integritätsprüfungen bestanden werden müssen, damit die Anwendung als bereit zur Annahme von Datenverkehr gilt.

Beobachtbarkeit 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 Integrations-Observability und Telemetrie finden Sie unter .NET.NET Aspire Integrationsübersicht. Abhängig vom unterstützenden Dienst unterstützen einige Integrationen möglicherweise nur einige dieser Funktionen. 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 AspirePostgreSQLEntity Framework Core Integration verwendet die folgenden Protokollkategorien:

  • Microsoft.EntityFrameworkCore.ChangeTracking
  • Microsoft.EntityFrameworkCore.Database.Command
  • Microsoft.EntityFrameworkCore.Database.Connection
  • Microsoft.EntityFrameworkCore.Database.Transaction
  • Microsoft.EntityFrameworkCore.Infrastructure
  • Microsoft.EntityFrameworkCore.Infrastructure
  • Microsoft.EntityFrameworkCore.Migrations
  • Microsoft.EntityFrameworkCore.Model
  • Microsoft.EntityFrameworkCore.Model.Validation
  • Microsoft.EntityFrameworkCore.Query
  • Microsoft.EntityFrameworkCore.Update

Nachverfolgung

Die .NET AspirePostgreSQLEntity Framework Core Integration wird die folgenden Ablaufverfolgungen mithilfe von OpenTelemetryausgeben:

  • Npgsql

Metriken

Die .NET AspirePostgreSQLEntity Framework Core Integration gibt die folgenden Metriken mithilfe von OpenTelemetryaus:

  • Microsoft.EntityFrameworkCore:

    • ec_Microsoft_EntityFrameworkCore_active_db_contexts
    • ec_Microsoft_EntityFrameworkCore_total_queries
    • ec_Microsoft_EntityFrameworkCore_queries_per_second
    • ec_Microsoft_EntityFrameworkCore_total_save_changes
    • ec_Microsoft_EntityFrameworkCore_save_changes_per_second
    • ec_Microsoft_EntityFrameworkCore_compiled_query_cache_hit_rate
    • ec_Microsoft_Entity_total_execution_strategy_operation_failures
    • ec_Microsoft_E_execution_strategy_operation_failures_per_second
    • ec_Microsoft_EntityFramew_total_optimistic_concurrency_failures
    • ec_Microsoft_EntityF_optimistic_concurrency_failures_per_second
  • 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 für Azurebereitzustellen, installieren Sie das 📦Aspire.Hosting.Azure.PostgreSQL NuGet-Paket:

dotnet add package Aspire.Hosting.Azure.PostgreSQL

Hinzufügen AzurePostgreSQLserver ressourcen

Nachdem Sie die Hostingintegration .NET AspireAzurePostgreSQL installiert haben, rufen Sie in Ihrem App-Hostprojekt die Erweiterungsmethode AddAzurePostgresFlexibleServer 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 stellt AddAzurePostgresFlexibleServerMicrosoft Entra ID Authentifizierung ein. Dies erfordert Änderungen an Anwendungen, die eine Verbindung mit diesen Ressourcen herstellen müssen. Weitere Informationen finden Sie bei -Client-Integration.

Füge Azure authentifiziertes Npgsql client hinzu

Standardmäßig wird, wenn Sie in Ihrer -Hostingintegration aufrufen, das NuGet-Paket Identity von konfiguriert, um die Authentifizierung zu aktivieren.

dotnet add package Azure.Identity

Die PostgreSQL Verbindung kann mithilfe der client Integration und Azure.Identitygenutzt werden:

builder.AddNpgsqlDbContext<YourDbContext>(
    "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