integratie van AspirePostgreSQLEntity Framework Core

Inclusief: —&— Client integratie

PostgreSQL is een krachtig opensource-object-relationeel databasesysteem met vele jaren actieve ontwikkeling die het een sterke reputatie heeft verdiend voor betrouwbaarheid, robuustheid en prestaties. De AspirePostgreSQLEntity Framework Core-integratie biedt een manier om verbinding te maken met bestaande PostgreSQL-databases of nieuwe exemplaren te maken vanuit .NET met de docker.io/library/postgres-containerimage.

Hostingintegratie

De PostgreSQL hostingintegratie modelleert PostgreSQL resources als de volgende typen.

• PostgresServerResource
• PostgresDatabaseResource
• PgAdminContainerResource
• PgWebContainerResource

Als u toegang wilt krijgen tot deze typen en API's om ze uit te drukken als resources in uw AppHost-project , installeert u het 📦Aspire. Gastvrijheid.PostgreSQL NuGet-pakket:

dotnet add package Aspire.Hosting.PostgreSQL

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

Zie dotnet pakket toevoegen of Pakketafhankelijkheden beheren in .NET toepassingenvoor meer informatie.

PostgreSQL serverresource toevoegen

Roep in uw AppHost-project AddPostgres het builder exemplaar aan om een PostgreSQL serverresource toe te voegen en roep AddDatabase vervolgens het postgres exemplaar aan om een databaseresource toe te voegen, zoals wordt weergegeven in het volgende voorbeeld:

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

Wanneer Aspire een containerafbeelding toevoegt aan de AppHost, zoals wordt weergegeven in het voorgaande voorbeeld met de docker.io/library/postgres afbeelding, wordt er een nieuw PostgreSQL serverexemplaar gemaakt op uw lokale computer. Een verwijzing naar uw PostgreSQL server- en database-exemplaar (de postgresdb variabele) wordt gebruikt om een afhankelijkheid toe te voegen aan de ExampleProject.

Wanneer u een databaseresource toevoegt aan het app-model, wordt de database gemaakt als deze nog niet bestaat. Het maken van de database is afhankelijk van de AppHost-gebeurtenis-API's, met name ResourceReadyEvent. Met andere woorden, wanneer de postgres resource gereed is, wordt de gebeurtenis veroorzaakt en wordt de database-resource gemaakt.

De PostgreSQL-server-resource bevat standaardgegevens met een username van "postgres" en willekeurig gegenereerde password met behulp van de CreateDefaultPasswordParameter-methode.

De methode WithReference configureert een verbinding in de ExampleProject met de naam "messaging". Zie levenscyclus van containerresourcesvoor meer informatie.

Een resource toevoegen PostgreSQL met databasescripts

Wanneer u een PostgresDatabaseResourcetoevoegt, is het standaard afhankelijk van het volgende script om de database te maken:

CREATE DATABASE "<QUOTED_DATABASE_NAME>"

Als u het standaardscript wilt wijzigen, koppelt u een aanroep aan de WithCreationScript(IResourceBuilder<PostgresDatabaseResource>, String) methode in de opbouwfunctie voor databaseresources:

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

In het voorgaande voorbeeld wordt een database gemaakt met de naam app_db. Het script wordt uitgevoerd wanneer de databaseresource wordt gemaakt. Het script wordt doorgegeven als een tekenreeks aan de WithCreationScript methode, die vervolgens wordt uitgevoerd in de context van de PostgreSQL resource.

PostgreSQL pgAdmin-resource toevoegen

Wanneer u PostgreSQL resources toevoegt aan de builder met de methode AddPostgres, kunt u aanroepen koppelen aan WithPgAdmin om de dpage/pgadmin4--container toe te voegen. Deze container is een platformoverschrijdende client voor PostgreSQL databases die een webgebaseerde beheerdashboard dient. Bekijk het volgende voorbeeld:

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

