Udostępnij za pośrednictwem

integracja .NET AspirePostgreSQL

  • Artykuł

obejmuje:integracja hostingu i integracja Client

PostgreSQL to zaawansowany, relacyjny system baz danych typu open source z wieloma latami aktywnego programowania, który zdobył silną reputację niezawodności, niezawodności funkcji i wydajności. Integracja .NET AspirePostgreSQL umożliwia połączenie z istniejącymi bazami danych PostgreSQL lub tworzenie nowych instancji z .NET z użyciem obrazu kontenera docker.io/library/postgres.

Integracja hostingu

Integracja modeli hostowania PostgreSQL modeluje PostgreSQLserver w typie PostgresServerResource. Aby uzyskać dostęp do tego typu i interfejsów API, które umożliwiają dodanie go do . Gościnność. pakiet NuGet w projekcie hosta aplikacji .

dotnet add package Aspire.Hosting.PostgreSQL

Aby uzyskać więcej informacji, zobacz dotnet add package lub Zarządzanie zależnościami pakietów w .NET aplikacjach.

Dodawanie zasobu PostgreSQLserver

W projekcie hosta aplikacji wywołaj AddPostgres w wystąpieniu builder, aby dodać zasób PostgreSQLserver, a następnie wywołaj AddDatabase w wystąpieniu postgres, aby dodać zasób bazy danych, jak pokazano w poniższym przykładzie:

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

Gdy .NET.NET Aspire dodaje obraz kontenera do hosta aplikacji, jak pokazano w poprzednim przykładzie z obrazem docker.io/library/postgres, tworzy nowe wystąpienie PostgreSQLserver na komputerze lokalnym. Referencje do PostgreSQLserver oraz instancji bazy danych PostgreSQL (zmiennej postgresdb) są używane do dodawania zależności do ExampleProject. Zasób PostgreSQLserver zawiera poświadczenia domyślne z username"postgres" i losowo generowane password przy użyciu metody CreateDefaultPasswordParameter.

Metoda WithReference konfiguruje połączenie w ExampleProject o nazwie "messaging". Aby uzyskać więcej informacji, zobacz Cykl życia zasobów kontenera.

Napiwek

Jeśli wolisz nawiązać połączenie z istniejącym PostgreSQLserver, wywołaj AddConnectionString zamiast tego. Aby uzyskać więcej informacji, zobacz Odwołaj się do istniejących zasobów.

Dodawanie zasobu PostgreSQL pgAdmin

Podczas dodawania zasobów PostgreSQL do builder za pomocą metody AddPostgres można łańcuchowo wywoływać WithPgAdmin, aby dodać kontener dpage/pgadmin4. Ten kontener jest wieloplatformowym client dla PostgreSQL baz danych, który obsługuje interfejs administracyjny dostępny przez internet. Rozważmy następujący przykład:

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

Kod powyżej dodaje kontener na bazie obrazu docker.io/dpage/pgadmin4. Kontener służy do zarządzania zasobami PostgreSQLserver i bazami danych. Metoda WithPgAdmin dodaje kontener obsługujący internetowy pulpit nawigacyjny administratora dla baz danych PostgreSQL.

Dodawanie zasobu PostgreSQL pgWeb

Podczas dodawania zasobów PostgreSQL do builder przy użyciu metody AddPostgres, można łączyć wywołania, aby za pomocą WithPgWeb dodać kontener sosedoff/pgweb. Ten kontener jest wieloplatformowym client dla PostgreSQL baz danych, który obsługuje internetowy pulpit nawigacyjny administratora. Rozważmy następujący przykład:

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

Powyższy kod dodaje kontener na podstawie obrazu docker.io/sosedoff/pgweb. Wszystkie zarejestrowane wystąpienia PostgresDatabaseResource są używane do tworzenia pliku konfiguracji dla każdego wystąpienia, a każda konfiguracja jest powiązana z katalogiem zakładek kontenera pgweb. Aby uzyskać więcej informacji, zapoznaj się z dokumentacją PgWeb: Server zakładki dotyczące połączenia.

Dodawanie zasobu PostgreSQLserver z woluminem danych

Aby dodać wolumin danych do zasobu PostgreSQLserver, wywołaj metodę WithDataVolume w zasobie 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...

Objętość danych służy do przechowywania danych PostgreSQLserver poza cyklem życia kontenera. Wolumin danych jest instalowany w ścieżce /var/lib/postgresql/data w kontenerze PostgreSQLserver, a gdy nie podano parametru name, nazwa jest generowana losowo. Aby uzyskać więcej informacji na temat woluminów danych i szczegółów na temat tego, dlaczego są preferowane w przypadku instalacji wiązania, zobacz Docker dokumentacji: woluminy.

Dodawanie zasobu PostgreSQLserver z instalacją powiązania danych

Aby dodać powiązanie danych do zasobu PostgreSQLserver, wywołaj metodę 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...

