integrace .NET AspirePostgreSQL

Článek
01/31/2025

zahrnuje:hostovací integrace a integrace Client

PostgreSQL je výkonný opensourcový systém relačních databází s mnoha lety aktivního vývoje, který získal silnou pověst pro spolehlivost, odolnost funkcí a výkon. Integrace poskytuje způsob, jak se připojit k existujícím databázím nebo vytvořit nové instance z pomocíimage kontejneru .

Integrace hostování

PostgreSQL integrační modely hostování kategorizují různé PostgreSQL prostředky jako následující typy.

Pokud chcete získat přístup k těmto typům a rozhraním API pro jejich vyjádření jako prostředků v hostiteli aplikace projektu , nainstalujte balíček NuGet 📦Aspire.Hosting.PostgreSQL:

.NET CLI
OdkazNaBalíček

dotnet add package Aspire.Hosting.PostgreSQL

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

Další informace viz dotnet add package nebo Správa závislostí balíčků v .NET aplikacích.

Přidání prostředku serveru PostgreSQL

V hostitelském projektu aplikace zavolejte AddPostgres na instanci builder a přidejte prostředek serveru PostgreSQL a potom zavolejte AddDatabase na instanci postgres a přidejte prostředek databáze, jak je znázorněno v následujícím příkladu:

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

Když .NET.NET Aspire přidá do hostitele aplikace image kontejneru, jak je znázorněno v předchozím příkladu s imagí docker.io/library/postgres, vytvoří na místním počítači novou instanci serveru PostgreSQL. Odkaz na váš PostgreSQL server a instanci databáze PostgreSQL (proměnnou postgresdb) slouží k přidání závislosti do ExampleProject. Prostředek serveru PostgreSQL obsahuje výchozí přihlašovací údaje s username"postgres" a náhodně vygenerovanými password pomocí metody CreateDefaultPasswordParameter.

Metoda WithReference nakonfiguruje připojení v ExampleProject s názvem "messaging". Další informace najdete v tématu životní cyklus zdrojů kontejneru.

Spropitné

Pokud byste se raději připojili k existujícímu serveru PostgreSQL, volejte místo toho AddConnectionString. Další informace naleznete v tématu Odkaz na existující prostředky.

Přidání prostředku PostgreSQL pgAdmin

Při přidávání PostgreSQL prostředků do builder pomocí metody AddPostgres můžete využít zřetězení volání WithPgAdmin pro přidání kontejneru dpage/pgadmin4. Tento kontejner je multiplatformní klient pro PostgreSQL databáze, který slouží webovému řídicímu panelu pro správu. Podívejte se na následující příklad:

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

Předchozí kód přidá kontejner založený na obrazu docker.io/dpage/pgadmin4. Kontejner slouží ke správě PostgreSQL serverových a databázových prostředků. Metoda WithPgAdmin přidá kontejner, který slouží webovému řídicímu panelu pro správu pro PostgreSQL databáze.

Konfigurace portu hostitele pgAdmin

Pokud chcete nakonfigurovat port hostitele pro kontejner pgAdmin, zavolejte metodu WithHostPort prostředku serveru PostgreSQL. Následující příklad ukazuje, jak nakonfigurovat port hostitele pro kontejner pgAdmin:

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

Předchozí kód přidá a nakonfiguruje port hostitele pro kontejner pgAdmin. Port hostitele je jinak náhodně přiřazen.

Přidejte prostředek pgWeb PostgreSQL

Při přidávání PostgreSQL prostředků do builder pomocí metody AddPostgres můžete řetězit volání na WithPgWeb, abyste přidali sosedoff/pgweb kontejneru. Tento kontejner je multiplatformní klient pro PostgreSQL databáze, který slouží webovému řídicímu panelu pro správu. Podívejte se na následující příklad:

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

Předchozí kód přidá kontejner založený na obrazu docker.io/sosedoff/pgweb. Všechny registrované PostgresDatabaseResource instance se používají k vytvoření konfiguračního souboru pro každou instanci a každá konfigurace je svázaná s adresářem záložek kontejneru pgweb. Další informace najdete v dokumentaci PgWeb: Server záložky pro připojení.

Konfigurujte port hostitele pgWeb

