.NET Aspire PostgreSQL integráció

Tartalmazza: Üzemeltetési integráció és Client integráció

PostgreSQL egy hatékony, nyílt forráskódú objektum-relációs adatbázis-rendszer, amely sok éves aktív fejlesztéssel rendelkezik, amely erős hírnévre tett szert a megbízhatóság, a funkciók robusztussága és a teljesítmény tekintetében. A .NET AspirePostgreSQL integráció lehetővé teszi a meglévő PostgreSQL adatbázisokhoz való csatlakozást, vagy új példányok létrehozását a .NET-ból a docker.io/library/postgres tárolóképfájllal.

Üzemeltetési integráció

A PostgreSQL integráció különféle PostgreSQL erőforrásokat modellez a következő típusokként.

• PostgresServerResource
• PostgresDatabaseResource
• PgAdminContainerResource
• PgWebContainerResource

Ha hozzá szeretne férni ezekhez a típusokhoz és API-khoz, hogy erőforrásként kifejezze őket a alkalmazásgazda projektben, telepítse a 📦Aspire.Hosting.PostgreSQL NuGet csomagot:

dotnet add package Aspire.Hosting.PostgreSQL

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

További információért lásd: dotnet add package vagy Csomagfüggőségek kezelése .NET alkalmazásokban.

PostgreSQL erőforrás hozzáadása a kiszolgálóhoz

Az alkalmazásgazdaprojektben hívja meg a AddPostgres-példány builder, hogy adjon hozzá egy PostgreSQL kiszolgálóerőforrást, majd hívja meg a AddDatabase a postgres-példányon, hogy adjon hozzá egy adatbázis-erőforrást az alábbi példában látható módon:

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

Amikor .NET.NET Aspire egy konténerképet ad hozzá az alkalmazás gazdagépéhez, ahogyan az a docker.io/library/postgres-konténerkép előző példájában is látható, létrehoz egy új PostgreSQL szerverpéldányt a helyi gépen. A PostgreSQL kiszolgálóra és a PostgreSQL adatbázispéldányra (a postgresdb változóra) mutató hivatkozások a ExampleProjectfüggőségének hozzáadására szolgálnak. A PostgreSQL kiszolgálóerőforrás alapértelmezett hitelesítő adatokat tartalmaz, username"postgres" és véletlenszerűen generált password a CreateDefaultPasswordParameter metódus használatával.

A WithReference metódus konfigurál egy kapcsolatot a ExampleProject nevű "messaging". További információért lásd: Tároló erőforrás életciklus.

PostgreSQL pgAdmin-erőforrás hozzáadása

Amikor a PostgreSQL erőforrásokat a builder-hez a AddPostgres metódussal ad hozzá, akkor a WithPgAdmin hívások láncolásával hozzáadhatja a dpage/pgadmin4 tárolót. Ez a tároló egy platformfüggetlen ügyfél PostgreSQL adatbázisokhoz, amely egy webes rendszergazdai irányítópultot szolgál ki. Vegye figyelembe a következő példát:

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

Az előző kód hozzáad egy tárolót a docker.io/dpage/pgadmin4 képfájl alapján. A tároló a PostgreSQL kiszolgáló- és adatbázis-erőforrások kezelésére szolgál. A WithPgAdmin metódus egy olyan tárolót ad hozzá, amely webes rendszergazdai irányítópultot szolgál ki PostgreSQL adatbázisokhoz.

A pgAdmin hosztport konfigurálása

A pgAdmin tároló gazdagépportjának konfigurálásához hívja meg a WithHostPort metódust a PostgreSQL kiszolgálóerőforráson. Az alábbi példa bemutatja, hogyan konfigurálhatja a gazdaportot a pgAdmin tárolóhoz:

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

Az előző kód hozzáadja és konfigurálja a host portot a pgAdmin konténerhez. A hosztport egyébként véletlenszerűen kerül hozzárendelésre.

PostgreSQL pgWeb-erőforrás hozzáadása

Ha PostgreSQL erőforrásokat ad hozzá a builder a AddPostgres módszerrel, a WithPgWeb hívások láncolásával hozzáadhatja a sosedoff/pgweb tárolót. Ez a tároló egy platformfüggetlen ügyfél PostgreSQL adatbázisokhoz, amely egy webes rendszergazdai irányítópultot szolgál ki. Vegye figyelembe a következő példát:

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

Az előző kód hozzáad egy tárolót a docker.io/sosedoff/pgweb képfájl alapján. Az összes regisztrált PostgresDatabaseResource példány egy konfigurációs fájl példányonkénti létrehozására szolgál, és minden konfiguráció a pgweb tároló könyvjelző-könyvtárához van kötve. További információért lásd a PgWeb-dokumentumokat: Server kapcsolati könyvjelzők.

