Dela via

.NET Aspire PostgreSQL Entity Framework Core integrering

  • Artikel

omfattar:Som värd för integrering och Client integration

PostgreSQL är ett kraftfullt objektrelationssystem med öppen källkod med många års aktiv utveckling som har gett det ett starkt rykte för tillförlitlighet, funktions robusthet och prestanda. Med .NET AspirePostgreSQLEntity Framework Core-integreringen kan du ansluta till befintliga PostgreSQL databaser eller skapa nya instanser från .NET med docker.io/library/postgres containeravbildningen.

Värdintegrering

Modellen för PostgreSQL integrering hostar en PostgreSQLserver som typ PostgresServerResource. För att komma åt den här typen och API:er som gör att du kan lägga till den i din 📦Aspire.HostingPostgreSQL NuGet-paket i appvärdprojekt.

dotnet add package Aspire.Hosting.PostgreSQL

Mer information finns i dotnet add package eller hantera paketsberoenden i .NET applikationer.

Lägg till PostgreSQLserver resurs

I appvärdprojektet anropar du AddPostgres på builder-instansen för att lägga till en PostgreSQLserver resurs och anropar sedan AddDatabase på postgres-instansen för att lägga till en databasresurs enligt följande exempel:

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

När .NET.NET Aspire lägger till en containeravbildning till appvärden, som du ser i föregående exempel med docker.io/library/postgres avbildningen, skapas en ny PostgreSQLserver instans på den lokala datorn. En referens till din PostgreSQLserver och din PostgreSQL databasinstans (postgresdb-variabeln) används för att lägga till ett beroende i ExampleProject. Den PostgreSQLserver resursen innehåller standardautentiseringsuppgifter med en username av "postgres" och slumpmässigt genererade password med hjälp av metoden CreateDefaultPasswordParameter.

Metoden WithReference konfigurerar en anslutning i ExampleProject med namnet "messaging". Mer information finns i Livscykel för containerresurser.

Tips

Om du hellre vill ansluta till en befintlig PostgreSQLserveranropar du AddConnectionString i stället. Mer information finns i Referera till befintliga resurser.

Lägg till PostgreSQL pgAdmin-resurs

När du lägger till PostgreSQL-resurser i builder med AddPostgres-metoden kan du kedja anrop till WithPgAdmin för att lägga till dpage/pgadmin4-container. Den här containern är en plattformsoberoende client för PostgreSQL databaser som hanterar ett webbaserat administratörsgränssnitt. Tänk på följande exempel:

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

Den föregående koden lägger till en container baserad på docker.io/dpage/pgadmin4-avbildningen. Containern används för att hantera PostgreSQLserver- och databasresurserna. Metoden WithPgAdmin lägger till en container som hanterar en webbaserad administratörsinstrumentpanel för PostgreSQL databaser.

Lägg till PostgreSQL pgWeb-resurs

När du lägger till PostgreSQL-resurser till builder med AddPostgres-metoden kan du kedja anrop till WithPgWeb för att lägga till sosedoff/pgweb-container. Den här containern är en plattformsoberoende client för PostgreSQL databaser som hanterar en webbaserad administrationspanel. Tänk på följande exempel:

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

Den föregående koden lägger till en container baserad på avbilden docker.io/sosedoff/pgweb. Alla registrerade PostgresDatabaseResource-instanser används för att skapa en konfigurationsfil per instans. Varje konfigurationsfil är bunden till katalogen för pgweb containerbokmärken. Mer information finns i PgWeb-dokument: Server anslutningsbokmärken.

Lägga till PostgreSQLserver resurs med datavolym

Om du vill lägga till en datavolym i den PostgreSQLserver resursen anropar du metoden WithDataVolume på den PostgreSQLserver resursen:

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

Datavolymen används för att bevara PostgreSQLserver data utanför containerns livscykel. Datavolymen monteras på sökvägen /var/lib/postgresql/data i containern PostgreSQLserver, och när en name-parameter inte anges genereras namnet slumpmässigt. Mer information om datavolymer och varför de föredras framför bindmonteringarfinns i Docker dokumenten: Volymer.

Lägg till PostgreSQLserver resurs med databindningsmontering

Om du vill lägga till en databindningsmontering till den PostgreSQLserver resursen anropar du metoden 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...

Viktig

Data bindningsmonteringar har begränsade funktioner jämfört med volymer, vilket ger bättre prestanda, portabilitet och säkerhet, vilket gör dem mer lämpliga för produktionsmiljöer. Bindningsmonteringar tillåter dock direkt åtkomst och ändring av filer i värdsystemet, perfekt för utveckling och testning där realtidsändringar behövs.

