Aspire PostgreSQL Entity Framework Core integrering

Inkluderar:Värdintegrering ingår Värdintegrering &–& integrering ingår 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. Integreringen AspirePostgreSQLEntity Framework Core ger ett sätt att ansluta till befintliga PostgreSQL databaser eller skapa nya instanser från .NET med containeravbildningendocker.io/library/postgres.

Värdintegrering

PostgreSQL-värdintegrationen modellerar olika PostgreSQL-resurser som följande typer.

• PostgresServerResource
• PostgresDatabaseResource
• PgAdminContainerResource
• PgWebContainerResource

Om du vill komma åt dessa typer och API:er och uttrycka dem som resurser i "AppHost" i ditt projekt, installerar du NuGet-paketet .

dotnet add package Aspire.Hosting.PostgreSQL

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

Mer information finns i dotnet add package eller Hantera paketberoenden i .NET program.

Lägg till PostgreSQL serverresurs

I ditt AppHost-projekt anropar du AddPostgres instansen builder för att lägga till en PostgreSQL serverresurs och anropar AddDatabase sedan instansen postgres 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 Aspire lägger till en containeravbildning i AppHost, som visas i föregående exempel med docker.io/library/postgres-avbildningen, skapas en ny PostgreSQL-serverinstans på din lokala dator. En referens till din server och databasinstans PostgreSQL (variabeln postgresdb) används för att lägga till ett beroende på ExampleProject.

När du lägger till en databasresurs i appmodellen skapas databasen om den inte redan finns. Skapandet av databasen förlitar sig på AppHost-händelse-API:erna, särskilt ResourceReadyEvent. Med andra ord, när resursen postgres är klar utlöses händelsen och databasresursen skapas.

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

Lägga till PostgreSQL resurs med databasskript

När du lägger till en PostgresDatabaseResourceförlitar den sig som standard på följande skript för att skapa databasen:

CREATE DATABASE "<QUOTED_DATABASE_NAME>"

Om du vill ändra standardskriptet kedjar du ett anrop till WithCreationScript(IResourceBuilder<PostgresDatabaseResource>, String) metoden i databasresursverktyget:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres");

var databaseName = "app_db";
var creationScript = $$"""
    -- Create the database
    CREATE DATABASE {{databaseName}};

    """;

var db = postgres.AddDatabase(databaseName)
                 .WithCreationScript(creationScript);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

// After adding all resources, run the app...

I föregående exempel skapas en databas med namnet app_db. Skriptet körs när databasresursen skapas. Skriptet skickas som en sträng till WithCreationScript metoden, som sedan körs i resursens PostgreSQL kontext.

Lägg till PostgreSQL pgAdmin-resurs

När du lägger till PostgreSQL resurser i builder med metoden AddPostgres kan du kedja anrop till WithPgAdmin för att lägga till behållaren dpage/pgadmin4. Den här containern är en plattformsoberoende klient för PostgreSQL databaser som hanterar en webbaserad administratörsinstrumentpanel. 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 PostgreSQL server- och databasresurser. Metoden WithPgAdmin lägger till en container som hanterar en webbaserad administratörsinstrumentpanel för PostgreSQL databaser.

Konfigurera värdporten för pgAdmin

Om du vill konfigurera värdporten för pgAdmin-containern anropar du metoden WithHostPort på PostgreSQL serverresursen. I följande exempel visas hur du konfigurerar värdporten för pgAdmin-containern:

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

Föregående kod lägger till och konfigurerar värdporten för pgAdmin-containern. Värdporten tilldelas annars slumpmässigt.

Lägg till PostgreSQL pgWeb-resurs

När du lägger till PostgreSQL resurser i 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 klient för PostgreSQL databaser som hanterar en webbaserad administratörsinstrumentpanel. 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å docker.io/sosedoff/pgweb-avbildningen. Alla registrerade PostgresDatabaseResource instanser används för att skapa en konfigurationsfil per instans och varje konfiguration är bunden till katalogen för pgweb-containerns bokmärke. Mer information finns i PgWeb-dokument: Server anslutningsbokmärken.

Konfigurera pgWeb-värdporten

Om du vill konfigurera värdporten för pgWeb-containern anropar du metoden WithHostPort på PostgreSQL-serverresursen. I följande exempel visas hur du konfigurerar värdporten för pgAdmin-containern:

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

Föregående kod lägger till och konfigurerar värdporten för pgWeb-containern. Värdporten tilldelas annars slumpmässigt.

Lägga till PostgreSQL serverresurs med datavolym

Om du vill lägga till en datavolym i PostgreSQL-serverresursen anropar du metoden WithDataVolume på PostgreSQL serverresursen:

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 PostgreSQL serverdata utanför containerns livscykel. Datavolymen monteras på sökvägen /var/lib/postgresql/data i PostgreSQL-servercontainern, och om ingen name-parameter anges genereras namnet slumpvis. Mer information om datavolymer och information om varför de föredras framför bindningsmonteringar finns i Docker dokument: Volymer.

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddAzurePostgresFlexibleServer("postgres")
                      .RunAsContainer(container => 
                      {
                        container.WithDataVolume();
                      });

