integratie van .NET AspirePostgreSQLEntity Framework Core

omvat:hostingintegratie en 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 .NET 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

Een PostgreSQLserver wordt gemodelleerd als het PostgresServerResource type door de PostgreSQL die integratie host. Voor toegang tot dit type en API's waarmee u het kunt toevoegen aan uw 📦Aspire. Hosting.PostgreSQL NuGet-pakket in het app-hostproject.

.NET CLI

dotnet add package Aspire.Hosting.PostgreSQL

PackageReference

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

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

PostgreSQL server-resource toevoegen

Roep in uw app-hostproject AddPostgres aan op het builder exemplaar om een PostgreSQLserver resource toe te voegen en roep AddDatabase aan op het postgres exemplaar 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 .NET.NET Aspire een containerinstallatiekopie toevoegt aan de app-host, zoals wordt weergegeven in het vorige voorbeeld met de docker.io/library/postgres-installatiekopie, wordt er een nieuw PostgreSQLserver exemplaar op uw lokale computer gemaakt. Een verwijzing naar uw PostgreSQLserver en uw PostgreSQL database-exemplaar (de postgresdb variabele) worden gebruikt om een afhankelijkheid toe te voegen aan de ExampleProject. De resource PostgreSQLserver bevat standaardreferenties 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.

Tip

Als u liever verbinding wilt maken met een bestaande PostgreSQLserver, roept u in plaats daarvan AddConnectionString aan. Raadpleeg bestaande bronnenvoor meer informatie.

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 platformoverschrijdend client voor PostgreSQL databases, dat een web-gebaseerd beheerdashboard bedient. 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 PostgreSQLserver- en databasebronnen. Met de methode WithPgAdmin wordt een container toegevoegd die een webbeheerdashboard voor PostgreSQL databases bedient.

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 platformoverschrijdend client voor PostgreSQL databases, dat een webgebaseerd beheerdashboard biedt. 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 voorgaande code wordt een container toegevoegd op basis van de 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 PgWeb-documenten voor meer informatie: Server verbindingsbladwijzers.

PostgreSQL server bron toevoegen met gegevensvolume

Als u een gegevensvolume wilt toevoegen aan de PostgreSQLserver-resource, roept u de WithDataVolume methode aan voor de PostgreSQLserver-resource:

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 PostgreSQLserver gegevens buiten de levenscyclus van de container te behouden. Het gegevensvolume wordt gekoppeld aan het /var/lib/postgresql/data pad in de PostgreSQLserver container 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.

PostgreSQL server-resource toevoegen met een data-bindkoppeling

Als u een koppeling voor gegevensbinding wilt toevoegen aan de PostgreSQLserver-resource, 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...

Belangrijk

Gegevens koppelen beperkte functionaliteit hebben in vergelijking met volumes, die betere prestaties, draagbaarheid en beveiliging bieden, waardoor ze geschikter zijn voor productieomgevingen. Bind mounts bieden echter directe toegang tot en wijziging van bestanden op het hostsysteem, ideaal voor ontwikkeling en testen waar wijzigingen in real-time nodig zijn.

Databindingskoppelingen zijn afhankelijk van het bestandssysteem van de hostcomputer om de PostgreSQLserver gegevens te behouden bij herstart van de container. De koppeling voor gegevensbinding wordt gekoppeld aan de C:\PostgreSQL\Data in Windows (of /PostgreSQL/Data op Unix) pad op de hostcomputer in de PostgreSQLserver container. Zie Docker docs: Bindingskoppelingenvoor meer informatie over koppelingskoppelingen voor gegevens.

PostgreSQL server resource toevoegen met init bind mount

Als u een init-bindingskoppeling wilt toevoegen aan de PostgreSQLserver-resource, 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-bindingskoppeling is afhankelijk van het bestandssysteem van de hostcomputer om de PostgreSQLserver database te initialiseren met de containers init map. Deze map wordt gebruikt voor initialisatie, het uitvoeren van uitvoerbare shellscripts of .sql opdrachtbestanden nadat de postgres-data map is gemaakt. De init-bindingskoppeling wordt gekoppeld aan de C:\PostgreSQL\Init in Windows (of /PostgreSQL/Init op Unix) op de hostcomputer in de PostgreSQLserver-container.

PostgreSQL server resource 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 PostgreSQLserver resource. De gezondheidscontrole controleert of PostgreSQLserver functioneert en of er een verbinding tot stand kan worden gebracht.

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

integratie van Client

Installeer de 📦Aspireom aan de slag te gaan met de .NET AspirePostgreSQLEntity Framework Coreclient-integratie. Npgsql.EntityFrameworkCore.PostgreSQL NuGet-pakket in het client-verbruikende project, dat wil gezegd het project voor de toepassing die gebruikmaakt van de PostgreSQLclient. De .NET AspirePostgreSQLEntity Framework Coreclient-integratie registreert de gewenste DbContext subklasse-exemplaren die u kunt gebruiken om met PostgreSQLte communiceren.

