.NET Aspire PostgreSQL integrering

Artikel
01/31/2025

omfattar:Webbhotellintegration och Client integrering

PostgreSQL är ett kraftfullt objektrelationssystem med öppen källkod med många års aktiv utveckling som har gett det ett starkt rykte för tillförlitlighet, funktions robusthet och prestanda. Med integreringen .NET AspirePostgreSQL kan du ansluta till befintliga PostgreSQL databaser eller skapa nya instanser från .NET med docker.io/library/postgres containeravbildningen.

Värdintegrering

PostgreSQL hostingintegration modellerar olika PostgreSQL-resurser som följande typer.

För att få åtkomst till dessa typer och API:er för att uttrycka dem som resurser i din appvärdmiljö för-projektet, installerar du 📦Aspire.Hosting.PostgreSQL NuGet-paket.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.PostgreSQL

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

Mer information finns i dotnet add package eller i Hantera paketberoenden i .NET-applikationer.

Lägg till PostgreSQL serverresurs

I programvärdprojektet anropar du AddPostgres på builder-instansen för att lägga till en PostgreSQL serverresurs och anropar sedan AddDatabase på postgres-instansen för att lägga till en databasresurs enligt följande exempel:

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

När .NET.NET Aspire lägger till en containeravbildning till appvärden, som du ser i föregående exempel med docker.io/library/postgres avbildningen, skapas en ny PostgreSQL serverinstans på den lokala datorn. En referens till din PostgreSQL-server och din PostgreSQL databasinstans (variabeln postgresdb) används för att lägga till ett beroende i ExampleProject. PostgreSQL-serverresursen innehåller standardautentiseringsuppgifter med en username av "postgres" och slumpmässigt genererade password med hjälp av metoden CreateDefaultPasswordParameter.

Metoden WithReference konfigurerar en anslutning i ExampleProject med namnet "messaging". Mer information finns i Livscykel för containerresurser.

Tips

Om du hellre vill ansluta till en befintlig PostgreSQL server anropar du AddConnectionString i stället. Mer information finns i Referera till befintliga resurser.

Lägg till PostgreSQL pgAdmin-resurs

När du lägger till PostgreSQL resurser i builder med metoden AddPostgres kan du länka anrop till WithPgAdmin för att lägga till containern dpage/pgadmin4. Den här containern är en plattformsoberoende klient för PostgreSQL databaser som hanterar en webbaserad administratörsinstrumentpanel. Tänk på följande exempel:

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

Den följande koden lägger till en container baserad på docker.io/dpage/pgadmin4-bilden. Containern används för att hantera PostgreSQL server- och databasresurser. Metoden WithPgAdmin lägger till en container som hanterar en webbaserad administratörsinstrumentpanel för PostgreSQL databaser.

Konfigurera pgAdmin-värdporten

Om du vill konfigurera värdporten för pgAdmin-containern anropar du metoden WithHostPort på PostgreSQL serverresursen. I följande exempel visas hur du konfigurerar värdporten för pgAdmin-containern:

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

Föregående kod lägger till och konfigurerar värdporten för pgAdmin-containern. Värdporten tilldelas annars slumpmässigt.

Lägg till PostgreSQL pgWeb-resurs

När du lägger till PostgreSQL resurser i builder med metoden AddPostgres kan du länka anrop till WithPgWeb för att lägga till sosedoff/pgweb container. Den här containern är en plattformsoberoende klient för PostgreSQL databaser som hanterar en webbaserad administratörsinstrumentpanel. Tänk på följande exempel:

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

Den följande koden lägger till en container baserad på docker.io/sosedoff/pgweb-bilden. Alla registrerade PostgresDatabaseResource-instanser används för att skapa en konfigurationsfil per instans. Varje konfiguration är bunden till katalogen för pgweb containerbokmärken. Mer information finns i PgWeb-dokument: Server anslutningsbokmärken.

Konfigurera pgWeb-värdporten

Om du vill konfigurera värdporten för pgWeb-containern anropar du metoden WithHostPort på PostgreSQL-serverresursen. I följande exempel visas hur du konfigurerar värdporten för pgAdmin-containern:

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

Föregående kod lägger till och konfigurerar värdporten för pgWeb-containern. Värdporten tilldelas annars slumpmässigt.

