integracja .NET AspirePostgreSQLEntity Framework Core

obejmuje: integracjahostingu 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 AspirePostgreSQLEntity Framework Core umożliwia łączenie się z istniejącymi bazami danych PostgreSQL lub tworzenie nowych instancji z .NET za pomocą obrazu kontenera docker.io/library/postgres.

Integracja hostingu

Integracja hostingu modeli PostgreSQL modeluje PostgreSQLserver jako typ 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 .

.NET interfejsu wiersza polecenia

dotnet add package Aspire.Hosting.PostgreSQL

PackageReference

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

Aby uzyskać więcej informacji, zobacz dotnet add package or Manage package dependencies in .NET applications.

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. Odwołanie do PostgreSQLserver oraz wystąpienia bazy danych PostgreSQL (zmienna postgresdb) służy do dodania 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.

Wskazówka

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

Dodawanie zasobu PostgreSQL pgAdmin

Podczas dodawania zasobów PostgreSQL do builder za pomocą metody AddPostgres można zrównoleglić wywołania do WithPgAdmin w celu dodania kontenera dpage/pgadmin4. 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")
                      .WithPgAdmin();

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 w oparciu o obraz 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 za pomocą metody AddPostgres można połączyć wywołania w celu WithPgWeb dodania kontenera 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 folderem zakładek w kontenerze pgweb. Aby uzyskać więcej informacji, zobacz dokumentację PgWeb: Server zakładki połączeń.

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

Wolumin danych służy do przechowywania PostgreSQLserver danych poza okresem życia jego 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 oraz powodów ich preferowania nad montowaniem wiązań , zobacz dokumentację Docker: Woluminy.

Dodawanie zasobu PostgreSQLserver z montowaniem powiązania danych

Aby dodać punkt montowania 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

Powiązane montowania danych mają ograniczoną funkcjonalność w porównaniu do woluminów , które oferują lepszą wydajność, przenośność i bezpieczeństwo, co czyni je bardziej odpowiednimi dla środowisk produkcyjnych. Jednak instalacje wiązania umożliwiają bezpośredni dostęp i modyfikację plików w systemie hosta, idealne do programowania i testowania, w których potrzebne są zmiany w czasie rzeczywistym.

Instalacje powiązania danych polegają na systemie plików maszyny hosta w celu utrwalania PostgreSQLserver danych między ponownymi uruchomieniami kontenera. Powiązanie danych jest zamontowane w C:\PostgreSQL\Data w systemie Windows (lub /PostgreSQL/Data w Unix) na ścieżce maszyny hosta w kontenerze PostgreSQLserver. Aby uzyskać więcej informacji na temat podłączenia danych bind, zobacz dokumentację Docker: Bind mounts.

Dodawanie zasobu PostgreSQLserver z instalacją powiązania init

Aby dodać montowanie bind init do zasobu PostgreSQLserver, użyj metody 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 montowania init jest montowane w C:\PostgreSQL\Init w systemie Windows (lub /PostgreSQL/Init w Unix) na ścieżce maszyny hosta w kontenerze PostgreSQLserver.

Dodawanie zasobu PostgreSQLserver z parametrami

Jeśli chcesz jawnie podać nazwę użytkownika i hasło używane przez obraz kontenera, możesz przekazać te dane uwierzytelniające jako parametry. 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.

Monitoring stanu zdrowia integracji

Integracja hostowania PostgreSQL automatycznie dodaje kontrolę kondycji zasobu PostgreSQLserver. Sprawdzenie kondycji sprawdza, czy PostgreSQLserver są uruchomione i czy można nawiązać z nimi połączenie.

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

integracja Client

Aby rozpocząć pracę z integracją .NET AspirePostgreSQLEntity Framework Coreclient, zainstaluj 📦Aspire.Npgsql.EntityFrameworkCore.PostgreSQL pakiet NuGet w projekcie, który korzysta z client, czyli w projekcie dla aplikacji wykorzystującej PostgreSQLclient. Integracja .NET AspirePostgreSQLEntity Framework Coreclient rejestruje żądane wystąpienia podklasy DbContext, które można użyć do interakcji z PostgreSQL.

