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

• PostgresServerResource
• PostgresDatabaseResource
• PgAdminContainerResource
• PgWebContainerResource

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

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

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.

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 ist ActiveDirectoryAuth aktiviert und PasswordAuth deaktiviert.
• availabilityZone: Die Verfügbarkeitszone des PostgreSQL-Servers. Der Standardwert ist 1.
• backup: Die Sicherungskonfiguration des PostgreSQL Servers. Der Standardwert ist BackupRetentionDays auf 7 und GeoRedundantBackup auf Disabledfestgelegt.
• highAvailability: Die Konfiguration für hohe Verfügbarkeit des PostgreSQL Servers. Der Standardwert ist Disabled.
• storage: Die Speicherkonfiguration des PostgreSQL-Servers. Der Standardwert ist auf StorageSizeGBfestgelegt, beginnend bei 32.
• version: Die Version des PostgreSQL Servers. Der Standardwert ist 16.
• sku: Die SKU des PostgreSQL-Servers. Der Standardwert ist Standard_B1ms.
• tags: Die Tags des PostgreSQL-Servers. Der Standardwert ist aspire-resource-name und wird auf den Namen der Ressource Aspire festgelegt, in diesem Fall postgres-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, locationsund 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 von Example value hinzugefügt.

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

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.

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

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

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");

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:

• .NET App-Gesundheitschecks in C#
• Gesundheitschecks in ASP.NET Core

• Fügt die NpgSqlHealthCheckhinzu, 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

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

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.

Siehe auch

• PostgreSQL Dokumente
• Azure Datenbank für PostgreSQL
• .NET Aspire Azure PostgreSQL Entity Framework Core Integration
• .NET Aspire PostgreSQL Integration
• .NET .NET Aspire Integrationen
• .NET Aspire GitHub Repo