Ważny

Instalacje powiązane danych mają ograniczoną funkcjonalność w porównaniu z woluminami , co zapewnia lepszą wydajność, przenośność i bezpieczeństwo, co czyni je bardziej odpowiednimi dla środowisk produkcyjnych. Jednak montowanie wiązań umożliwia bezpośredni dostęp i modyfikację plików w systemie hosta, co jest idealne do rozwoju i testowania, gdzie potrzebne są zmiany w czasie rzeczywistym.

Instalacje powiązań danych wykorzystują system plików maszyny hosta do utrwalania danych PostgreSQLserver przy ponownych uruchomieniach kontenera. Powiązanie danych jest montowane w ścieżce C:\PostgreSQL\Data na systemie Windows (lub /PostgreSQL/Data na Unix) na maszynie hosta w kontenerze PostgreSQLserver. Aby uzyskać więcej informacji na temat montowania punktów powiązań danych, zobacz dokumentację Docker: "Montaż powiązań".

Dodaj zasób PostgreSQLserver z montażem wiążącym init

Aby dodać zamontowanie powiązania init do zasobu PostgreSQLserver, wywołaj metodę 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...

Instalacja powiązania init opiera się na systemie plików maszyny hosta w celu zainicjowania bazy danych PostgreSQLserver przy użyciu kontenerów init folder. Ten folder służy do inicjowania, uruchamiania skryptów powłoki wykonywalnej lub plików poleceń .sql po utworzeniu folderu postgres-data. Powiązanie init jest zamontowane na ścieżce C:\PostgreSQL\Init w systemie Windows (lub /PostgreSQL/Init w Unix) na maszynie hosta w kontenerze PostgreSQLserver.

Dodawanie zasobu PostgreSQLserver z parametrami

Jeśli chcesz wyraźnie określić nazwę użytkownika i hasło używane przez obraz kontenera, możesz dostarczyć te poświadczenia w formie parametrów. Rozważmy następujący przykład alternatywny:

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

Aby uzyskać więcej informacji na temat udostępniania parametrów, zobacz Parametry zewnętrzne.

Kontrola stanu integracji hostingu

Integracja hostowania PostgreSQL automatycznie dodaje kontrolę kondycji zasobu PostgreSQLserver. Sprawdzenie stanu weryfikuje, czy PostgreSQLserver jest uruchomiona i czy można nawiązać z nią połączenie.

Integracja hostingu opiera się na pakiecie NuGet 📦 AspNetCore.HealthChecks.Npgsql.

integracja Client

Aby rozpocząć pracę z integracją .NET AspirePostgreSQLclient, zainstaluj 📦Aspire. Npgsql pakiet NuGet w projekcie korzystającym z client, czyli projektu dla aplikacji korzystającej z PostgreSQLclient. Integracja PostgreSQLclient rejestruje instancję NpgsqlDataSource, której można użyć do interakcji z PostgreSQL.

dotnet add package Aspire.Npgsql

Dodawanie npgsql client

W pliku Program.cs projektu zużywającego clientwywołaj metodę rozszerzenia AddNpgsqlDataSource na dowolnym IHostApplicationBuilder, aby zarejestrować NpgsqlDataSource do użycia za pośrednictwem kontenera wstrzykiwania zależności. Metoda przyjmuje parametr nazwy połączenia.

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Napiwek

Parametr connectionName musi być zgodny z nazwą używaną podczas dodawania zasobu PostgreSQLserver w projekcie hosta aplikacji. Aby uzyskać więcej informacji, zobacz Dodawanie zasobu PostgreSQLserver.

Po dodaniu NpgsqlDataSource do konstruktora można pobrać wystąpienie NpgsqlDataSource przy użyciu wstrzykiwania zależności. Na przykład aby pobrać obiekt źródła danych z przykładowej usługi, zdefiniuj go jako parametr konstruktora i upewnij się, że klasa ExampleService jest zarejestrowana w kontenerze iniekcji zależności:

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

Aby uzyskać więcej informacji na temat wstrzykiwania zależności, zobacz .NET wstrzykiwanie zależności.

Dodaj npgsql z kluczem client

Mogą wystąpić sytuacje, w których chcesz zarejestrować wiele wystąpień NpgsqlDataSource z różnymi nazwami połączeń. Aby zarejestrować klientów Npgsql z kluczami, wywołaj metodę AddKeyedNpgsqlDataSource:

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

Następnie można za pomocą wstrzykiwania zależności pobrać wystąpienia NpgsqlDataSource. Aby na przykład pobrać połączenie z przykładowej usługi:

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

Aby uzyskać więcej informacji na temat usług kluczy, zobacz .NET wstrzykiwanie zależności: usługi kluczy.

Konfiguracja

Integracja .NET AspirePostgreSQL zapewnia wiele metod konfiguracji i opcji spełniających wymagania i konwencje projektu.

