.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 ExampleProject
eine 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 ConnectionString
festzulegen:
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
DbContextHealthCheck
hinzu, die die CanConnectAsync-Methode von EF Coreaufruft. Der Name der Gesundheitsprüfung ist der Name des TypsTContext
. - 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 AddAzurePostgresFlexibleServer
Microsoft 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
dotnet add package Azure.Identity
Die PostgreSQL Verbindung kann mithilfe der client Integration und Azure.Identity
genutzt 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.