integracja .NET AspirePostgreSQL

obejmuje: integracja hostingu oraz 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

Modele integracji hostingowej PostgreSQL modelują różne zasoby PostgreSQL jako następujące typy.

• PostgresServerResource
• PostgresDatabaseResource
• PgAdminContainerResource
• PgWebContainerResource

Aby uzyskać dostęp do tych typów i interfejsów API, aby wyrazić je jako zasoby w projekcie hosta aplikacji, zainstaluj pakiet NuGet 📦Aspire.Hosting.PostgreSQL.

dotnet add package Aspire.Hosting.PostgreSQL

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

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

Dodawanie zasobu serwera PostgreSQL

W projekcie hosta aplikacji wywołaj AddPostgres w wystąpieniu builder, aby dodać zasób serwera PostgreSQL, 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 we wcześniejszym przykładzie z obrazem docker.io/library/postgres, tworzy nową instancję serwera PostgreSQL na komputerze lokalnym. Odwołanie do serwera PostgreSQL i wystąpienia bazy danych PostgreSQL (zmiennej postgresdb) służy do dodania zależności do ExampleProject. Zasób serwera PostgreSQL zawiera domyślne poświadczenia oparte na username"postgres" oraz 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.

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 międzyplatformowym klientem 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")
                      .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 serwera PostgreSQL i bazy danych. Metoda WithPgAdmin dodaje kontener obsługujący internetowy pulpit nawigacyjny administratora dla baz danych PostgreSQL.

Konfigurowanie portu hosta pgAdmin

Aby skonfigurować port hosta dla kontenera pgAdmin, wywołaj metodę WithHostPort w zasobie serwera PostgreSQL. W poniższym przykładzie pokazano, jak skonfigurować port hosta dla kontenera 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...

Powyższy kod dodaje i konfiguruje port hosta dla kontenera pgAdmin. Port hosta jest w przeciwnym razie losowo przypisany.

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 międzyplatformowym klientem 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...

Kod powyżej dodaje kontener na bazie 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.

Konfigurowanie portu hosta pgWeb

Aby skonfigurować port hosta dla kontenera pgWeb, wywołaj metodę WithHostPort w zasobie serwera PostgreSQL. W poniższym przykładzie pokazano, jak skonfigurować port hosta dla kontenera pgAdmin:

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

Powyższy kod dodaje i konfiguruje port hosta dla kontenera pgWeb. Port hosta jest w przeciwnym razie losowo przypisany.

Dodaj zasób serwera PostgreSQL z woluminem danych

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

Wolumin danych jest używany do utrwalania danych serwera PostgreSQL poza cyklem życia kontenera. Wolumin danych jest instalowany w ścieżce /var/lib/postgresql/data w kontenerze serwera PostgreSQL, 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 zamiast bind mounts, zobacz w Docker dokumentacji: Woluminy.

Dodaj zasób serwera PostgreSQL z montowaniem danych za pomocą powiązania

Aby dodać powiązanie danych do zasobu serwera PostgreSQL, 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...

Montaże powiązań danych polegają na systemie plików maszyny hosta do utrwalania danych serwera PostgreSQL podczas ponownych uruchomień kontenera. Punkt montowania danych jest montowany na ścieżce C:\PostgreSQL\Data w systemie Windows (lub na ścieżce /PostgreSQL/Data na Unix) na maszynie hosta w kontenerze PostgreSQL serwera. Aby uzyskać więcej informacji na temat montowania punktów powiązań danych, zobacz dokumentację Docker: "Montaż powiązań".

Dodaj zasób serwera PostgreSQL z montowaniem powiązania init

Aby dodać punkt montowania init typu bind do zasobu serwera PostgreSQL, 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 serwera PostgreSQL za pomocą kontenerów init folderu. Ten folder jest używany do inicjalizacji i uruchamiania dowolnych wykonywalnych skryptów powłoki lub plików poleceń .sql po utworzeniu folderu postgres-data. Powiązanie init jest zamontowane w C:\PostgreSQL\Init w systemie Windows (lub /PostgreSQL/Init na ścieżce Unix) na maszynie hosta w kontenerze serwera PostgreSQL.

Dodawanie zasobu serwera PostgreSQL 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 serwera PostgreSQL. Sprawdzanie kondycji sprawdza, czy serwer PostgreSQL jest uruchomiony i czy można nawiązać z nim połączenie.

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

integracja Client

Aby rozpocząć pracę z integracją klienta .NET AspirePostgreSQL, zainstaluj pakiet NuGet 📦Aspire.Npgsql w projekcie korzystającym z klienta, czyli w projekcie dla aplikacji, który używa klienta PostgreSQL. Integracja klienta PostgreSQL rejestruje instancję NpgsqlDataSource, którą można wykorzystać do interakcji z PostgreSQL.

dotnet add package Aspire.Npgsql

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

Dodawanie klienta npgsql

W pliku Program.cs projektu korzystającego z klienta wywoł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");

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 sekcję .NET wstrzykiwanie zależności.

Dodaj klienta Npgsql z kluczem

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 opartych na kluczach, zobacz .NET wstrzykiwanie zależności: usługi oparte na kluczach.

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 konfiguracyjnych 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 klienta PostgreSQLJSON, 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);

Client kontrole stanu integracji

Domyślnie .NET.NET Aspireintegracje klienta mają kontrole stanu włączone dla wszystkich usług. Podobnie, wiele .NET.NET Aspireintegracji hostingowych również umożliwiają punkty końcowe sprawdzania kondycji. Aby uzyskać więcej informacji, zobacz:

• .NET sprawdzanie kondycji aplikacji w języku C#
• kontrole kondycji w ASP.NET Core

• Dodaje NpgSqlHealthCheck, który sprawdza, czy polecenia można pomyślnie wykonać w bazowej bazie 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 .

Logowanie

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

Zobacz też

• PostgreSQL dokumentacja
• .NET Aspire Azure PostgreSQL integracja
• .NET .NET Aspire integracje
• .NET Aspire GitHub repozytorium