Met de voorafgaande code wordt een container toegevoegd op basis van het docker.io/dpage/pgadmin4-image. De container wordt gebruikt voor het beheren van de PostgreSQL server- en databasebronnen. Met de methode WithPgAdmin wordt een container toegevoegd die een webbeheerdashboard voor PostgreSQL databases bedient.

De pgAdmin-hostpoort configureren

Als u de hostpoort voor de pgAdmin-container wilt configureren, roept u de WithHostPort methode aan op de PostgreSQL serverresource. In het volgende voorbeeld ziet u hoe u de hostpoort voor de pgAdmin-container configureert:

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

Met de voorgaande code wordt de hostpoort voor de pgAdmin-container toegevoegd en geconfigureerd. De hostpoort wordt anders willekeurig toegewezen.

PostgreSQL pgWeb-resource toevoegen

Wanneer u PostgreSQL resources toevoegt aan de builder met de methode AddPostgres, kunt u aanroepen koppelen aan WithPgWeb om de sosedoff/pgweb--container toe te voegen. Deze container is een platformoverschrijdende client voor PostgreSQL databases die een webgebaseerde beheerdashboard dient. Bekijk het volgende voorbeeld:

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

Met de voorafgaande code wordt een container toegevoegd op basis van het docker.io/sosedoff/pgweb-image. Alle geregistreerde PostgresDatabaseResource-exemplaren worden gebruikt om een configuratiebestand voor elk exemplaar te maken en elke configuratie is gebonden aan de pgweb container bladwijzermap. Zie de PgWeb-documenten: Server bladwijzers voor verbindingen voor meer informatie.

De pgWeb-hostpoort configureren

Als u de hostpoort voor de pgWeb-container wilt configureren, roept u de WithHostPort methode aan op de PostgreSQL-serverresource. In het volgende voorbeeld ziet u hoe u de hostpoort voor de pgAdmin-container configureert:

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

Met de voorgaande code wordt de hostpoort voor de pgWeb-container toegevoegd en geconfigureerd. De hostpoort wordt anders willekeurig toegewezen.

PostgreSQL serverresource toevoegen met gegevensvolume

Als u een gegevensvolume wilt toevoegen aan de PostgreSQL serverresource, roept u de WithDataVolume methode aan op de PostgreSQL serverresource:

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

Het gegevensvolume wordt gebruikt om de PostgreSQL servergegevens buiten de levenscyclus van de container te behouden. Het gegevensvolume wordt gekoppeld aan het /var/lib/postgresql/data pad in de PostgreSQL servercontainer en wanneer er geen name parameter wordt opgegeven, wordt de naam willekeurig gegenereerd. Voor meer informatie over datavolumes en details over waarom ze de voorkeur hebben boven bind-mounts, zie Docker docs: Volumes.

var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();

PostgreSQL serverbron toevoegen met data-bind mount

Als u een gegevensbindingskoppeling wilt toevoegen aan de PostgreSQL-serverresource, roept u de methode WithDataBindMount aan:

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

Gegevensbindmontages zijn afhankelijk van het bestandssysteem van de hostmachine om de PostgreSQL-servergegevens bij herstarten van de container te behouden. De data bind-mount wordt aangekoppeld aan het pad C:\PostgreSQL\Data op Windows (of /PostgreSQL/Data op Unix) op de hostcomputer in de PostgreSQL servercontainer. Zie Docker docs: Bindingskoppelingen voor meer informatie over gegevensbindkoppelingen.

Voeg PostgreSQL serverhulpbron toe met init bind mount

Als u een init-bindingskoppeling wilt toevoegen aan de PostgreSQL-serverresource, roept u de methode WithInitBindMount aan:

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

De init-bindmount is afhankelijk van het bestandssysteem van de hostmachine voor het initialiseren van de PostgreSQL serverdatabase met de init map van de containers. Deze map wordt gebruikt voor initialisatie, het uitvoeren van uitvoerbare shellscripts of .sql opdrachtbestanden nadat de postgres-gegevens map is gemaakt. De init-bindmount wordt gekoppeld aan de C:\PostgreSQL\Init op het Windows-pad (of /PostgreSQL/Init op Unix) van de hostcomputer in de PostgreSQL-servercontainer.

