Sdílet prostřednictvím

integrace .NET AspirePostgreSQLEntity Framework Core

  • Článek

zahrnuje:integraci hostování a Client integraci

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í

PostgreSQL hostování integračních modelů PostgreSQLserver jako typ PostgresServerResource. Přístup k tomuto typu a rozhraním API, které vám umožní jej přidat do balíčku NuGet pro hostování 📦Aspire.PostgreSQL v projektu hostitele aplikace .

dotnet add package Aspire.Hosting.PostgreSQL

Další informace najdete v tématu dotnet add package nebo Manage package dependencies in .NET applications.

Přidání prostředku PostgreSQLserver

V projektu hostitele aplikace zavolejte AddPostgres pro instanci builder, abyste přidali PostgreSQLserver prostředek, a potom zavolejte AddDatabase pro instanci postgres, abyste přidali 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"postgres" a náhodně vygenerovanými password pomocí metody CreateDefaultPasswordParameter.

Metoda WithReference nakonfiguruje připojení v ExampleProject s názvem "messaging". Další informace naleznete v části Životní cyklus prostředků kontejneru.

Spropitné

Pokud byste se raději připojili k existujícímu PostgreSQLserver, volejte místo toho AddConnectionString. Další informace naleznete v sekci Reference k existujícím zdrojům.

Přidání prostředku PostgreSQL pgAdmin

Při přidávání PostgreSQL prostředků do builder pomocí metody AddPostgres můžete řetězit volání na WithPgAdmin k přidání kontejneru dpage/pgadmin4. Tento kontejner je multiplatformní client pro PostgreSQL databáze, který obsluhuje administrátorský panel na webu. 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 na základě 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 pro přidání sosedoff/pgweb kontejneru. Tento kontejner je multiplatformní client pro PostgreSQL databáze, který poskytuje webový administrační 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 připojení.

Přidání PostgreSQLserver prostředku 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č se upřednostňují před připojeními typu bind mounts, najdete v dokumentaci Docker: Svazky.

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

Pokud chcete přidat připojení datové vazby 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řesto přípojná místa umožňují přímý přístup a úpravy souborů na hostitelském systému, což je ideální pro vývoj a testování, kde jsou potřeba změny v reálném čase.

Vázání dat spoléhají na souborový systém hostitele pro uchování PostgreSQLserver dat při restartech kontejneru. Datové svazování připojení je připojeno k cestě C:\PostgreSQL\Data na 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řidejte PostgreSQLserver prostředek s bind mount pro inicializaci

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í init spoléhá na systém souborů hostitelského počítače pro inicializaci PostgreSQLserver databáze pomocí složky init kontejnerů . Tato složka se používá k inicializaci a k spuštění všech spustitelných skriptů prostředí nebo souborů příkazů .sql po vytvoření složky postgres-data. Inicializační připojení je připojeno na C:\PostgreSQL\Init ve Windows (nebo na /PostgreSQL/Init na Unix) na hostitelském počítači v kontejneru PostgreSQLserver.

Přidejte prostředek 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 jsou spuštěny PostgreSQLserver a že se k nim 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 AspirePostgreSQLEntity Framework Coreclient, nainstalujte 📦Aspire. Npgsql.EntityFrameworkCore.PostgreSQL balíček NuGet v projektu client, tj. projekt pro aplikaci, která používá PostgreSQLclient. Integrace .NET AspirePostgreSQLEntity Framework Coreclient registruje požadované instance podtřídy DbContext, které můžete použít k interakci s PostgreSQL.

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

Přidání kontextu databáze Npgsql

V souboru Program.cs projektu využívajícího clientzavolejte metodu rozšíření AddNpgsqlDbContext na libovolném IHostApplicationBuilder a zaregistrujte podtřídu DbContext pro použití prostřednictvím kontejneru injektáže závislostí. Metoda přebírá parametr názvu připojení.

builder.AddNpgsqlDbContext<YourDbContext>(connectionName: "postgresdb");

Spropitné

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í YourDbContext do builderu můžete získat instanci YourDbContext 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(YourDbContext context)
{
    // Use context...
}

Další informace o injektáži závislostí najdete v tématu .NET injektáž závislostí.

Přidání kontextu databáze Npgsql s rozšířením