Databindningsmonteringar förlitar sig på värddatorns filsystem för att bevara PostgreSQLserver data mellan omstarter av containrar. Databindningsmonteringen monteras på sökvägen C:\PostgreSQL\Data i Windows (eller /PostgreSQL/Data på Unix) på värddatorn i PostgreSQLserver-containern. Mer information om datamonteringar finns i Docker dokumentationen: bindmonteringar.

Lägg till PostgreSQLserver resurs med init-bindmontering

Om du vill lägga till en init-bindmontering till resursen PostgreSQLserver, anropar du metoden 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...

Init-bindningsmonteringen förlitar sig på värddatorns filsystem för att initiera den PostgreSQLserver databasen med containrarna init mapp. Den här mappen används för initiering, körning av körbara gränssnittsskript eller .sql kommandofiler när mappen postgres-data har skapats. Init-bindmonteringen monteras på sökvägen C:\PostgreSQL\Init i Windows-miljön (eller /PostgreSQL/Init på Unix) på värddatorn i PostgreSQLserver-containern.

Lägga till PostgreSQLserver resurs med parametrar

När du uttryckligen vill ange användarnamnet och lösenordet som används av containeravbildningen kan du ange dessa autentiseringsuppgifter som parametrar. Tänk dig följande alternativa exempel:

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

Mer information om hur du tillhandahåller parametrar finns i Externa parametrar.

Hälsokontroller för integreringshosting

PostgreSQL värdintegrering lägger automatiskt till en hälsokontroll för den PostgreSQLserver resursen. Hälsokontrollen verifierar att PostgreSQLserver körs och att en anslutning kan upprättas till den.

Värdintegrering förlitar sig på 📦 AspNetCore.HealthChecks.Npgsql NuGet-paketet.

Client integration

För att komma igång med .NET AspirePostgreSQLEntity Framework Coreclient-integreringen genom att installera 📦Aspire.Npgsql.EntityFrameworkCore.PostgreSQL NuGet-paket i projektet som använder client, dvs. programprojektet som använder PostgreSQLclient. .NET Aspire PostgreSQL Entity Framework Core client-integreringen registrerar önskade DbContext underklassinstanser som du kan använda för att interagera med PostgreSQL.

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

Lägg till npgsql-databaskontext

I Program.cs-filen för ditt client-förbrukande projekt anropar du AddNpgsqlDbContext-tilläggsmetoden på valfri IHostApplicationBuilder för att registrera din DbContext-underklass för användning via containern för beroendeinjektion. Metoden tar en parameter för anslutningsnamn.

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

Tips

Parametern connectionName måste matcha namnet som används när du lägger till PostgreSQLserver-resursen i appvärdprojektet. Mer information finns i Lägg till PostgreSQLserver resurs.

När du har lagt till YourDbContext i byggaren kan du med hjälp av beroendeinjicering hämta YourDbContext-instansen. Om du till exempel vill hämta datakällobjektet från en exempeltjänst definierar du det som en konstruktorparameter och kontrollerar att klassen ExampleService är registrerad med containern för beroendeinmatning:

public class ExampleService(YourDbContext context)
{
    // Use context...
}

Mer information om beroendeinmatning finns i .NET beroendeinmatning.

Lägga till Npgsql-databaskontext med berikning

Om du vill utöka DbContext med ytterligare tjänster, till exempel automatiska återförsök, hälsokontroller, loggning och telemetri, anropar du metoden EnrichNpgsqlDbContext:

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

Parametern settings är en instans av klassen NpgsqlEntityFrameworkCorePostgreSQLSettings.

Konfiguration

Den .NET AspirePostgreSQLEntity Framework Core integreringen innehåller flera konfigurationsmetoder och alternativ för att uppfylla kraven och konventionerna i ditt projekt.

Använda en anslutningssträng

När du använder en anslutningssträng från ConnectionStrings konfigurationsavsnittet anger du namnet på anslutningssträngen när du anropar metoden AddNpgsqlDbContext:

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

Anslutningssträngen hämtas från avsnittet ConnectionStrings konfiguration:

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

EnrichNpgsqlDbContext använder inte ConnectionStrings-konfigurationsavsnittet eftersom det förväntar sig att en DbContext registreras vid den tidpunkt då den anropas.

Mer information finns i ConnectionString.

Använda konfigurationsprovidrar

