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

Modele integracji hostingu PostgreSQL modelują serwer PostgreSQL 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 poleceń

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 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 w poprzednim przykładzie z obrazem docker.io/library/postgres, tworzy nowe wystąpienie serwera PostgreSQL na komputerze lokalnym. Odwołanie do serwera PostgreSQL i wystąpienia bazy danych PostgreSQL (zmiennej postgresdb) służy do dodawania 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.

Wskazówka

Jeśli wolisz nawiązać połączenie z istniejącym serwerem PostgreSQL, 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 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...

Powyższy kod dodaje kontener w oparciu o obraz 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.

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

Powyższy kod dodaje kontener w oparciu o obraz 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 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 oraz powodów ich preferowania nad montowaniem wiązań , zobacz dokumentację Docker: 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...

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 danych serwera PostgreSQL między ponownymi uruchomieniami kontenera. Powiązanie danych jest montowane w C:\PostgreSQL\Data w systemie Windows (lub w /PostgreSQL/Data na Unix), w ścieżce na maszynie hosta, w kontenerze serwera PostgreSQL. Aby uzyskać więcej informacji na temat podłączenia danych bind, zobacz dokumentację Docker: Bind mounts.

Dodaj zasób serwera PostgreSQL z powiązaniem montowania init

Aby dodać wiążący punkt montowania init 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 służy do inicjowania, uruchamiania skryptów powłoki wykonywalnej lub plików poleceń .sql po utworzeniu folderu danych 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 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 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 AspirePostgreSQLEntity Framework Core, zainstaluj 📦Aspire. Npgsql.EntityFrameworkCore.PostgreSQL pakiet NuGet w projekcie korzystającym z klienta, czyli projekt aplikacji używającej klienta, który korzysta z klienta PostgreSQL. Integracja dla klienta .NET AspirePostgreSQLEntity Framework Core rejestruje żądane wystąpienia podklasy DbContext, które można wykorzystać do interakcji z PostgreSQL.

.NET interfejsu wiersza poleceń

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 korzystającego z klienta wywoł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");

Wskazówka

Parametr connectionName musi być zgodny z nazwą używaną podczas dodawania zasobu serwera PostgreSQL w projekcie hosta aplikacji. Aby uzyskać więcej informacji, zobacz Dodaj PostgreSQL zasób serwera.

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 klienta PostgreSQLEntity Framework CoreJSON, 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ę EF CoreCanConnectAsync. 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 poleceń

dotnet add package Aspire.Hosting.Azure.PostgreSQL

PackageReference

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

Dodawanie zasobu serwera AzurePostgreSQL

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 serwera PostgreSQL do wdrożenia jako AzurePostgres Elastyczny Server.

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 klienta Npgsql Azure z uwierzytelnieniem

Domyślnie, gdy wywołujesz AddAzurePostgresFlexibleServer w integracji hostingu PostgreSQL, konfiguruje to pakiet NuGet 📦Azure.Identity w celu włączenia uwierzytelniania.

.NET interfejsu wiersza poleceń

dotnet add package Azure.Identity

PackageReference

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

Połączenie PostgreSQL można wykorzystywać dzięki integracji z klientem 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