Pokud chcete rozšířit DbContext dalšími službami, jako jsou automatické opakování, kontroly stavu, protokolování a telemetrie, zavolejte metodu EnrichNpgsqlDbContext:

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

Parametr settings je instance třídy NpgsqlEntityFrameworkCorePostgreSQLSettings.

Konfigurace

Integrace .NET AspirePostgreSQLEntity Framework Core poskytuje několik přístupů a možností konfigurace pro splnění požadavků a konvencí projektu.

Použijte připojovací řetězec

Při použití připojovacího řetězce z oddílu konfigurace ConnectionStrings zadáte název připojovacího řetězce při volání metody AddNpgsqlDbContext:

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

Připojovací řetězec je získán z oddílu konfigurace ConnectionStrings.

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

EnrichNpgsqlDbContext nepoužije oddíl konfigurace ConnectionStrings, protože očekává, že se DbContext zaregistruje v okamžiku, kdy se volá.

Další informace naleznete v ConnectionString.

Použití zprostředkovatelů konfigurace

Integrace .NET AspirePostgreSQLEntity Framework Core podporuje Microsoft.Extensions.Configuration. Načte NpgsqlEntityFrameworkCorePostgreSQLSettings z konfiguračních souborů, jako je appsettings.json, pomocí klíče Aspire:Npgsql:EntityFrameworkCore:PostgreSQL. Pokud jste nastavili konfigurace v oddílu Aspire:Npgsql:EntityFrameworkCore:PostgreSQL, stačí volat metodu bez předání jakéhokoli parametru.

Následující příklad ukazuje soubor appsettings.json, který konfiguruje některé z dostupných možností:

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

Kompletní schéma integrace PostgreSQLEntity Framework CoreclientJSON najdete v tématu Aspire. Npgsql.EntityFrameworkCore.PostgreSQL/ConfigurationSchema.json.

Použití vložených delegátů

Můžete také předat delegáta Action<NpgsqlEntityFrameworkCorePostgreSQLSettings> k nastavení některých nebo všech možností přímo, například k nastavení ConnectionString:

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

Konfigurace více tříd DbContext

Pokud chcete zaregistrovat více DbContext s různými konfiguracemi, můžete použít název konfigurační sekce $"Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:{typeof(TContext).Name}". Konfigurace json by vypadala takto:

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

Volání metody AddNpgsqlDbContext s parametrem typu AnotherDbContext by pak načetlo nastavení z oddílu Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:AnotherDbContext.

builder.AddNpgsqlDbContext<AnotherDbContext>();

Kontroly stavu

Integrace .NET.NET Aspire ve výchozím nastavení umožňují kontroly stavu pro všechny služby. Další informace naleznete v přehledu integrací .NET.NET Aspire.

Integrace .NET AspirePostgreSQLEntity Framework Core ve výchozím nastavení zpracovává následující:

  • Přidá DbContextHealthCheck, která volá metodu CanConnectAsyncEF Core. Název kontroly zdraví je název typu TContext.
  • Integruje se s HTTP koncovým bodem /health, který stanoví, že všechny registrované zdravotní kontroly musí být úspěšně dokončeny, aby byla aplikace považována za připravenou k přijetí provozu.

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 AspirePostgreSQLEntity Framework Core používá následující kategorie protokolů:

  • 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

Trasování

Integrace .NET AspirePostgreSQLEntity Framework Core pomocí OpenTelemetryvygeneruje následující aktivity trasování:

  • Npgsql

Metody měření dat

Integrace .NET AspirePostgreSQLEntity Framework Core pomocí OpenTelemetryvygeneruje následující metriky:

  • 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

integrace hostování AzurePostgreSQL

Pokud chcete nasadit prostředky PostgreSQL do Azure, nainstalujte balíček NuGet 📦Aspire.Hostování.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řidat autentizovaný Azure Npgsql client

Ve výchozím nastavení se při volání AddAzurePostgresFlexibleServer v PostgreSQL integračního hostování nakonfiguruje 📦AzureIdentita balíčku NuGet pro povolení ověřování:

dotnet add package Azure.Identity

Připojení PostgreSQL lze využívat pomocí integrace client a 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));
});

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 tvůrci připojovacích řetězců.

Viz také