.NET CLI

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

PackageReference

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

Npgsql-databasecontext toevoegen

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

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

Tip

De parameter connectionName moet overeenkomen met de naam die wordt gebruikt bij het toevoegen van de PostgreSQLserver resource in het app-hostproject. Zie PostgreSQLserver resource toevoegenvoor meer informatie.

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.

Npgsql-databasecontext toevoegen met verrijking

Als u de DbContext wilt verrijken met aanvullende services, zoals automatische herhalingen, gezondheidscontroles, logboekregistratie en telemetrie, roept u de methode EnrichNpgsqlDbContext aan.

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

De parameter settings is een exemplaar van de klasse NpgsqlEntityFrameworkCorePostgreSQLSettings.

Configuratie

De .NET 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 een DbContext wordt verwacht die op het moment dat deze wordt aangeroepen, geregistreerd moet zijn.

Zie de ConnectionStringvoor meer informatie.

Configuratieproviders gebruiken

De .NET 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",
          "DbContextPooling": true,
          "DisableHealthChecks": true,
          "DisableTracing": true
        }
      }
    }
  }
}

Zie Aspirevoor het volledige PostgreSQLEntity Framework Coreclient-integratieschema JSON. Npgsql.EntityFrameworkCore.PostgreSQL/ConfigurationSchema.json.

Inline gedelegeerden gebruiken

U kunt de Action<NpgsqlEntityFrameworkCorePostgreSQLSettings> gedelegeerde ook doorgeven om bepaalde of alle opties inline in te stellen, bijvoorbeeld om de ConnectionStringin 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 configuratie van de json ziet er als volgt uit:

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

Standaard kunnen .NET.NET Aspire integraties statuscontroles voor alle services inschakelen. Zie .NET.NET Aspire overzicht van integratiesvoor meer informatie.

De .NET AspirePostgreSQLEntity Framework Core-integraties verwerken standaard het volgende:

• Hiermee wordt de DbContextHealthChecktoegevoegd, waarmee de CanConnectAsync methode van EF Corewordt 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

.NET .NET Aspire integraties configureren automatisch logregistratie-, tracering- en metriekinstellingen, die ook wel bekend staan als de pijlers van waarneembaarheid. Zie .NET.NET Aspire overzicht van integratieintegratiesvoor meer informatie over de waarneembaarheid en telemetrie van integraties. 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.

Logboekregistratie

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

Opsporen

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

• Npgsql

Statistieken

De integratie van .NET 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

Azure PostgreSQL hostingintegratie

Als u uw PostgreSQL resources wilt implementeren in Azure, installeert u het 📦Aspire. Hosting.Azure.PostgreSQL NuGet-pakket:

.NET CLI

dotnet add package Aspire.Hosting.Azure.PostgreSQL

PackageReference

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

Azure PostgreSQL server resource toevoegen

Nadat u de .NET AspireAzurePostgreSQL hostingintegratie hebt geïnstalleerd, roept u de AddAzurePostgresFlexibleServer-extensiemethode aan in uw app-hostproject:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Met de voorgaande aanroep voor AddAzurePostgresFlexibleServer configureert u de PostgreSQL server-resource om te worden geïmplementeerd als een flexibele AzurePostgresServer.

Belangrijk

Standaard configureert AddAzurePostgresFlexibleServerMicrosoft Entra ID authenticatie. Hiervoor moeten wijzigingen worden aangebracht in toepassingen die verbinding moeten maken met deze resources. Zie Client integratievoor meer informatie.

Azure geverifieerde Npgsql toevoegen client

Wanneer u standaard AddAzurePostgresFlexibleServer aanroept in uw PostgreSQL hostingintegratie, configureert het de 📦AzureIdentity NuGet-pakket om authenticatie in te schakelen.

.NET CLI

dotnet add package Azure.Identity

PackageReference

<PackageReference Include="Azure.Identity"
                  Version="*" />

De PostgreSQL-verbinding kan worden gebruikt met behulp van de client-integratie en 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));
});

Het voorgaande codefragment laat zien hoe u de DefaultAzureCredential-klasse uit het Azure.Identity-pakket gebruikt om te verifiëren met Microsoft Entra ID en een token ophaalt om verbinding te maken met de PostgreSQL-database. De methode UsePeriodicPasswordProvider wordt gebruikt om het token aan de opbouwfunctie voor verbindingsreeksen op te geven.

Zie ook

• documentatie voor Azure Database for PostgreSQL
• .NET .NET Aspire integraties
• .NET Aspire GitHub repo