Lägga till PostgreSQL serverresurs med datavolym

Om du vill lägga till en datavolym i PostgreSQL-serverresursen anropar du metoden WithDataVolume på PostgreSQL serverresursen:

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

Datavolymen används för att bevara PostgreSQL serverdata utanför containerns livscykel. Datavolymen monteras på sökvägen /var/lib/postgresql/data i servercontainern PostgreSQL och om ingen name-parameter anges genereras namnet slumpvis. Mer information om datavolymer och detaljer om varför de föredras framför bindmountsfinns i Docker dokumentation: Volymer.

Lägg till PostgreSQL serverresurs med databindningspunkt

Om du vill lägga till en databindningsmontering till PostgreSQL-serverresursen anropar du metoden WithDataBindMount:

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

Viktig

Data bindningsmonteringar har begränsade funktioner jämfört med volymer, vilket ger bättre prestanda, portabilitet och säkerhet, vilket gör dem mer lämpliga för produktionsmiljöer. Bindningsmonteringar tillåter dock direkt åtkomst och ändring av filer i värdsystemet, perfekt för utveckling och testning där realtidsändringar behövs.

Monteringar av databindningar förlitar sig på värddatorns filsystem för att bevara serverdata PostgreSQL vid omstarter av containrar. Databindningsmontering monteras på C:\PostgreSQL\Data på Windows (eller /PostgreSQL/Data på Unix) på värddatorn i PostgreSQL-servercontainern. Mer information om databindningspunkter finns i Docker dokumentationen: Bindningspunkter.

Lägg till PostgreSQL server-resurs med init-bindmontering

Om du vill lägga till en init-bindningsmontering till PostgreSQL-serverresursen anropar du metoden WithInitBindMount:

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

Init-bindningsmonteringen förlitar sig på värddatorns filsystem för att initiera PostgreSQL-serverdatabasen med containrarna init mapp. Den här mappen används för initiering, körning av körbara gränssnittsskript eller .sql kommandofiler efter att mappen postgres-data har skapats. Init-bindningsmonteringen är monterad på sökvägen C:\PostgreSQL\Init på Windows (eller /PostgreSQL/Init på Unix) på värddatorn i PostgreSQL-servercontainern.

Lägga till PostgreSQL serverresurs med parametrar

När du uttryckligen vill ange användarnamnet och lösenordet som används av containeravbildningen kan du ange dessa autentiseringsuppgifter som parametrar. Tänk dig följande alternativa exempel:

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

Mer information om hur du tillhandahåller parametrar finns i Externa parametrar.

Hosting för integrationskontroller

PostgreSQL värdintegrering lägger automatiskt till en hälsokontroll för PostgreSQL serverresursen. Hälsokontrollen verifierar att PostgreSQL-servern körs och att en anslutning kan upprättas till den.

Integreringen av värdtjänst förlitar sig på 📦 AspNetCore.HealthChecks.Npgsql NuGet-paketet.

Client integrering

Kom igång med .NET AspirePostgreSQL-klientintegrering genom att installera 📦Aspire. Npgsql NuGet-paket i det klientkrävande projektet, dvs. projektet för det program som använder PostgreSQL-klienten. PostgreSQL-klientintegrering registrerar en NpgsqlDataSource- instans som du kan använda för att interagera med PostgreSQL.

.NET CLI
PackageReference

dotnet add package Aspire.Npgsql

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

Lägg till Npgsql-klient

I Program.cs-filen för ditt klientprojekt anropar du AddNpgsqlDataSource-tilläggsmetoden på alla IHostApplicationBuilder för att registrera en NpgsqlDataSource för användning via beroendeinjiceringscontainern. Metoden tar en parameter för anslutningsnamn.

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Tips

Parametern connectionName måste matcha namnet som används när du lägger till PostgreSQL-serverresursen i appvärdprojektet. För mer information, se Lägg till PostgreSQL serverresurs.

När du har lagt till NpgsqlDataSource i byggaren kan du hämta NpgsqlDataSource-instansen med hjälp av dependency injection. Om du till exempel vill hämta datakällobjektet från en exempeltjänst definierar du det som en konstruktorparameter och kontrollerar att klassen ExampleService är registrerad med containern för beroendeinmatning:

public class ExampleService(NpgsqlDataSource dataSource)
{
    // Use dataSource...
}