.NET Aspire PostgreSQL Entity Framework Core-integreringen stöder Microsoft.Extensions.Configuration. Den läser in NpgsqlEntityFrameworkCorePostgreSQLSettings från konfigurationsfiler som appsettings.json med hjälp av Aspire:Npgsql:EntityFrameworkCore:PostgreSQL-nyckeln. Om du har konfigurerat konfigurationerna i avsnittet Aspire:Npgsql:EntityFrameworkCore:PostgreSQL kan du bara anropa metoden utan att skicka någon parameter.

I följande exempel visas en appsettings.json fil som konfigurerar några av de tillgängliga alternativen:

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

Det fullständiga PostgreSQLEntity Framework Coreclient integrationsschemat JSON finns i Aspire. Npgsql.EntityFrameworkCore.PostgreSQL/ConfigurationSchema.json.

Använd inlinedelegater

Du kan också delegera Action<NpgsqlEntityFrameworkCorePostgreSQLSettings> för att konfigurera vissa eller alla alternativ inlinje, till exempel för att ställa in ConnectionString:

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

Konfigurera flera DbContext-klasser

Om du vill registrera fler än en DbContext med en annan konfiguration kan du använda $"Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:{typeof(TContext).Name}" namn på konfigurationsavsnittet. Konfigurationen json skulle se ut så här:

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

Om du sedan anropar AddNpgsqlDbContext-metoden med parametern AnotherDbContext typ läser du in inställningarna från Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:AnotherDbContext avsnittet.

builder.AddNpgsqlDbContext<AnotherDbContext>();

Hälsokontroller

Som standard aktiverar .NET.NET Aspire integreringar hälsokontroller för alla tjänster. Mer information finns i översikten över .NET.NET Aspire integreringar.

Som standard hanterar .NET AspirePostgreSQLEntity Framework Core-integreringarna följande:

  • Lägger till DbContextHealthCheck, som anropar EF Core:s CanConnectAsync-metod. Namnet på hälsokontrollen är namnet på typen TContext.
  • Integrerar med /health HTTP-slutpunkt, som anger att alla registrerade hälsokontroller måste godkännas för att appen ska anses vara redo att acceptera trafik

Observerbarhet och telemetri

.NET .NET Aspire integreringar ställer automatiskt in loggning, spårning och mätvärden, vilket ibland kallas grundpelarna för observabilitet. Mer information om integreringsobservabilitet och telemetri finns i översikten över .NET.NET Aspire integreringar. Beroende på säkerhetskopieringstjänsten kanske vissa integreringar bara stöder vissa av dessa funktioner. Vissa integreringar stöder till exempel loggning och spårning, men inte mått. Telemetrifunktioner kan också inaktiveras med hjälp av de tekniker som visas i avsnittet Configuration.

Skogsavverkning

.NET Aspire PostgreSQL Entity Framework Core-integreringen använder följande loggkategorier:

  • 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

Spårning

Integreringen .NET AspirePostgreSQLEntity Framework Core genererar följande spårningsaktiviteter med hjälp av OpenTelemetry:

  • Npgsql

Mått

Integreringen .NET AspirePostgreSQLEntity Framework Core genererar följande mått med hjälp av 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 värdintegrering

Om du vill distribuera dina PostgreSQL-resurser till Azure, installera 📦Aspire.Hosting.Azure.PostgreSQL NuGet-paket:

dotnet add package Aspire.Hosting.Azure.PostgreSQL

Lägg till AzurePostgreSQLserver resurs

När du har installerat .NET AspireAzurePostgreSQL värdintegrering anropar du AddAzurePostgresFlexibleServer-tilläggsmetoden i appvärdprojektet:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddAzurePostgresFlexibleServer("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

Föregående anrop till AddAzurePostgresFlexibleServer konfigurerar PostgresSQL-server resursen som ska distribueras som en AzurePostgres flexibel Server.

Viktig

Som standard konfigurerar AddAzurePostgresFlexibleServerMicrosoft Entra-ID autentisering. Detta kräver ändringar i program som behöver ansluta till dessa resurser. Mer information finns i Client integration.

Lägg till autentiserade Npgsql Azureclient

När du anropar AddAzurePostgresFlexibleServer i din PostgreSQL värdintegrering konfigureras som standard 📦Azure. Identitet NuGet-paket för att aktivera autentisering:

dotnet add package Azure.Identity

Den PostgreSQL anslutningen kan användas med hjälp av client integrering och 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));
});

Föregående kodfragment visar hur du använder klassen DefaultAzureCredential från Azure.Identity-paketet för att autentisera med Microsoft Entra-ID och hämta en token för att ansluta till PostgreSQL-databasen. Metoden UsePeriodicPasswordProvider används för att tillhandahålla token till anslutningssträngsverktyget.

Se även