Pokud chcete nakonfigurovat port hostitele pro kontejner pgWeb, zavolejte metodu WithHostPort na prostředku serveru PostgreSQL. Následující příklad ukazuje, jak nakonfigurovat port hostitele pro kontejner pgAdmin:

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

Předchozí kód přidá a nakonfiguruje port hostitele pro kontejner pgWeb. Port hostitele je jinak náhodně přiřazen.

Přidejte prostředek serveru PostgreSQL s datovým svazkem

Pro přidání datového svazku k prostředku serveru PostgreSQL zavolejte metodu WithDataVolume na prostředku serveru PostgreSQL.

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

Datový svazek slouží k zachování dat serveru PostgreSQL mimo životní cyklus kontejneru. Datový svazek se připojí k cestě /var/lib/postgresql/data v kontejneru serveru PostgreSQL a pokud není zadaný parametr name, název se náhodně vygeneruje. Další informace o datových svazcích a podrobnosti o tom, proč jsou upřednostňovány před připojeními přes vazby , najdete v dokumentaci Docker: Svazky.

Přidat prostředek serveru PostgreSQL s připojením datového úložiště

Pokud chcete přidat data bind mount k prostředku serveru PostgreSQL, zavolejte metodu 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...

Důležitý

Připojení vazby dat mají v porovnání s svazkyomezené funkce, které nabízejí lepší výkon, přenositelnost a zabezpečení, což je vhodnější pro produkční prostředí. Připojení vazby však umožňují přímý přístup a úpravy souborů v hostitelském systému, které jsou ideální pro vývoj a testování, kde jsou potřebné změny v reálném čase.

Připojení vazby dat spoléhají na systém souborů hostitelského počítače k zachování dat serveru PostgreSQL napříč restartováními kontejneru. Připojení vazby dat je připojeno na cestu C:\PostgreSQL\Data v systému Windows (nebo /PostgreSQL/Data na Unix) na hostitelském počítači v kontejneru serveru PostgreSQL. Další informace o připojeních datových vazeb najdete v dokumentaci Docker: Připojení vazby.

Přidat serverový prostředek PostgreSQL s inicializačním bind mountem

Pokud chcete přidat inicializační přípojný bod k prostředku serveru PostgreSQL, zavolejte metodu 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...

Připojení typu bind spoléhá na souborový systém hostitelského počítače pro inicializaci databáze serveru PostgreSQL pomocí kontejnerů složky init . Tato složka se používá pro inicializaci, spuštění všech spustitelných skriptů prostředí nebo příkazových souborů .sql poté, co je vytvořena složka postgres-data. Připojení init typu bind je umístěno na cestě C:\PostgreSQL\Init ve Windows (nebo na cestě /PostgreSQL/Init na Unix) na hostitelském počítači v kontejneru serveru PostgreSQL.

Přidání prostředku serveru PostgreSQL s parametry

Pokud chcete explicitně zadat uživatelské jméno a heslo používané imagí kontejneru, můžete tyto přihlašovací údaje zadat jako parametry. Podívejte se na následující alternativní příklad:

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

Další informace o poskytování parametrů naleznete v tématu Externí parametry.

Hostování kontrol stavu integrace

Integrace hostování PostgreSQL automaticky přidává kontrolu stavu pro serverový prostředek PostgreSQL. Kontrola stavu ověřuje, jestli je server PostgreSQL spuštěný a že se k němu dá navázat připojení.

Integrace hostování spoléhá na balíček NuGet AspNetCore.HealthChecks.Npgsql.

Client integrace

Pokud chcete začít s integrací klienta .NET AspirePostgreSQL, nainstalujte 📦Aspire. Npgsql balíček NuGet v projektu využívajícím klienta, tj. projekt aplikace, která používá klienta PostgreSQL. Integrace klienta PostgreSQL registruje instanci NpgsqlDataSource, kterou můžete použít k interakci s PostgreSQL.

.NET CLI
OdkazNaBalíček

dotnet add package Aspire.Npgsql

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

Přidání klienta Npgsql

