.NET Aspire PostgreSQL-integratie
omvat:hosting-integratie 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 AspirePostgreSQL-integratie biedt een manier om verbinding te maken met bestaande PostgreSQL-databases of nieuwe exemplaren te maken op basis van .NET met de docker.io/library/postgres
containerimage.
Hostingintegratie
De hostintegratiemodellen van PostgreSQL beschouwen de verschillende PostgreSQL resources als de volgende typen.
Als u toegang wilt krijgen tot deze typen en API's om ze uit te drukken als resources in uw app-host project, Installeer het 📦Aspire.Hosting.PostgreSQL NuGet-pakket:
dotnet add package Aspire.Hosting.PostgreSQL
Zie dotnet pakket toevoegen of Pakketafhankelijkheden beheren in .NET toepassingenvoor meer informatie.
PostgreSQL serverresource toevoegen
Roep in uw app-hostproject AddPostgres aan op het builder
-exemplaar om een PostgreSQL serverresource toe te voegen en roep vervolgens 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 PostgreSQL-serverexemplaar gemaakt op uw lokale computer. Een verwijzing naar uw PostgreSQL-server en uw PostgreSQL database-exemplaar (de postgresdb
variabele) worden gebruikt om een afhankelijkheid toe te voegen aan de ExampleProject
. 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.
Tip
Als u liever verbinding wilt maken met een bestaande PostgreSQL-server, roept u in plaats daarvan AddConnectionString aan. Voor meer informatie, raadpleeg Bestaande bronnen.
PostgreSQL pgAdmin-resource toevoegen
Wanneer u PostgreSQL-middelen toevoegt aan de builder
met de AddPostgres
-methode, 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...
De code voegt een container toe op basis van de 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 AddPostgres
-methode, kunt u opeenvolgende aanroepen naar WithPgWeb maken 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...
De code voegt een container toe op basis van de docker.io/sosedoff/pgweb
-image. Alle geregistreerde PostgresDatabaseResource-exemplaren worden gebruikt om een configuratiebestand per exemplaar te maken en elke configuratie is gebonden aan de pgweb containerbladwijzermap. Zie PgWeb-documenten voor meer informatie: Server verbindingsbladwijzers.
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")
.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...
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. Zie Dockervoor meer informatie over gegevensvolumes en details over waarom ze de voorkeur hebben boven bindingskoppelingen.
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...
Belangrijk
Data bind-mounts hebben een beperkte functionaliteit in vergelijking met volumes, die betere prestaties, draagbaarheid en beveiliging bieden, waardoor ze geschikter zijn voor productieomgevingen. Bindingskoppelingen bieden echter directe toegang tot en wijziging van bestanden op het hostsysteem, ideaal voor ontwikkeling en testen waar wijzigingen in realtime nodig zijn.
Gegevensbindmontages zijn afhankelijk van het bestandssysteem van de hostmachine om de PostgreSQL-servergegevens bij herstarten van de container te behouden. De data-bindmount wordt op de hostcomputer gekoppeld aan het pad C:\PostgreSQL\Data
in Windows (of /PostgreSQL/Data
op Unix) binnen de server container van de PostgreSQL. Zie Docker docs: Bindingskoppelingenvoor meer informatie over koppelingskoppelingen voor gegevens.
PostgreSQL serverbron toevoegen 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-bindingskoppeling is afhankelijk van het bestandssysteem van de hostcomputer om de PostgreSQL serverdatabase te initialiseren met de containers init map. Deze map wordt gebruikt voor initialisatie, het uitvoeren van uitvoerbare shellscripts of .sql opdrachtbestanden nadat de postgres-gegevens map is gemaakt. De init-bind mount wordt gekoppeld op C:\PostgreSQL\Init
op Windows (of /PostgreSQL/Init
op Unix) pad van de hostcomputer in de PostgreSQL servercontainer.
PostgreSQL serverresource toevoegen met parameters
Als u expliciet de gebruikersnaam en het wachtwoord wilt opgeven die de containerimage gebruikt, kunt u deze aanmeldgegevens opgeven als parameters. 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.
integratie van Client
Installeer de 📦Aspireom aan de slag te gaan met de .NET AspirePostgreSQL-clientintegratie. Npgsql NuGet-pakket in het clientintensieve project, dat wil gezegd het project voor de toepassing die gebruikmaakt van de PostgreSQL-client. De PostgreSQL-clientintegratie registreert een NpgsqlDataSource--exemplaar dat u kunt gebruiken om met PostgreSQLte communiceren.
dotnet add package Aspire.Npgsql
Npgsql-client toevoegen
Roep in het Program.cs bestand van het clientgebruikte project de AddNpgsqlDataSource-extensiemethode aan op elke IHostApplicationBuilder om een NpgsqlDataSource
te registreren voor gebruik via de container voor afhankelijkheidsinjectie. De methode gebruikt een verbindingsnaamparameter.
builder.AddNpgsqlDataSource(connectionName: "postgresdb");
Tip
De parameter connectionName
moet overeenkomen met de naam die wordt gebruikt bij het toevoegen van de PostgreSQL serverresource in het hostproject van de app. Zie PostgreSQL serverresource toevoegenvoor meer informatie.
Nadat u NpgsqlDataSource
aan de builder hebt toegevoegd, kunt u de NpgsqlDataSource
-instantie verkrijgen 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(NpgsqlDataSource dataSource)
{
// Use dataSource...
}
Voor meer informatie over afhankelijkheidsinjectie, zie .NET afhankelijkheidsinjectie.
Keyed Npgsql-client toevoegen
Er kunnen situaties zijn waarin u meerdere NpgsqlDataSource
exemplaren met verschillende verbindingsnamen wilt registreren. Als u keyed Npgsql-clients wilt registreren, roept u de methode AddKeyedNpgsqlDataSource aan:
builder.AddKeyedNpgsqlDataSource(name: "chat");
builder.AddKeyedNpgsqlDataSource(name: "queue");
Vervolgens kunt u met behulp van dependency injection de NpgsqlDataSource
exemplaren ophalen. Als u bijvoorbeeld de verbinding wilt ophalen uit een voorbeeldservice:
public class ExampleService(
[FromKeyedServices("chat")] NpgsqlDataSource chatDataSource,
[FromKeyedServices("queue")] NpgsqlDataSource queueDataSource)
{
// Use data sources...
}
Voor meer informatie over gesleutelde services, zie .NET afhankelijkheidsinjectie: Keyed Services.
Configuratie
De .NET AspirePostgreSQL-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, kunt u de naam van de verbindingsreeks opgeven bij het aanroepen van de AddNpgsqlDataSource methode:
builder.AddNpgsqlDataSource("postgresdb");
Vervolgens wordt de verbindingsreeks opgehaald uit de ConnectionStrings
configuratiesectie:
{
"ConnectionStrings": {
"postgresdb": "Host=myserver;Database=postgresdb"
}
}
Zie de ConnectionStringvoor meer informatie.
Configuratieproviders gebruiken
De .NET AspirePostgreSQL-integratie ondersteunt Microsoft.Extensions.Configuration. Het laadt de NpgsqlSettings uit appsettings.json of andere configuratiebestanden met behulp van de Aspire:Npgsql
-sleutel. Voorbeeld appsettings.json waarmee een aantal van de opties wordt geconfigureerd:
In het volgende voorbeeld ziet u een appsettings.json-bestand waarmee een aantal van de beschikbare opties wordt geconfigureerd:
{
"Aspire": {
"Npgsql": {
"ConnectionString": "Host=myserver;Database=postgresdb",
"DisableHealthChecks": false,
"DisableTracing": true,
"DisableMetrics": false
}
}
}
Zie Aspirevoor het volledige PostgreSQL clientintegratieschema JSON. Npgsql/ConfigurationSchema.json.
Gebruik inline-afgevaardigden
U kunt ook de Action<NpgsqlSettings> configureSettings
delegate doorgeven om sommige of alle opties rechtstreeks in te stellen, bijvoorbeeld om health checks uit te schakelen:
builder.AddNpgsqlDataSource(
"postgresdb",
static settings => settings.DisableHealthChecks = true);
Gezondheidscontroles
Standaard kunnen .NET.NET Aspire integraties statuscontroles voor alle services inschakelen. Zie .NET.NET Aspire overzicht van integratiesvoor meer informatie.
- Voegt de
NpgSqlHealthCheck
toe, waarmee wordt gecontroleerd of opdrachten kunnen worden uitgevoerd op basis van de onderliggende Postgres-database. - Integreert met het
/health
HTTP-eindpunt, waarbij alle geregistreerde statuscontroles moeten slagen zodat de app klaar wordt geacht om verkeer te accepteren.
Waarneembaarheid en telemetrie
.NET .NET Aspire integraties stellen automatisch logging-, tracing- en metricsconfiguraties in, 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.
Loggen
De .NET AspirePostgreSQL-integratie maakt gebruik van de volgende logboekcategorieën:
Npgsql.Connection
Npgsql.Command
Npgsql.Transaction
Npgsql.Copy
Npgsql.Replication
Npgsql.Exception
Tracering
De .NET AspirePostgreSQL-integratie verzendt de volgende traceringsactiviteiten met behulp van OpenTelemetry:
Npgsql
Statistieken
De integratie van .NET AspirePostgreSQL verzendt de volgende metrische gegevens met behulp van OpenTelemetry:
- 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