integrace .NET AspirePostgreSQLEntity Framework Core

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ů různé PostgreSQL prostředky jako následující typy.

• PostgresServerResource
• PostgresDatabaseResource
• PgAdminContainerResource
• PgWebContainerResource

Pokud chcete získat přístup k těmto typům a API pro jejich vyjádření jako prostředky v hostiteli aplikace projektu, nainstalujte 📦Aspire.Hosting. balíček NuGetPostgreSQL:

dotnet add package Aspire.Hosting.PostgreSQL

PackageReference

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

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

Nastavte 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")
                      .WithPgAdmin(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řidání serverového prostředku PostgreSQL s datovým svazkem

Pokud chcete přidat datový svazek do prostředku PostgreSQL serveru, zavolejte metodu WithDataVolume prostředku serveru 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řidání prostředku serveru PostgreSQL s připojením vazby dat

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

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

Pokud chcete přidat připojení inicializační vazby 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 k inicializaci databáze serveru PostgreSQL s kontejnery inicializovat složku. 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

Integrace hostování PostgreSQL automaticky přidá kontrolu stavu pro prostředek serveru 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.

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

PackageReference

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

Přidání kontextu databáze Npgsql

V souboru Program.cs projektu, který využívá klienta, zavolejte 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 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í.

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",
          "DisableHealthChecks": true,
          "DisableTracing": true
        }
      }
    }
  }
}

Kompletní schéma integrace klienta PostgreSQLEntity Framework CoreJSON naleznete 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>",
          "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 EF CoreCanConnectAsync. 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

Viz také

• PostgreSQL dokumenty
• .NET Aspire Azure PostgreSQL Entity Framework Core integrace
• integrace .NET.NET Aspire
• .NET Aspire GitHub repo úložiště