PostgreSQL serverresource toevoegen met parameters

Als u expliciet de gebruikersnaam en het wachtwoord wilt opgeven die door de containerafbeelding worden gebruikt, kunt u deze inloggegevens als parameters opgeven. Bekijk het volgende alternatieve voorbeeld:

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

Zie Externe parametersvoor meer informatie over het opgeven van parameters.

Gezondheidscontroles voor hostingintegratie

De PostgreSQL hostingintegratie voegt automatisch een statuscontrole toe voor de PostgreSQL serverresource. De gezondheidscontrole controleert of de PostgreSQL-server draait en of er een verbinding mee kan worden gemaakt.

De hostingintegratie is afhankelijk van het 📦 AspNetCore.HealthChecks.Npgsql NuGet-pakket.

Client integratie

Installeer het NuGet-pakket Aspire in het clientgebruikende project, dat wil zeggen het project voor de toepassing die gebruikmaakt van de PostgreSQL-client, om aan de slag te gaan met de Entity Framework Core📦Aspire-clientintegratie. De AspirePostgreSQLEntity Framework Core-clientintegratie registreert de gewenste DbContext subklasse-exemplaren die u kunt gebruiken om met PostgreSQLte communiceren.

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

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

De Npgsql-database context toevoegen

Roep in het Program.cs bestand van het clientgebruikte project de AddNpgsqlDbContext-extensiemethode aan op elke IHostApplicationBuilder om uw DbContext subklasse te registreren voor gebruik via de container voor afhankelijkheidsinjectie. De methode gebruikt een verbindingsnaamparameter.

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

Nadat u YourDbContext aan de builder hebt toegevoegd, kunt u de YourDbContext instantie ophalen met behulp van afhankelijkheidsinjectie. Als u bijvoorbeeld uw gegevensbronobject wilt ophalen uit een voorbeeldservice, definieert u het als een constructorparameter en zorgt u ervoor dat de klasse ExampleService is geregistreerd bij de container voor afhankelijkheidsinjectie:

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

Voor meer informatie over afhankelijkheidsinjectie, zie .NET afhankelijkheidsinjectie.

Een Npgsql-databasecontext verrijken

U kunt liever de standaard Entity Framework-methode gebruiken om een databasecontext te verkrijgen en deze toe te voegen aan de container voor afhankelijkheidsinjectie:

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

U hebt meer flexibiliteit wanneer u de databasecontext op deze manier maakt, bijvoorbeeld:

• U kunt bestaande configuratiecode opnieuw gebruiken voor de databasecontext zonder deze opnieuw te schrijven voor Aspire.
• U kunt Entity Framework Core interceptors gebruiken om databasebewerkingen te wijzigen.
• U kunt ervoor kiezen om Entity Framework Core contextpooling niet te gebruiken, wat in sommige omstandigheden beter kan presteren.

Als u deze methode gebruikt, kunt u de databasecontext verbeteren met herhaalde pogingen in de stijl van Aspire, statuscontroles, logboekregistratie en telemetriefuncties door de EnrichNpgsqlDbContext methode aan te roepen.

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

De parameter settings is een exemplaar van de klasse NpgsqlEntityFrameworkCorePostgreSQLSettings.

Configuratie

De AspirePostgreSQLEntity Framework Core-integratie biedt meerdere configuratiemethoden en opties om te voldoen aan de vereisten en conventies van uw project.

Een verbindingsreeks gebruiken

Wanneer u een verbindingsreeks uit de sectie ConnectionStrings configuratie gebruikt, geeft u de naam van de verbindingsreeks op bij het aanroepen van de AddNpgsqlDbContext methode:

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

De verbindingsreeks wordt opgehaald uit de ConnectionStrings configuratiesectie:

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

De EnrichNpgsqlDbContext maakt geen gebruik van de ConnectionStrings-configuratiesectie, omdat er van wordt uitgegaan dat een DbContext al geregistreerd is op het moment dat deze wordt aangeroepen.

