integrace .NET AspirePostgreSQLEntity Framework Core

Článek
03/08/2025

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í

Integrační modely hostování zpracovávají různé prostředky jako následující typy.

Chcete-li získat přístup k těmto typům a API pro jejich vyjádření jako prostředky v projektu hostitele aplikace , nainstalujte balíček NuGet .Hosting.:

.NET rozhraní příkazového řádku
PackageReference

dotnet add package Aspire.Hosting.PostgreSQL

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

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

Přidání prostředku serveru PostgreSQL

V hostitelském projektu aplikace zavolejte AddPostgres na instanci builder a přidejte prostředek serveru PostgreSQL a potom zavolejte AddDatabase na instanci postgres a přidejte prostředek databáze, 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 serveru PostgreSQL. Odkaz na váš PostgreSQL server a instanci databáze PostgreSQL (proměnnou postgresdb) slouží k přidání závislosti do ExampleProject. Prostředek serveru PostgreSQL obsahuje výchozí přihlašovací údaje s parametrem username nastaveným na "postgres" a náhodně vygenerovaným password pomocí metody CreateDefaultPasswordParameter.

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

Spropitné

Pokud byste se raději připojili k existujícímu serveru PostgreSQL, 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í klient pro PostgreSQL databáze, který slouží webovému řídicímu panelu pro správu. 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ě PostgreSQL serverových 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.

Nakonfigurujte port hostitele pgAdmin

Pokud chcete nakonfigurovat port hostitele pro kontejner pgAdmin, zavolejte metodu WithHostPort prostředku serveru PostgreSQL. Následující příklad ukazuje, jak nakonfigurovat port hostitele pro kontejner 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...

Předchozí kód přidá a nakonfiguruje port hostitele pro kontejner pgAdmin. Port hostitele je jinak náhodně přiřazen.

PostgreSQL Přidejte prostředek pgWeb

Při přidávání PostgreSQL prostředků do builder pomocí metody AddPostgres můžete volání na WithPgWeb řetězit pro přidání kontejneru sosedoff/pgweb. Tento kontejner je multiplatformní klient pro PostgreSQL databáze, který slouží webovému řídicímu panelu pro správu. 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 na základě 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í.

Nakonfigurujte port hostitele pgWeb

Pokud chcete nakonfigurovat port hostitele pro kontejner pgWeb, zavolejte metodu WithHostPort na prostředku serveru PostgreSQL. Následující příklad ukazuje, jak nakonfigurovat port hostitele pro kontejner 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...

Předchozí kód přidá a nakonfiguruje port hostitele pro kontejner pgWeb. Port hostitele je jinak náhodně přiřazen.

Přidejte serverový prostředek PostgreSQL s datovým svazkem

Chcete-li přidat datový objem do serverového prostředku PostgreSQL, použijte metodu WithDataVolume na serverovém prostředku 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...

Datový svazek slouží k zachování dat serveru PostgreSQL mimo životní cyklus kontejneru. Datový svazek se připojí k cestě /var/lib/postgresql/data v kontejneru serveru PostgreSQL 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řidejte prostředek serveru PostgreSQL s datovým svazkem typu bind.

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

Vazby datových svazků spoléhají na systém souborů hostitelského počítače k zachování dat serveru PostgreSQL při restartech kontejneru. Připojení vazby dat je připojeno k C:\PostgreSQL\Data v systému Windows (nebo /PostgreSQL/Data na Unix) v hostitelském počítači v kontejneru serveru PostgreSQL. Další informace o připojeních datových vazeb najdete v dokumentaci Docker: Připojení vazby.

Přidejte prostředek serveru PostgreSQL s připojením prostřednictvím bind mountu při inicializaci

Chcete-li přidat init bind mount k prostředku serveru PostgreSQL, 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í inicializační vazby spoléhá na systém souborů hostitelského počítače pro inicializaci databáze serveru pomocí složky init kontejneru. Tato složka se používá k inicializaci a poté ke spuštění jakýchkoli spustitelných skriptů prostředí nebo souborů příkazů .sql po vytvoření složky postgres-data. Připojení "init bind mount" je připojeno k cestě C:\PostgreSQL\Init ve Windows (nebo /PostgreSQL/Init na Unix) na hostitelském počítači v rámci kontejneru serveru PostgreSQL.

Přidat prostředek serveru PostgreSQL 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

Při integraci hostingu PostgreSQL se automaticky přidá kontrola stavu pro serverový prostředek PostgreSQL. Kontrola stavu ověřuje, jestli je server PostgreSQL spuštěný a že se k němu 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í klienta .NET AspirePostgreSQLEntity Framework Core, nainstalujte balíček NuGet 📦Aspire.Npgsql.EntityFrameworkCore.PostgreSQL do projektu, který využívá klienta, tedy do projektu aplikace používajícího klienta PostgreSQL. Integrace klienta .NET AspirePostgreSQLEntity Framework Core registruje požadované instance podtřídy DbContext, které můžete použít k interakci s PostgreSQL.

.NET rozhraní příkazového řádku
PackageReference

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

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

Přidání kontextu databáze Npgsql

V souboru Program.cs ve vašem projektu, který využívá klienta, zavolejte metodu rozšíření AddNpgsqlDbContext na jakémkoli objektu IHostApplicationBuilder a zaregistrujte podtřídu DbContext pro použití prostřednictvím kontejneru pro injektáž 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 serveru PostgreSQL v projektu hostitele aplikace. Další informace najdete v tématu Přidání prostředku serveru PostgreSQL.

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

Obohacení kontextu databáze Npgsql

Pokud chcete získat kontext databáze a přidat ji do kontejneru injektáže závislostí, můžete raději použít standardní metodu Entity Framework:

builder.Services.AddDbContext<YourDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("postgresdb")
        ?? throw new InvalidOperationException("Connection string 'postgresdb' not found.")));

Poznámka

Název připojovacího řetězce, který předáte metodě GetConnectionString, se musí shodovat s názvem použitým při přidávání prostředku serveru PostgreSQL do hostitelského projektu aplikace. Další informace najdete v tématu Přidání prostředku serveru PostgreSQL.

Při vytváření kontextu databáze tímto způsobem máte větší flexibilitu, například:

Existující konfigurační kód pro kontext databáze můžete znovu použít, aniž byste ho museli přepisovat pro .NET.NET Aspire.
Můžete použít Entity Framework Core zachytávače k úpravě databázových operací.
Můžete se rozhodnout, že nebudete používat Entity Framework Core sdružování kontextu, což může za určitých okolností fungovat lépe.

Pokud použijete tuto metodu, můžete vylepšit kontext databáze pomocí opakování ve stylu .NET.NET Aspire, kontrol stavu, protokolování a funkcí telemetrie voláním metody EnrichNpgsqlDbContext.

builder.EnrichNpgsqlDbContext<YourDbContext>(
    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");

Řetězec připojení je získán z konfiguračního oddílu 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",
          "DisableHealthChecks": true,
          "DisableTracing": true
        }
      }
    }
  }
}

Kompletní schéma integrace klienta PostgreSQLEntity Framework CoreJSON najdete v 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>",
          "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>();

Client testy stavu integrace

Ve výchozím nastavení mají .NET.NET Aspireklientské integracekontroly stavu povoleny pro všechny služby. Podobně mnoho integrací .NET.NET Aspirehostingu také povoluje kontrolní body zdraví. Další informace najdete tady:

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

Přidá DbContextHealthCheck, která volá metodu CanConnectAsync objektu EF 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.Migrations
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

Sdílet prostřednictvím