A pgWeb-gazdagép portjának konfigurálása

A pgWeb-tároló gazdagépportjának konfigurálásához hívja meg a WithHostPort metódust a PostgreSQL kiszolgálóerőforráson. Az alábbi példa bemutatja, hogyan konfigurálhatja a gazdaportot a pgAdmin tárolóhoz:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

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

Az előző kód hozzáadja és konfigurálja a pgWeb-konténer host portját. A hosztport egyébként véletlenszerűen kerül hozzárendelésre.

Adjon hozzá PostgreSQL szerverkiszolgálói erőforrást adatmennyiséggel

Ha adatkötetet szeretne hozzáadni a PostgreSQL kiszolgálóerőforráshoz, hívja meg a WithDataVolume metódust a PostgreSQL kiszolgálóerőforráson:

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

Az adatkötet a tároló életciklusán kívüli PostgreSQL kiszolgálóadatok megőrzésére szolgál. Az adatkötet a /var/lib/postgresql/data kiszolgálótároló PostgreSQL elérési útjára van csatlakoztatva, és ha nincs megadva name paraméter, a rendszer véletlenszerűen hozza létre a nevet. További információk az adatmennyiségekről és arról, hogy miért részesítik előnyben őket a bind mount-okhelyett, lásd a Docker dokumentációt: Kötetek.

PostgreSQL szerver erőforrás hozzáadása adatok csatolásával

Ha adatkötési csatlakoztatást szeretne hozzáadni a PostgreSQL kiszolgálóerőforráshoz, hívja meg a WithDataBindMount metódust:

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

Az adatmegkötések a gazdagép fájlrendszerére támaszkodnak, hogy a tároló újraindításakor megőrizzék a PostgreSQL kiszolgáló adatait. Az adatkötés csatlakoztatása a Windows C:\PostgreSQL\Data (vagy /PostgreSQL/DataUnix) gazdaszámítógépének PostgreSQL kiszolgálótárolójában található elérési útjára van csatlakoztatva. Az adatkötési csatlakoztatásokkal kapcsolatos további információkért lásd Docker dokumentumokat: Kötési csatlakoztatások.

PostgreSQL kiszolgálói erőforrás hozzáadása bindelt csatolással inicializáláskor

Ha init bind-csatlakoztatást szeretne hozzáadni a PostgreSQL kiszolgálóerőforráshoz, hívja meg a WithInitBindMount metódust:

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

Az init csatolás a hosztgép fájlrendszerére támaszkodik, hogy inicializálja a PostgreSQL kiszolgálóadatbázist a konténerek init mappájával. Ez a mappa inicializálásra szolgál, és futtat minden végrehajtható rendszerhéj-szkriptet vagy .sql parancsfájlt a postgres-data mappa létrehozása után. Az inicializálási kötés csatlakoztatása a C:\PostgreSQL\Init windowsos (vagy /PostgreSQL/InitUnix) útvonalon van csatlakoztatva a gazdagépen a PostgreSQL kiszolgálótárolóban.

PostgreSQL szerver erőforrás hozzáadása paraméterekkel

Ha explicit módon meg szeretné adni a tárolólemezkép által használt felhasználónevet és jelszót, paraméterekként megadhatja ezeket a hitelesítő adatokat. Tekintse meg a következő alternatív példát:

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

További információ a paraméterek megadásáról: Külső paraméterek.

Integrációs állapotellenőrzések üzemeltetése

A PostgreSQL üzemeltetési integráció automatikusan hozzáad egy állapotellenőrzést a PostgreSQL kiszolgálói erőforráshoz. Az állapot-ellenőrzés ellenőrzi, hogy a PostgreSQL kiszolgáló fut-e, és hogy létre lehet-e hozni vele kapcsolatot.

Az üzemeltetési integráció a 📦 AspNetCore.HealthChecks.Npgsql NuGet-csomagra támaszkodik.

Client integráció

Az .NET AspirePostgreSQL ügyfélintegráció megkezdéséhez telepítse az Npgsql 📦Aspireügyfelet használó projektben, vagyis abban a projektben, amelyik az PostgreSQL ügyfelet használó alkalmazásé. A PostgreSQL ügyfélintegráció egy olyan NpgsqlDataSource példányt regisztrál, amelyet használhat a PostgreSQL-hoz való interakcióhoz.

dotnet add package Aspire.Npgsql

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

Npgsql-ügyfél hozzáadása