Zie de ConnectionStringvoor meer informatie.

Configuratieproviders gebruiken

De AspirePostgreSQLEntity Framework Core-integratie ondersteunt Microsoft.Extensions.Configuration. Het laadt de NpgsqlEntityFrameworkCorePostgreSQLSettings uit configuratiebestanden zoals appsettings.json met behulp van de Aspire:Npgsql:EntityFrameworkCore:PostgreSQL sleutel. Als u uw configuraties in de sectie Aspire:Npgsql:EntityFrameworkCore:PostgreSQL hebt ingesteld, kunt u de methode gewoon aanroepen zonder een parameter door te geven.

In het volgende voorbeeld ziet u een appsettings.json-bestand waarmee een aantal van de beschikbare opties wordt geconfigureerd:

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

Zie voor het volledige client-integratieschema PostgreSQLEntity Framework CoreJSON, Aspire. Npgsql.EntityFrameworkCore.PostgreSQL/ConfigurationSchema.json.

Inline delegates gebruiken

U kunt de Action<NpgsqlEntityFrameworkCorePostgreSQLSettings> delegate ook doorgeven om bepaalde of alle opties direct in te stellen, bijvoorbeeld om de ConnectionString in te stellen:

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

Meerdere DbContext-klassen configureren

Als u meer dan één DbContext met een andere configuratie wilt registreren, kunt u $"Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:{typeof(TContext).Name}" configuratiesectienaam gebruiken. De json-configuratie ziet er als volgt uit:

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

Als u vervolgens de methode AddNpgsqlDbContext aanroept met AnotherDbContext typeparameter, worden de instellingen vanuit Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:AnotherDbContext sectie geladen.

builder.AddNpgsqlDbContext<AnotherDbContext>();

Gezondheidscontroles voor Client-integratie

Aspire hebben standaard statuscontroles ingeschakeld voor alle services. Op dezelfde manier maken veel Aspirehostingintegraties ook statuscontrole-eindpunten mogelijk. Zie voor meer informatie:

• .NET app-gezondheidscontroles in C#
• Gezondheidscontroles in ASP.NET Core

De AspirePostgreSQLEntity Framework Core-integraties verwerken standaard het volgende:

• Hiermee wordt de DbContextHealthChecktoegevoegd, waarmee de EF Core methode van CanConnectAsyncwordt aangeroepen. De naam van de gezondheidscontrole is de naam van het type TContext.
• Integreert met het /health HTTP-eindpunt, waarmee is gespecificeerd dat alle geregistreerde gezondheidscontroles moeten slagen voordat de app als gereed kan worden beschouwd voor het accepteren van verkeer.

Waarneembaarheid en telemetrie

Aspire Integraties stellen automatisch configuraties voor logboekregistratie, tracering en metrische gegevens in, die ook wel de pijlers van waarneembaarheid worden genoemd. Zie het overzicht van integratieobserveerbaarheid en telemetrie voor meer informatie over integratieobserveerbaarheid en telemetrieAspire. Afhankelijk van de back-upservice ondersteunen sommige integraties mogelijk slechts enkele van deze functies. Sommige integraties ondersteunen bijvoorbeeld logboekregistratie en tracering, maar geen metrische gegevens. Telemetriefuncties kunnen ook worden uitgeschakeld met behulp van de technieken die worden weergegeven in de sectie Configuratie.

Loggen

De AspirePostgreSQLEntity Framework Core-integratie maakt gebruik van de volgende logboekcategorieën:

• 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

Opsporen

De integratie van AspirePostgreSQLEntity Framework Core verzendt de volgende traceringsactiviteiten met behulp van OpenTelemetry:

• Npgsql

Statistieken

De integratie van AspirePostgreSQLEntity Framework Core verzendt de volgende metrische gegevens met behulp van 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

Zie ook

• PostgreSQL documenten
• Aspire Azure PostgreSQL Entity Framework Core integratie
• Aspire Integraties
• Aspire GitHub Repo