Mer information om beroendeinmatning finns i .NET beroendeinmatning.

Lägg till nyckelad Npgsql-klient

Det kan finnas situationer där du vill registrera flera NpgsqlDataSource instanser med olika anslutningsnamn. Om du vill registrera nyckelade Npgsql-klienter anropar du metoden AddKeyedNpgsqlDataSource:

builder.AddKeyedNpgsqlDataSource(name: "chat");
builder.AddKeyedNpgsqlDataSource(name: "queue");

Sedan kan du hämta NpgsqlDataSource-instans genom dependency injection. Om du till exempel vill hämta anslutningen från en exempeltjänst:

public class ExampleService(
    [FromKeyedServices("chat")] NpgsqlDataSource chatDataSource,
    [FromKeyedServices("queue")] NpgsqlDataSource queueDataSource)
{
    // Use data sources...
}

Mer information om nyckeltjänster finns i .NET beroendeinjektion: Nyckeltjänster.

Konfiguration

Den .NET AspirePostgreSQL integreringen innehåller flera konfigurationsmetoder och alternativ för att uppfylla kraven och konventionerna i ditt projekt.

Använda en anslutningssträng

När du använder en anslutningssträng från ConnectionStrings-konfigurationsavsnittet kan du ange namnet på anslutningssträngen när du anropar metoden AddNpgsqlDataSource:

builder.AddNpgsqlDataSource("postgresdb");

Sedan hämtas anslutningssträngen från ConnectionStrings-konfigurationsavsnittet:

{
  "ConnectionStrings": {
    "postgresdb": "Host=myserver;Database=postgresdb"
  }
}

Mer information finns i ConnectionString.

Använda konfigurationsprovidrar

.NET Aspire PostgreSQL-integreringen stöder Microsoft.Extensions.Configuration. Den läser in NpgsqlSettings från appsettings.json eller andra konfigurationsfiler med hjälp av Aspire:Npgsql-nyckeln. Exempel appsettings.json som konfigurerar några av alternativen:

I följande exempel visas en appsettings.json fil som konfigurerar några av de tillgängliga alternativen:

{
  "Aspire": {
    "Npgsql": {
      "ConnectionString": "Host=myserver;Database=postgresdb",
      "DisableHealthChecks": false,
      "DisableTracing": true,
      "DisableMetrics": false
    }
  }
}

Det fullständiga PostgreSQL klientintegreringsschemat JSON finns i Aspire. Npgsql/ConfigurationSchema.json.

Använd inline-delegater

Du kan också skicka Action<NpgsqlSettings> configureSettings ombud för att konfigurera vissa eller alla alternativ infogade, till exempel för att inaktivera hälsokontroller:

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

Hälsokontroller

Som standard aktiverar .NET.NET Aspire integreringar hälsokontroller för alla tjänster. Mer information finns i översikten över .NET.NET Aspire integreringar.

Lägger till NpgSqlHealthCheck, som verifierar att kommandon kan köras mot den underliggande Postgres databasen.
Integrerar med HTTP-slutpunkten /health, som anger att alla registrerade hälsokontroller måste godkännas för att appen ska anses vara redo att ta emot trafik.

Observerbarhet och telemetri

.NET .NET Aspire integreringar ställer automatiskt in konfigurationer för loggning, spårning och mått, som ibland kallas grundpelarna för observerbarhet. Mer information om integreringsobservabilitet och telemetri finns i översikten över .NET.NET Aspire integreringar. Beroende på säkerhetskopieringstjänsten kanske vissa integreringar bara stöder vissa av dessa funktioner. Vissa integreringar stöder till exempel loggning och spårning, men inte mått. Telemetrifunktioner kan också inaktiveras med hjälp av de tekniker som visas i avsnittet Configuration.

Skogsavverkning

.NET Aspire PostgreSQL-integreringen använder följande loggkategorier:

Npgsql.Connection
Npgsql.Command
Npgsql.Transaction
Npgsql.Copy
Npgsql.Replication
Npgsql.Exception

Spårning

.NET Aspire PostgreSQL-integreringen genererar följande spårningsaktiviteter med hjälp av OpenTelemetry:

Npgsql

Mätvärden

Integreringen .NET AspirePostgreSQL genererar följande mått med hjälp av OpenTelemetry:

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

Dela via