.NET interfejsu wiersza polecenia

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

PackageReference

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

Dodawanie kontekstu bazy danych Npgsql

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

builder.AddNpgsqlDbContext<YourDbContext>(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 YourDbContext do konstruktora można pobrać wystąpienie YourDbContext 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(YourDbContext context)
{
    // Use context...
}

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

Dodawanie kontekstu bazy danych Npgsql z wzbogacaniem

Aby wzbogacić DbContext o dodatkowe usługi, takie jak automatyczne ponawianie prób, kontrole stanu zdrowia, logowanie i telemetria, wywołaj metodę EnrichNpgsqlDbContext.

builder.EnrichNpgsqlDbContext<YourDbContext>(
    connectionName: "postgresdb",
    configureSettings: settings =>
    {
        settings.DisableRetry = false;
        settings.CommandTimeout = 30;
    });

Parametr settings jest wystąpieniem klasy NpgsqlEntityFrameworkCorePostgreSQLSettings.

Konfiguracja

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

Użycie ciągu połączenia

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

builder.AddNpgsqlDbContext<MyDbContext>("pgdb");

Parametry połączenia są pobierane z sekcji konfiguracji ConnectionStrings:

{
  "ConnectionStrings": {
    "pgdb": "Host=myserver;Database=test"
  }
}

EnrichNpgsqlDbContext nie będzie korzystać z sekcji konfiguracji ConnectionStrings, ponieważ oczekuje ona zarejestrowania DbContext w momencie jego wywołania.

Aby uzyskać więcej informacji, zobacz ConnectionString.

Korzystanie z dostawców konfiguracji

Integracja .NET AspirePostgreSQLEntity Framework Core obsługuje Microsoft.Extensions.Configuration. Ładuje NpgsqlEntityFrameworkCorePostgreSQLSettings z plików konfiguracji, takich jak appsettings.json przy użyciu klucza Aspire:Npgsql:EntityFrameworkCore:PostgreSQL. Jeśli konfiguracje zostały skonfigurowane w sekcji Aspire:Npgsql:EntityFrameworkCore:PostgreSQL, możesz wywołać metodę bez przekazywania żadnego parametru.

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

{
  "Aspire": {
    "Npgsql": {
      "EntityFrameworkCore": {
        "PostgreSQL": {
          "ConnectionString": "Host=myserver;Database=postgresdb",
          "DbContextPooling": true,
          "DisableHealthChecks": true,
          "DisableTracing": true
        }
      }
    }
  }
}

Aby uzyskać pełny schemat integracji JSONPostgreSQLEntity Framework Coreclient, zobacz Aspire. Npgsql.EntityFrameworkCore.PostgreSQL/ConfigurationSchema.json.

Używaj delegatów wbudowanych

Możesz również przekazać delegata Action<NpgsqlEntityFrameworkCorePostgreSQLSettings>, aby skonfigurować niektóre lub wszystkie opcje wbudowane, na przykład w celu ustawienia ConnectionString:

builder.AddNpgsqlDbContext<YourDbContext>(
    "pgdb",
    static settings => settings.ConnectionString = "<YOUR CONNECTION STRING>");

Konfigurowanie wielu klas DbContext

Jeśli chcesz zarejestrować więcej niż jedną DbContext w innej konfiguracji, możesz użyć nazwy sekcji konfiguracji $"Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:{typeof(TContext).Name}". Konfiguracja json wygląda następująco:

{
  "Aspire": {
    "Npgsql": {
      "EntityFrameworkCore": {
        "PostgreSQL": {
          "ConnectionString": "<YOUR CONNECTION STRING>",
          "DbContextPooling": true,
          "DisableHealthChecks": true,
          "DisableTracing": true,
          "AnotherDbContext": {
            "ConnectionString": "<ANOTHER CONNECTION STRING>",
            "DisableTracing": false
          }
        }
      }
    }
  }
}

Następnie wywołanie metody AddNpgsqlDbContext przy użyciu parametru typu AnotherDbContext spowoduje załadowanie ustawień z sekcji Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:AnotherDbContext.

builder.AddNpgsqlDbContext<AnotherDbContext>();

Kontrole kondycji

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

Domyślnie integracja .NET AspirePostgreSQLEntity Framework Core obsługuje następujące elementy:

• Dodaje DbContextHealthCheck, który wywołuje metodę CanConnectAsyncEF Core. Nazwa sprawdzania kondycji odpowiada nazwie typu TContext.
• Integruje się z punktem końcowym HTTP /health, który określa, że wszystkie zarejestrowane testy kondycji muszą zostać pomyślnie zakończone, aby aplikacja była uznana za gotową do przyjmowania ruchu.

Obserwowanie i telemetria

.NET .NET Aspire integracje automatycznie konfigurują rejestrowanie, śledzenie i metryki, 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 AspirePostgreSQLEntity Framework Core używa następujących kategorii dzienników:

• Microsoft.EntityFrameworkCore.ChangeTracking
• Microsoft.EntityFrameworkCore.Database.Command
• Microsoft.EntityFrameworkCore.Database.Connection
• Microsoft.EntityFrameworkCore.Database.Transaction
• Microsoft.EntityFrameworkCore.Infrastructure
• Microsoft.EntityFrameworkCore.Infrastructure
• Microsoft.EntityFrameworkCore.Migrations
• Microsoft.EntityFrameworkCore.Model
• Microsoft.EntityFrameworkCore.Model.Validation
• Microsoft.EntityFrameworkCore.Query
• Microsoft.EntityFrameworkCore.Update

Śledzenie

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

• Npgsql

Metryki

Integracja .NET AspirePostgreSQLEntity Framework Core będzie emitować następujące metryki przy użyciu OpenTelemetry:

• Microsoft.EntityFrameworkCore:

  • ec_Microsoft_EntityFrameworkCore_active_db_contexts
  • ec_Microsoft_EntityFrameworkCore_total_queries
  • ec_Microsoft_EntityFrameworkCore_queries_per_second
  • ec_Microsoft_EntityFrameworkCore_total_save_changes
  • ec_Microsoft_EntityFrameworkCore_save_changes_per_second
  • ec_Microsoft_EntityFrameworkCore_compiled_query_cache_hit_rate
  • ec_Microsoft_Entity_total_execution_strategy_operation_failures
  • ec_Microsoft_E_execution_strategy_operation_failures_per_second
  • ec_Microsoft_EntityFramew_total_optimistic_concurrency_failures
  • ec_Microsoft_EntityF_optimistic_concurrency_failures_per_second

• 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 integracja hostingu

Aby wdrożyć zasoby PostgreSQL do Azure, zainstaluj pakiet NuGet 📦Aspire.Hosting.Azure.PostgreSQL.

.NET interfejsu wiersza polecenia

dotnet add package Aspire.Hosting.Azure.PostgreSQL

PackageReference

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

Dodawanie zasobu AzurePostgreSQLserver

Po zainstalowaniu integracji hostingu .NET AspireAzurePostgreSQL wywołaj metodę rozszerzenia AddAzurePostgresFlexibleServer w projekcie hostującym aplikację:

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 PostgreSQL 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 w celu włączenia uwierzytelniania.

.NET interfejsu wiersza polecenia

dotnet add package Azure.Identity

PackageReference

<PackageReference Include="Azure.Identity"
                  Version="*" />

Połączenie PostgreSQL można używać przy użyciu integracji client i Azure.Identity:

builder.AddNpgsqlDbContext<YourDbContext>(
    "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ż

• dokumentacja dla dotycząca bazy danychAzure dla PostgreSQL
• .NET .NET Aspire integracje
• .NET Aspire GitHub repozytorium