Sdílet prostřednictvím

integrace .NET AspirePostgreSQL

  • Článek

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í

Integrační modely hostování PostgreSQL definují PostgreSQLserver jako typ PostgresServerResource. Přístup k tomuto typu a k rozhraním API, která vám umožní přidat jej do 📦AspirePostgreSQL .Hostování balíčku NuGet v projektu hostitele aplikace .

dotnet add package Aspire.Hosting.PostgreSQL

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

Přidání prostředku PostgreSQLserver

V projektu hostitele aplikace zavolejte AddPostgres na instanci builder a přidejte PostgreSQLserver prostředek, a následně zavolejte AddDatabase na instanci postgres a přidejte databázový prostředek, 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 PostgreSQLserver. Odkaz na vaši PostgreSQLserver a instanci databáze PostgreSQL (proměnnou postgresdb) slouží k přidání závislosti do ExampleProject. Prostředek PostgreSQLserver zahrnuje výchozí přihlašovací údaje s username o hodnotě "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 PostgreSQLserver, 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 víceplatformní client pro PostgreSQL databáze, který poskytuje webový řídicí panel 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ě PostgreSQLserver 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.

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í client pro PostgreSQL databáze, který obsluhuje webový řídicí panel. 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í.

Přidání PostgreSQLserver zdroje s datovým svazkem

Pokud chcete do prostředku PostgreSQLserver přidat datový svazek, zavolejte metodu WithDataVolume prostředku PostgreSQLserver:

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

Objem dat se používá k zachování PostgreSQLserver dat mimo životní cyklus kontejneru. Datový svazek se připojí k cestě /var/lib/postgresql/data v kontejneru PostgreSQLserver 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řidání prostředku PostgreSQLserver s připojením vazby dat

Pokud chcete přidat vazbu datového připojení k prostředku PostgreSQLserver, 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.

Napojení pro svázání dat využívají systém souborů hostitelského počítače k zachování PostgreSQLserver dat při restartech kontejneru. Vazba datového svazku je připojena k trase C:\PostgreSQL\Data ve Windows (nebo /PostgreSQL/Data na Unix) na hostitelském počítači v kontejneru PostgreSQLserver. Další informace o připojeních datových vazeb najdete v dokumentaci Docker: Připojení vazby.

Přidání prostředku PostgreSQLserver s inicializačním připojením vazby

Pokud chcete přidat připojení inicializační vazby k prostředku PostgreSQLserver, 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í inicializační vazby spoléhá na systém souborů hostitelského počítače k inicializaci PostgreSQLserver databáze pomocí složky init kontejnerů. Tato složka se používá k inicializaci a po vytvoření složky postgres-data spustí všechny spustitelné skripty prostředí nebo soubory příkazů .sql. Připojení inicializační vazby je připojeno k C:\PostgreSQL\Init ve Windows (nebo /PostgreSQL/Init na Unix) v hostitelském počítači v kontejneru PostgreSQLserver.

Přidání prostředku PostgreSQLserver 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á kontrolu stavu prostředku PostgreSQLserver. Kontrola stavu ověřuje, že PostgreSQLserver běží 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í .NET AspirePostgreSQLclient, nainstalujte balíček NuGet 📦Aspire.Npgsql v projektu využívajícím client, tj. v projektu aplikace, která používá PostgreSQLclient. Integrace zaregistruje instanci npgsqlDataSource , kterou můžete použít k interakci s .

dotnet add package Aspire.Npgsql

Přidat Npgsql client

V souboru Program.cs vašeho projektu, který spotřebovává client, zavolejte rozšiřovací metodu AddNpgsqlDataSource na libovolném 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");

Tip

Parametr connectionName se musí shodovat s názvem použitým při přidávání prostředku PostgreSQLserver do hostitelského projektu aplikace. Další informace najdete v tématu Přidání PostgreSQLserver prostředků.

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řidat keyovaný Npgsql client

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 PostgreSQLclientJSON naleznete v části 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 vůči podkladové databázi Postgres.
  • 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 pomocí OpenTelemetryvygeneruje 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

integrace hostování AzurePostgreSQL

Pokud chcete nasadit prostředky PostgreSQL do Azure, nainstalujte balíček NuGet 📦Aspire.Hosting.Azure.PostgreSQL.

dotnet add package Aspire.Hosting.Azure.PostgreSQL

Přidání prostředku AzurePostgreSQLserver

Po instalaci integrace hostování .NET AspireAzurePostgreSQL volejte metodu rozšíření AddAzurePostgresFlexibleServer v hostitelském projektu aplikace:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Předchozí volání AddAzurePostgresFlexibleServer nakonfiguruje prostředek server PostgreSQL tak, aby byl nasazen jako flexibilní AzurePostgresServer.

Důležitý

Ve výchozím nastavení AddAzurePostgresFlexibleServer konfiguruje ověřování ID Microsoft Entra. To vyžaduje změny aplikací, které se k těmto prostředkům potřebují připojit. Další informace najdete v tématu Client integrace.

Přidání ověřených Npgsql Azureclient

Ve výchozím nastavení, když zavoláte AddAzurePostgresFlexibleServer ve vaší PostgreSQL hostovací integraci, nakonfiguruje se balíček NuGet 📦Azure.Identity pro povolení ověřování:

dotnet add package Azure.Identity

Připojení PostgreSQL je možné využívat pomocí integrace client a Azure.Identity:

builder.AddNpgsqlDataSource(
    "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));
});

Předchozí fragment kódu ukazuje použití třídy DefaultAzureCredential z balíčku Azure.Identity k ověření pomocí Microsoft Entra ID a načtení tokenu pro připojení k databázi PostgreSQL. Metoda UsePeriodicPasswordProvider slouží k poskytnutí tokenu pro tvůrce připojovacích řetězců.

Viz také