builder.Build().Run();

Lägg till PostgreSQL serverresurs med databindningspunkt

Om du vill lägga till en databindningsmontering till PostgreSQL-serverresursen 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...

Databindningsmonteringar använder värddatorns filsystem för att bevara PostgreSQL serverdatan vid containraromstarter. Databindningen monteras på C:\PostgreSQL\Data på Windows (eller /PostgreSQL/Data på Unix) på värddatorn i servercontainern PostgreSQL. Mer information om databindningsmonteringar finns i Docker dokument: Bindningsmonteringar.

Lägg till PostgreSQL serverresurs med init-bind mount

Om du vill lägga till en init-bindningsmontering till PostgreSQL-serverresursen 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-bindmounten förlitar sig på värddatorns filsystem för att initiera PostgreSQL serverdatabasen med containerns init-mapp. Den här mappen används för initiering, körning av körbara gränssnittsskript eller .sql kommandofiler när postgres-data-mappen har skapats . Init-bindningen är monterad på sökvägen C:\PostgreSQL\Init i Windows (eller /PostgreSQL/Init på Unix) på värddatorn i servercontainern PostgreSQL.

Lägga till PostgreSQL serverresurs 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 PostgreSQL serverresursen. Hälsokontrollen verifierar att PostgreSQL-servern körs och att en anslutning kan upprättas till den.

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

Client integration

Kom igång med klientintegrering genom AspirePostgreSQLEntity Framework Core att 📦Aspireinstallera . Npgsql.EntityFrameworkCore.PostgreSQL NuGet-paket i det klientkrävande projektet, det vill s.v.s. projektet för det program som använder PostgreSQL klienten. Aspire PostgreSQL Entity Framework Core-klientintegrering registrerar önskade DbContext underklassinstanser som du kan använda för att interagera med PostgreSQL.

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

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

Lägg till npgsql-databaskontext

I den Program.cs filen för ditt klientprojekt 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");

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.

Förbättra en Npgsql-databaskontext

Du kanske föredrar att använda entitetsramverkets standardmetod för att hämta en databaskontext och lägga till den i containern för beroendeinmatning:

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

Du har större flexibilitet när du skapar databaskontexten på det här sättet, till exempel:

• Du kan återanvända befintlig konfigurationskod för databaskontexten utan att skriva om den för Aspire.
• Du kan använda Entity Framework Core interceptorer för att ändra databasåtgärder.
• Du kan välja att inte använda Entity Framework Core kontextpooler, vilket kan fungera bättre under vissa omständigheter.

Om du använder den här metoden kan du förbättra databaskontexten med Aspire-style-återförsök, hälsokontroller, loggning och telemetrifunktioner genom att anropa EnrichNpgsqlDbContext metoden:

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

Parametern settings är en instans av klassen NpgsqlEntityFrameworkCorePostgreSQLSettings.

Konfiguration

Den 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

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

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

Använd inlinedelegater

Du kan också skicka Action<NpgsqlEntityFrameworkCorePostgreSQLSettings> för att konfigurera vissa eller alla alternativ direkt, 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. Json-konfigurationen skulle se ut så här:

{
  "Aspire": {
    "Npgsql": {
      "EntityFrameworkCore": {
        "PostgreSQL": {
          "ConnectionString": "<YOUR CONNECTION STRING>",
          "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>();

Client hälsokontroller för integrering

Som standard Aspire har klientintegreringarhälsokontroller aktiverade för alla tjänster. På samma sätt möjliggör många Aspirehostingintegrationer även hälsokontrolländpunkter. Mer information finns i:

• .NET hälsokontroller för appar i C#
• Hälsokontroller i ASP.NET Core

Som standard hanterar 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

Aspire integreringar konfigurerar automatiskt konfigurationer för loggning, spårning och mått, som ibland kallas grundpelarna för observerbarhet. Mer information om integreringsobservabilitet och telemetri finns i Aspire översikten över 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 Konfiguration .

Skogsavverkning

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.Migrations
• Microsoft.EntityFrameworkCore.Infrastructure
• Microsoft.EntityFrameworkCore.Migrations
• Microsoft.EntityFrameworkCore.Model
• Microsoft.EntityFrameworkCore.Model.Validation
• Microsoft.EntityFrameworkCore.Query
• Microsoft.EntityFrameworkCore.Update

Spårning

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

• Npgsql

Mått

Integreringen 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

Se även

• PostgreSQL dokumentation
• Aspire Azure PostgreSQL Entity Framework Core integration
• Aspire Integrationer
• Aspire GitHub Repo