Az ügyféloldali projekt Program.cs fájljában hívja meg a AddNpgsqlDataSource bővítménymetódusát bármelyik IHostApplicationBuilder-n a NpgsqlDataSource regisztrálásához a függőséginjektáló konténeren keresztül történő használatra. A metódus egy kapcsolatnévparamétert használ.

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Miután hozzáadta a NpgsqlDataSource elemet az építőhöz, a NpgsqlDataSource példányt függőséginjektálással kaphatja meg. Ha például egy példaszolgáltatásból szeretné lekérni az adatforrás-objektumot, konstruktorparaméterként határozza meg, és győződjön meg arról, hogy a ExampleService osztály regisztrálva van a függőséginjektálási tárolóban:

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

További információ a függőséginjektálásról: .NET függőséginjektálás.

Kulcsos Npgsql-ügyfél hozzáadása

Előfordulhatnak olyan helyzetek, amikor több NpgsqlDataSource példányt szeretne regisztrálni különböző kapcsolatnevekkel. A kulcsos Npgsql-ügyfelek regisztrálásához hívja meg a AddKeyedNpgsqlDataSource metódust:

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

Ezután függőséginjektálással lekérheti a NpgsqlDataSource példányokat. Ha például egy példaszolgáltatásból szeretné lekérni a kapcsolatot:

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

További információ a kulcsos szolgáltatásokról: .NET függőséginjektálás: Kulcsos szolgáltatások.

Konfiguráció

A .NET AspirePostgreSQL integráció több konfigurációs módszert és lehetőséget kínál a projekt követelményeinek és konvencióinak teljesítéséhez.

Kapcsolati karakterlánc használata

Ha a ConnectionStrings konfigurációs szakaszból használ kapcsolati sztringet, megadhatja a kapcsolati sztring nevét a AddNpgsqlDataSource metódus meghívásakor:

builder.AddNpgsqlDataSource("postgresdb");

Ezután a kapcsolati karakterlánc a ConnectionStrings konfigurációs szakaszból kerül lekérésre.

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

További információért lásd a ConnectionString.

Konfigurációs szolgáltatók használata

A .NET AspirePostgreSQL integráció támogatja a Microsoft.Extensions.Configuration. Betölti a NpgsqlSettings-t a appsettings.json-ből vagy más konfigurációs fájlokból a Aspire:Npgsql kulcs használatával. Példa appsettings.json, amely konfigurál néhány beállítást:

Az alábbi példa egy appsettings.json fájlt mutat be, amely konfigurálja a rendelkezésre álló lehetőségek némelyikét:

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

A teljes PostgreSQL ügyfél-integrációs JSON sémát lásd: Aspire. Npgsql/ConfigurationSchema.json.

Beágyazott delegátumok használata

A Action<NpgsqlSettings> configureSettings delegáltat soros beállításokhoz is átadhatja, például az állapot-ellenőrzések letiltásához:

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

Client integrációs egészségügyi ellenőrzések

Alapértelmezés szerint .NET.NET Aspireügyfélintegrációkállapotellenőrzések engedélyezve vannak minden szolgáltatásra. Hasonlóképpen számos .NET.NET Aspireüzemeltetési integráció is lehetővé teszi az állapot-ellenőrzési végpontokat. További információ:

• .NET alkalmazás-egészségügyi ellenőrzések C#-ben
• egészségügyi állapot-ellenőrzések ASP.NET Core

• Hozzáadja a NpgSqlHealthCheck, amely ellenőrzi, hogy a parancsok sikeresen végrehajthatók-e a mögöttes Postgres adatbázison.
• Integrálható a /health HTTP-végponttal, amely meghatározza, hogy az összes regisztrált állapot-ellenőrzésnek át kell mennie ahhoz, hogy az alkalmazás készen álljon a forgalom elfogadására

Megfigyelhetőség és telemetria

.NET .NET Aspire integrációk automatikusan beállítják a naplózási, követési és metrikakonfigurációkat, amelyeket más néven is ismert mint a megfigyelhetőség alappillérei. Az integráció megfigyelhetőségéről és telemetriáról további információt .NET.NET Aspire integrációk áttekintésében. A háttérszolgáltatástól függően egyes integrációk csak bizonyos funkciókat támogatnak. Egyes integrációk például támogatják a naplózást és a nyomkövetést, a metrikákat azonban nem. A telemetriai funkciók a Konfiguráció szakaszban ismertetett technikákkal is letilthatók.

Fakitermelés

Az .NET AspirePostgreSQL integráció a következő naplókategóriákat használja:

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

Nyomkövetés

Az .NET AspirePostgreSQL integráció a következő nyomkövetési tevékenységeket bocsátja ki a OpenTelemetryhasználatával:

• Npgsql

Metrikák

Az .NET AspirePostgreSQL integráció a következő metrikákat bocsátja ki a OpenTelemetryhasználatával:

• 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

Lásd még:

• PostgreSQL okmányok
• .NET Aspire Azure PostgreSQL integráció
• .NET .NET Aspire integrációk
• .NET Aspire GitHub adattár