V souboru Program.cs projektu, který využívá klienta, zavolejte metodu rozšíření AddNpgsqlDataSource na jakémkoli IHostApplicationBuilder a zaregistrujte NpgsqlDataSource pro použití prostřednictvím kontejneru pro injektování závislostí. Metoda přebírá parametr názvu připojení.

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Spropitné

Parametr connectionName se musí shodovat s názvem použitým při přidávání prostředku serveru PostgreSQL v projektu hostitele aplikace. Další informace najdete v tématu Přidání PostgreSQL prostředku serveru.

Po přidání NpgsqlDataSource do builderu můžete získat instanci NpgsqlDataSource pomocí injekce závislostí. Pokud například chcete načíst objekt zdroje dat z ukázkové služby, definujte ho jako parametr konstruktoru a ujistěte se, že je třída ExampleService zaregistrovaná v kontejneru injektáže závislostí:

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

Další informace o injektáži závislostí najdete v tématu .NET injektáž závislostí.

Přidání klienta Npgsql s klíči

Mohou nastat situace, kdy chcete zaregistrovat více instancí NpgsqlDataSource s různými názvy připojení. Pokud chcete zaregistrovat klienty Npgsql s klíči, zavolejte metodu AddKeyedNpgsqlDataSource:

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

Potom můžete načíst NpgsqlDataSource instance pomocí injektáže závislostí. Pokud například chcete získat připojení z ukázkové služby:

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

Další informace o klíčových službách najdete v tématu .NET injektáž závislostí: Služby s klíči.

Konfigurace

Integrace .NET AspirePostgreSQL poskytuje několik přístupů a možností konfigurace, které splňují požadavky a konvence projektu.

Použijte připojovací řetězec

Při použití připojovacího řetězce z oddílu konfigurace ConnectionStrings můžete při volání metody AddNpgsqlDataSource zadat název připojovacího řetězce:

builder.AddNpgsqlDataSource("postgresdb");

Připojovací řetězec se pak načte z oddílu konfigurace ConnectionStrings:

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

Další informace naleznete v ConnectionString.

Použití zprostředkovatelů konfigurace

Integrace .NET AspirePostgreSQL podporuje Microsoft.Extensions.Configuration. Načte NpgsqlSettings z appsettings.json nebo jiných konfiguračních souborů pomocí klíče Aspire:Npgsql. Příklad appsettings.json, který konfiguruje některé z možností:

Následující příklad ukazuje soubor appsettings.json, který konfiguruje některé z dostupných možností:

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

Kompletní schéma integrace klienta PostgreSQLJSON naleznete v tématu Aspire. Npgsql/ConfigurationSchema.json.

Použití vložených delegátů

Můžete také předat delegáta Action<NpgsqlSettings> configureSettings a nastavit některé nebo všechny možnosti přímo, například zakázat zdravotní kontroly:

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

Kontroly stavu

Ve výchozím nastavení integrace .NET.NET Aspire aktivují kontroly stavu pro všechny služby. Další informace naleznete v tématu .NET.NET Aspire integrace přehled.

Přidá NpgSqlHealthCheck, který ověří, že příkazy lze úspěšně spustit na podkladové Postgres databázi.
Integruje se s HTTP koncovým bodem /health, který určuje, že všechny registrované kontroly stavu musí projít, aby aplikace byla považována za připravenou přijímat síťový provoz.

Pozorovatelnost a telemetrie

.NET .NET Aspire integrace automaticky nastavují konfigurace protokolování, trasování a metrik, které se někdy označují jako pilíře pozorovatelnosti. Další informace o pozorovatelnosti a telemetrii integrace najdete v přehledu integrace .NET.NET Aspire. V závislosti na zálohovací službě můžou některé integrace podporovat pouze některé z těchto funkcí. Například některé integrace podporují protokolování a trasování, ale ne metriky. Funkce telemetrie je také možné zakázat pomocí technik uvedených v části Konfigurace.

Protokolování

Integrace .NET AspirePostgreSQL používá následující kategorie protokolů:

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

Trasování

Integrace .NET AspirePostgreSQL bude pomocí OpenTelemetryemitovat následující aktivity trasování:

Npgsql

Metriky

Integrace .NET AspirePostgreSQL pomocí OpenTelemetryvygeneruje následující metriky:

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

Sdílet prostřednictvím