.NET Aspire Azure PostgreSQL Integration
umfasst: Hostingintegration und
Client Integration
Azure Datenbank für PostgreSQL– Flexible Server ist ein relationaler Datenbankdienst, der auf dem Open Source-Postgres-Datenbankmodul basiert. Es ist ein vollständig verwalteter Datenbank-as-a-Service, der unternehmenskritische Workloads mit vorhersehbarer Leistung, Sicherheit, hoher Verfügbarkeit und dynamischer Skalierbarkeit verarbeiten kann. Die .NET AspireAzurePostgreSQL-Integration bietet eine Möglichkeit, eine Verbindung mit vorhandenen AzurePostgreSQL-Datenbanken herzustellen oder neue Instanzen aus .NET mit dem docker.io/library/postgres
Containerimagezu erstellen.
Hosting-Integration
Das .NET AspireAzurePostgreSQL Hosting-Integrationsmodell bildet einen flexiblen PostgreSQL-Server und eine PostgreSQL-Datenbank als die Typen AzurePostgresFlexibleServerResource und AzurePostgresFlexibleServerDatabaseResource ab. Andere Typen, die in der Hostingintegration inhärent verfügbar sind, werden in den folgenden Ressourcen dargestellt:
Um auf diese Typen und APIs zuzugreifen, um sie als Ressourcen in Ihrem App-Host Projekt auszudrücken, installieren Sie die 📦Aspire. Hosting.Azure.PostgreSQL NuGet-Paket:
dotnet add package Aspire.Hosting.Azure.PostgreSQL
Weitere Informationen finden Sie unter dotnet add package.
Die AzurePostgreSQL-Hosting-Integration ist abhängig von dem 📦Aspire.Hosting.PostgreSQL-NuGet-Paket und erweitert es, um Azure zu unterstützen. Alles, was Sie mit der .NET AspirePostgreSQL Integration und .NET AspirePostgreSQLEntity Framework Core Integration tun können, können Sie auch mit dieser Integration tun.
Serverressource AzurePostgreSQL hinzufügen
Nachdem Sie die .NET AspireAzurePostgreSQL Hostingintegration installiert haben, rufen Sie die AddAzurePostgresFlexibleServer Erweiterungsmethode in Ihrem App-Hostprojekt auf:
var builder = DistributedApplication.CreateBuilder(args);
var postgres = builder.AddAzurePostgresFlexibleServer("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");
var exampleProject = builder.AddProject<Projects.ExampleProject>()
.WithReference(postgresdb);
Durch den vorherigen Aufruf von AddAzurePostgresFlexibleServer
wird die PostgresSQL-Serverressource so konfiguriert, dass sie als AzurePostgres Flexible Serverbereitgestellt wird.
Wichtig
Standardmäßig konfiguriert AddAzurePostgresFlexibleServer
die Authentifizierung über Microsoft Entra ID. Dies erfordert Änderungen an Anwendungen, die eine Verbindung mit diesen Ressourcen herstellen müssen. Weitere Informationen finden Sie unter Client Integration.
Tipp
Wenn Sie AddAzurePostgresFlexibleServeraufrufen, wird implizit AddAzureProvisioningaufgerufen, wodurch die Unterstützung zur dynamischen Generierung von Azure-Ressourcen während des App-Starts hinzugefügt wird. Die App muss das entsprechende Abonnement und den entsprechenden Standort konfigurieren. Weitere Informationen finden Sie unter Lokale Bereitstellung: Konfiguration.
Generierte Bereitstellungs-Bicep-Skripte
Wenn Sie neu bei Bicepsind, handelt es sich um eine domänenspezifische Sprache zur Definition von Azure-Ressourcen. Mit .NET.NET Aspiremüssen Sie Bicep nicht manuell schreiben, da die Bereitstellungs-APIs Bicep für Sie generieren. Wenn Sie Ihre App veröffentlichen, wird die generierte Bicep-Datei zusammen mit der Manifestdatei ausgegeben. Wenn Sie eine AzurePostgreSQL Ressource hinzufügen, wird das folgende Bicep generiert:
@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location
param principalId string
param principalType string
param principalName string
resource postgres_flexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = {
name: take('postgresflexible-${uniqueString(resourceGroup().id)}', 63)
location: location
properties: {
authConfig: {
activeDirectoryAuth: 'Enabled'
passwordAuth: 'Disabled'
}
availabilityZone: '1'
backup: {
backupRetentionDays: 7
geoRedundantBackup: 'Disabled'
}
highAvailability: {
mode: 'Disabled'
}
storage: {
storageSizeGB: 32
}
version: '16'
}
sku: {
name: 'Standard_B1ms'
tier: 'Burstable'
}
tags: {
'aspire-resource-name': 'postgres-flexible'
}
}
resource postgreSqlFirewallRule_AllowAllAzureIps 'Microsoft.DBforPostgreSQL/flexibleServers/firewallRules@2024-08-01' = {
name: 'AllowAllAzureIps'
properties: {
endIpAddress: '0.0.0.0'
startIpAddress: '0.0.0.0'
}
parent: postgres_flexible
}
resource postgres_flexible_admin 'Microsoft.DBforPostgreSQL/flexibleServers/administrators@2024-08-01' = {
name: principalId
properties: {
principalName: principalName
principalType: principalType
}
parent: postgres_flexible
dependsOn: [
postgres_flexible
postgreSqlFirewallRule_AllowAllAzureIps
]
}
output connectionString string = 'Host=${postgres_flexible.properties.fullyQualifiedDomainName};Username=${principalName}'
Das vorangehende Bicep ist ein Modul, das einen AzurePostgreSQL flexiblen Server mit den folgenden Standardwerten darstellt:
-
authConfig
: Die Authentifizierungskonfiguration des PostgreSQL Servers. Standardmäßig istActiveDirectoryAuth
aktiviert undPasswordAuth
deaktiviert. -
availabilityZone
: Die Verfügbarkeitszone des PostgreSQL-Servers. Der Standardwert ist1
. -
backup
: Die Sicherungskonfiguration des PostgreSQL Servers. Der Standardwert istBackupRetentionDays
auf7
undGeoRedundantBackup
aufDisabled
festgelegt. -
highAvailability
: Die Konfiguration für hohe Verfügbarkeit des PostgreSQL Servers. Der Standardwert istDisabled
. -
storage
: Die Speicherkonfiguration des PostgreSQL-Servers. Der Standardwert ist aufStorageSizeGB
festgelegt, beginnend bei32
. -
version
: Die Version des PostgreSQL Servers. Der Standardwert ist16
. -
sku
: Die SKU des PostgreSQL-Servers. Der Standardwert istStandard_B1ms
. -
tags
: Die Tags des PostgreSQL-Servers. Der Standardwert istaspire-resource-name
und wird auf den Namen der Ressource Aspire festgelegt, in diesem Fallpostgres-flexible
.
Zusätzlich zum PostgreSQL flexiblen Server stellt sie auch eine Azure Firewallregel bereit, um alle Azure IP-Adressen zuzulassen. Schließlich wird ein Administrator für den PostgreSQL-Server erstellt, und die Verbindungszeichenfolge wird als Ausgabevariable ausgegeben. Das generierte Bicep ist ein Ausgangspunkt und kann an Ihre spezifischen Anforderungen angepasst werden.
Bereitstellungsinfrastruktur anpassen
Alle .NET AspireAzure Ressourcen sind Unterklassen des AzureProvisioningResource Typs. Dieser Typ ermöglicht die Anpassung der generierten Bicep durch Bereitstellen einer Fluent-API zum Konfigurieren der Azure-Ressourcen mithilfe der ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>)-API. Sie können z. B. die kind
, consistencyPolicy
, locations
und vieles mehr konfigurieren. Im folgenden Beispiel wird veranschaulicht, wie die PostgreSQL Serverressource angepasst wird:
builder.AddAzureCosmosDB("cosmos-db")
.ConfigureInfrastructure(infra =>
{
var flexibleServer = infra.GetProvisionableResources()
.OfType<PostgreSqlFlexibleServer>()
.Single();
flexibleServer.Sku = new PostgreSqlFlexibleServerSku
{
Tier = PostgreSqlFlexibleServerSkuTier.Burstable,
};
flexibleServer.HighAvailability = new PostgreSqlFlexibleServerHighAvailability
{
Mode = PostgreSqlFlexibleServerHighAvailabilityMode.ZoneRedundant,
StandbyAvailabilityZone = "2",
};
flexibleServer.Tags.Add("ExampleKey", "Example value");
});
Der vorherige Code:
- Verkettet einen Aufruf an die ConfigureInfrastructure-API.
- Der
infra
-Parameter ist eine Instanz des typs AzureResourceInfrastructure. - Die bereitstellbaren Ressourcen werden mittels der Methode GetProvisionableResources() abgerufen.
- Das einzelne PostgreSqlFlexibleServer wird abgerufen.
- Die
sku
wird mit PostgreSqlFlexibleServerSkuTier.Burstablefestgelegt. - Die Eigenschaften für hohe Verfügbarkeit werden mit PostgreSqlFlexibleServerHighAvailabilityMode.ZoneRedundant in der Standby-Verfügbarkeitszone
"2"
festgelegt. - Dem flexiblen Server wird ein Tag mit einem Schlüssel von
ExampleKey
und einem Wert vonExample value
hinzugefügt.
- Der
Es stehen viele weitere Konfigurationsoptionen zur Verfügung, um die PostgreSQL flexible Serverressource anzupassen. Weitere Informationen finden Sie unter Azure.Provisioning.PostgreSql und Azure. Bereitstellungsanpassung.
Herstellen einer Verbindung mit einem vorhandenen AzurePostgreSQL flexiblen Server
Möglicherweise verfügen Sie über einen vorhandenen AzurePostgreSQL flexiblen Server, mit dem Sie eine Verbindung herstellen möchten. Anstatt eine neue AzurePostgreSQL flexible Serverressource darzustellen, können Sie dem App-Host eine Verbindungszeichenfolge hinzufügen. Rufen Sie die Azure-Methode auf, um einer vorhandenen PostgreSQLAddConnectionString flexiblen Server eine Verbindung hinzuzufügen:
var builder = DistributedApplication.CreateBuilder(args);
var postgres = builder.AddConnectionString("postgres");
builder.AddProject<Projects.WebApplication>("web")
.WithReference(postgres);
// After adding all resources, run the app...
Anmerkung
Verbindungszeichenfolgen werden verwendet, um eine Vielzahl von Verbindungsinformationen darzustellen, einschließlich Datenbankverbindungen, Nachrichtenbroker, Endpunkt-URIs und andere Dienste. In der .NET.NET Aspire Nomenklatur wird der Begriff "Verbindungsstring" verwendet, um jede Art von Verbindungsinformationen darzustellen.
Die Verbindungszeichenfolge wird in der Konfiguration des App-Hosts konfiguriert, in der Regel unter Benutzergeheimnisse, unter dem Abschnitt ConnectionStrings
. Der App-Host fügt diese Verbindungszeichenfolge als Umgebungsvariable in alle abhängigen Ressourcen ein, z. B.:
{
"ConnectionStrings": {
"postgres": "Server=<PostgreSQL-server-name>.postgres.database.azure.com;Database=<database-name>;Port=5432;Ssl Mode=Require;User Id=<username>;"
}
}
Die abhängige Ressource kann auf die eingefügte Verbindungszeichenfolge zugreifen, indem sie die GetConnectionString Methode aufruft und den Verbindungsnamen als Parameter übergibt, in diesem Fall "postgres"
. Die GetConnectionString
-API ist eine Abkürzung für IConfiguration.GetSection("ConnectionStrings")[name]
.
Ausführen AzurePostgreSQL Ressource als Container
Die AzurePostgreSQL Hostingintegration unterstützt die Ausführung des PostgreSQL Servers als lokaler Container. Dies ist vorteilhaft für Situationen, in denen Sie den PostgreSQL Server lokal für Entwicklungs- und Testzwecke ausführen möchten, ohne dass eine Azure Ressource bereitgestellt werden muss oder eine Verbindung mit einem vorhandenen AzurePostgreSQL Server hergestellt werden muss.
Rufen Sie zum Ausführen des PostgreSQL Servers als Container die RunAsContainer-Methode auf:
var builder = DistributedApplication.CreateBuilder(args);
var postgres = builder.AddAzurePostgresFlexibleServer("postgres")
.RunAsContainer();
var postgresdb = postgres.AddDatabase("postgresdb");
var exampleProject = builder.AddProject<Projects.ExampleProject>()
.WithReference(postgresdb);
Der vorangehende Code konfiguriert eine AzurePostgreSQL Flexible Server-Ressource für die lokale Ausführung in einem Container.
Tipp
Die RunAsContainer
-Methode ist nützlich für die lokale Entwicklung und Tests. Die API macht einen optionalen Delegaten verfügbar, mit dem Sie die zugrunde liegende PostgresServerResource Konfiguration anpassen können. Sie können z. B. "pgAdmin" und "pgWeb" hinzufügen, ein Datenvolume oder einen Daten-Bind-Mount hinzufügen und einen Init-Bind-Mount hinzufügen. Weitere Informationen finden Sie im Abschnitt .NET AspirePostgreSQL Hosting-Integration.
Konfigurieren des AzurePostgreSQL Servers für die Verwendung der Kennwortauthentifizierung
Standardmäßig ist der AzurePostgreSQL Server so konfiguriert, dass Microsoft Entra ID Authentifizierung verwendet wird. Wenn Sie die Kennwortauthentifizierung verwenden möchten, können Sie den Server so konfigurieren, dass die Kennwortauthentifizierung verwendet wird, indem Sie die WithPasswordAuthentication-Methode aufrufen:
var builder = DistributedApplication.CreateBuilder(args);
var username = builder.AddParameter("username", secret: true);
var password = builder.AddParameter("password", secret: true);
var postgres = builder.AddAzurePostgresFlexibleServer("postgres")
.WithPasswordAuthentication(username, password);
var postgresdb = postgres.AddDatabase("postgresdb");
var exampleProject = builder.AddProject<Projects.ExampleProject>()
.WithReference(postgresdb);
Der vorangehende Code konfiguriert den AzurePostgreSQL Server für die Verwendung der Kennwortauthentifizierung. Die Parameter username
und password
werden dem App-Host als Parameter hinzugefügt, und die WithPasswordAuthentication
Methode wird aufgerufen, um den AzurePostgreSQL Server für die Verwendung der Kennwortauthentifizierung zu konfigurieren. Weitere Informationen finden Sie unter Externe Parameter.
Client Integration
Um mit der .NET AspirePostgreSQL-Clientintegration zu beginnen, installieren Sie das 📦Aspire.Npgsql NuGet-Paket im clientnutzenden Projekt, das heißt, dem Projekt für die Anwendung, die den PostgreSQL-Client verwendet. Die PostgreSQL Clientintegration registriert eine NpgsqlDataSource Instanz, die Sie für die Interaktion mit PostgreSQLverwenden können.
dotnet add package Aspire.Npgsql
Hinzufügen des Npgsql-Clients
Rufen Sie in der Program.cs-Datei Ihres clientnutzenden Projekts die AddNpgsqlDataSource-Erweiterungsmethode für jedes IHostApplicationBuilder auf, um eine NpgsqlDataSource
für die Verwendung über den Abhängigkeitsinjektionscontainer zu registrieren. Die Methode verwendet einen Verbindungsnamenparameter.
builder.AddNpgsqlDataSource(connectionName: "postgresdb");
Tipp
Der parameter connectionName
muss mit dem Namen übereinstimmen, der beim Hinzufügen der PostgreSQL Serverressource im App-Hostprojekt verwendet wird. Weitere Informationen finden Sie unter Serverressource hinzufügen PostgreSQL.
Nachdem Sie NpgsqlDataSource
zum Generator hinzugefügt haben, können Sie die NpgsqlDataSource
Instanz mithilfe der Abhängigkeitseinfügung abrufen. Wenn Sie beispielsweise das Datenquellenobjekt aus einem Beispieldienst abrufen möchten, definieren Sie es als Konstruktorparameter, und stellen Sie sicher, dass die ExampleService
Klasse im Container zum Einfügen von Abhängigkeiten registriert ist:
public class ExampleService(NpgsqlDataSource dataSource)
{
// Use dataSource...
}
Weitere Informationen zur Abhängigkeitsinjektion finden Sie unter .NET Abhängigkeitsinjektion.
Hinzufügen des Npgsql-Clients mit Schlüsseln
Es kann Situationen geben, in denen Sie mehrere NpgsqlDataSource
Instanzen mit unterschiedlichen Verbindungsnamen registrieren möchten. Rufen Sie die AddKeyedNpgsqlDataSource-Methode auf, um schlüsselierte Npgsql-Clients zu registrieren:
builder.AddKeyedNpgsqlDataSource(name: "chat");
builder.AddKeyedNpgsqlDataSource(name: "queue");
Anschließend können Sie die NpgsqlDataSource
-Instanzen über Abhängigkeitsinjektion abrufen. So rufen Sie beispielsweise die Verbindung aus einem Beispieldienst ab:
public class ExampleService(
[FromKeyedServices("chat")] NpgsqlDataSource chatDataSource,
[FromKeyedServices("queue")] NpgsqlDataSource queueDataSource)
{
// Use data sources...
}
Weitere Informationen zu schlüsselbasierten Diensten finden Sie unter .NET Abhängigkeitsinjektion: Dienste mit Schlüsseln.
Konfiguration
Die .NET AspirePostgreSQL-Integration bietet mehrere Konfigurationsmethoden und -optionen, um die Anforderungen und Konventionen Ihres Projekts zu erfüllen.
Verwenden Sie eine Verbindungszeichenfolge
Wenn Sie eine Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings
verwenden, können Sie beim Aufrufen der AddNpgsqlDataSource-Methode den Namen der Verbindungszeichenfolge angeben:
builder.AddNpgsqlDataSource("postgresdb");
Anschließend wird die Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings
abgerufen:
{
"ConnectionStrings": {
"postgresdb": "Host=myserver;Database=postgresdb"
}
}
Weitere Informationen finden Sie in der ConnectionString.
Verwenden von Konfigurationsanbietern
Die .NET AspirePostgreSQL-Integration unterstützt Microsoft.Extensions.Configuration. Sie lädt die NpgsqlSettings aus appsettings.json oder anderen Konfigurationsdateien mithilfe des Aspire:Npgsql
Schlüssels. Beispiel appsettings.json, das einige der Optionen konfiguriert:
Das folgende Beispiel zeigt eine appsettings.json Datei, die einige der verfügbaren Optionen konfiguriert:
{
"Aspire": {
"Npgsql": {
"ConnectionString": "Host=myserver;Database=postgresdb",
"DisableHealthChecks": false,
"DisableTracing": true,
"DisableMetrics": false
}
}
}
Für das vollständige PostgreSQL Client-Integrationsschema JSON finden Sie Aspire.Npgsql/ConfigurationSchema.json.
Verwenden Sie Inline-Delegaten
Sie können auch den Action<NpgsqlSettings> configureSettings
Delegat übergeben, um einige oder alle Optionen direkt einzurichten, zum Beispiel um Gesundheitschecks zu deaktivieren.
builder.AddNpgsqlDataSource(
"postgresdb",
static settings => settings.DisableHealthChecks = true);
Client Integrationsgesundheitsprüfungen
Standardmäßig sind bei .NET.NET AspireClient-IntegrationenGesundheitsprüfungen für alle Dienste aktiviert. Ebenso ermöglichen viele .NET.NET AspireHostingintegrationen auch Gesundheitsprüfungsendpunkte. Weitere Informationen finden Sie unter:
- Fügt die
NpgSqlHealthCheck
hinzu, die überprüft, ob Befehle erfolgreich für die zugrunde liegende Postgres Datenbank ausgeführt werden können. - Integriert in den
/health
HTTP-Endpunkt, der angibt, dass alle registrierten Gesundheitsprüfungen erfolgreich sein müssen, damit die App bereit ist, Datenverkehr zu akzeptieren.
Beobachtbarkeit und Telemetrie
.NET .NET Aspire Integrationen richten automatisch Protokollierungs-, Ablaufverfolgungs- und Metrikkonfigurationen ein, die manchmal als die Säulen der Beobachtbarkeitbezeichnet werden. Weitere Informationen zur Beobachtbarkeit und Telemetrie der Integrationen finden Sie in der Integrationsübersicht.NET.NET Aspire. Abhängig vom Sicherungsdienst unterstützen einige Integrationen möglicherweise nur einige dieser Features. Beispielsweise unterstützen einige Integrationen Protokollierung und Ablaufverfolgung, aber keine Metriken. Telemetriefeatures können auch mithilfe der techniken deaktiviert werden, die im Abschnitt Configuration dargestellt werden.
Protokollierung
Die .NET AspirePostgreSQL-Integration verwendet die folgenden Protokollkategorien:
Npgsql.Connection
Npgsql.Command
Npgsql.Transaction
Npgsql.Copy
Npgsql.Replication
Npgsql.Exception
Nachverfolgung
Die .NET AspirePostgreSQL-Integration wird die folgenden Verfolgungsaktivitäten mithilfe von OpenTelemetryausgeben:
Npgsql
Metriken
Die .NET AspirePostgreSQL Integration gibt die folgenden Metriken mithilfe von OpenTelemetryaus:
- 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
Hinzufügen eines Azure authentifizierten Clients von Npgsql
Wenn Sie AddAzurePostgresFlexibleServer
in Ihrer PostgreSQL Hostingintegration aufrufen, wird standardmäßig das 📦AzureIdentity--NuGet-Paket konfiguriert, um die Authentifizierung zu aktivieren:
dotnet add package Azure.Identity
Die PostgreSQL-Verbindung kann mithilfe der Clientintegration und Azure.Identitygenutzt werden:
builder.AddNpgsqlDataSource(
"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));
});
Im vorherigen Codeausschnitt wird veranschaulicht, wie Sie die DefaultAzureCredential-Klasse aus dem Azure.Identity-Paket verwenden, um sich mit Microsoft Entra ID zu authentifizieren und ein Token abzurufen, um eine Verbindung mit der PostgreSQL-Datenbank herzustellen. Die UsePeriodicPasswordProvider--Methode wird verwendet, um das Token für den Verbindungszeichenfolgen-Generator bereitzustellen.