Używanie parametrów połączenia

W przypadku używania parametrów połączenia z sekcji konfiguracji ConnectionStrings podczas wywoływania metody AddNpgsqlDataSource można podać nazwę parametrów połączenia:

builder.AddNpgsqlDataSource("postgresdb");

Następnie parametry połączenia zostaną pobrane z sekcji konfiguracji ConnectionStrings:

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

Aby uzyskać więcej informacji, zobacz ConnectionString.

Korzystanie z dostawców konfiguracji

Integracja .NET AspirePostgreSQL obsługuje Microsoft.Extensions.Configuration. Ładuje NpgsqlSettings z appsettings.json lub innych plików konfiguracji przy użyciu klucza Aspire:Npgsql. Przykład appsettings.json, który konfiguruje niektóre opcje:

W poniższym przykładzie przedstawiono plik appsettings.json, który konfiguruje niektóre z dostępnych opcji:

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

Aby uzyskać pełny schemat integracji PostgreSQLclientJSON, zobacz Aspire. Npgsql/ConfigurationSchema.json.

Używanie delegatów wbudowanych

Możesz również przekazać delegata Action<NpgsqlSettings> configureSettings, aby skonfigurować niektóre lub wszystkie opcje wbudowane, na przykład w celu wyłączenia kontroli kondycji:

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

Kontrole kondycji

Domyślnie .NET.NET Aspire integracje umożliwiają sprawdzanie zdrowia dla wszystkich usług. Aby uzyskać więcej informacji, zobacz omówienie integracji .NET.NET Aspire.

  • Dodaje NpgSqlHealthCheck, który sprawdza, czy polecenia można pomyślnie wykonać względem bazowego systemu baz danych Postgres.
  • Integruje się z /health punktem końcowym HTTP, który określa, że wszystkie zarejestrowane kontrole stanu zdrowia muszą zostać pomyślnie zakończone, aby aplikacja została uznana za gotową do akceptowania ruchu.

Obserwowanie i telemetria

.NET .NET Aspire integracje automatycznie ustawiają konfiguracje rejestrowania, śledzenia i metryk, które są czasami nazywane filarami obserwowalności. Aby uzyskać więcej informacji na temat możliwości obserwacji integracji i telemetrii, zobacz omówienie integracji .NET.NET Aspire. W zależności od usługi pomocniczej niektóre integracje mogą obsługiwać tylko niektóre z tych funkcji. Na przykład niektóre integracje obsługują rejestrowanie i śledzenie, ale nie metryki. Funkcje telemetrii można również wyłączyć przy użyciu technik przedstawionych w sekcji konfiguracji .

Wyrąb

Integracja .NET AspirePostgreSQL używa następujących kategorii dzienników:

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

Śledzenie

Integracja .NET AspirePostgreSQL spowoduje emitowanie następujących działań śledzenia przy użyciu OpenTelemetry:

  • Npgsql

Wskaźniki

Integracja .NET AspirePostgreSQL będzie emitować następujące metryki przy użyciu 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

Azure PostgreSQL integracji hostingu

Aby wdrożyć zasoby PostgreSQL w usłudze Azure, zainstaluj 📦Aspire.Hosting.Azure.PostgreSQL pakiet NuGet:

dotnet add package Aspire.Hosting.Azure.PostgreSQL

Dodawanie zasobu AzurePostgreSQLserver

Po zainstalowaniu integracji .NET AspireAzurePostgreSQL hostingu wywołaj metodę rozszerzenia AddAzurePostgresFlexibleServer w projekcie hosta aplikacji:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Poprzednie wywołanie AddAzurePostgresFlexibleServer konfiguruje zasób PostgresSQL server, który ma zostać wdrożony jako elastyczny AzurePostgresServer.

Ważny

Domyślnie AddAzurePostgresFlexibleServer konfiguruje uwierzytelnianie Microsoft Entra ID. Wymaga to zmian w aplikacjach, które muszą łączyć się z tymi zasobami. Aby uzyskać więcej informacji, zobacz Client integration.

Dodaj Azure uwierzytelnione Npgsql client

Domyślnie, gdy wywołujesz AddAzurePostgresFlexibleServer w integracji hostingu PostgreSQL, konfiguruje to pakiet NuGet 📦Azure.Identity, aby umożliwić uwierzytelnianie.

dotnet add package Azure.Identity

Połączenie PostgreSQL można wykorzystać za pomocą integracji client i 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));
});

Powyższy fragment kodu pokazuje, jak używać klasy DefaultAzureCredential z pakietu Azure.Identity do uwierzytelniania za pomocą microsoft Entra ID i pobrać token do nawiązania połączenia z bazą danych PostgreSQL. Metoda UsePeriodicPasswordProvider służy do udostępniania tokenu konstruktorowi parametrów połączenia.

Zobacz też