integrazione di .NET AspireAzurePostgreSQL

Include:,,, l'integrazione dell'hosting e ,,Client, l'integrazione

Azure Database per PostgreSQL: l'Server flessibile è un servizio di database relazionale basato sul motore di database Postgres open source. Si tratta di un database come servizio completamente gestito che può gestire carichi di lavoro cruciali con prestazioni prevedibili, sicurezza, disponibilità elevata e scalabilità dinamica. L'integrazione .NET AspireAzurePostgreSQL consente di connettersi ai database di AzurePostgreSQL esistenti o di creare nuove istanze da .NET con l'immagine del contenitore docker.io/library/postgres.

Integrazione dell'hosting

La .NET AspireAzurePostgreSQL integrazione di hosting modella un server e un database PostgreSQL flessibili come tipi di AzurePostgresFlexibleServerResource e AzurePostgresFlexibleServerDatabaseResource. Gli altri tipi intrinsecamente disponibili nell'integrazione dell'hosting sono rappresentati nelle risorse seguenti:

• PostgresServerResource
• PostgresDatabaseResource
• PgAdminContainerResource
• PgWebContainerResource

Per accedere a questi tipi e API per esprimerli come risorse nel progetto host dell'app , installare il pacchetto NuGet 📦Aspire.Hosting.Azure.PostgreSQL.

.NET

dotnet add package Aspire.Hosting.Azure.PostgreSQL

Per altre informazioni, vedere dotnet add package.

PackageReference

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

Per altre informazioni, vedere Gestire le dipendenze dei pacchetti nelle applicazioni .NET.

L'integrazione dell'hosting AzurePostgreSQL prende una dipendenza dal pacchetto NuGet 📦Aspire.Hosting.PostgreSQL, estendendolo per supportare Azure. Tutte le operazioni che è possibile eseguire con l'integrazione .NET AspirePostgreSQL e con l'integrazione .NET AspirePostgreSQLEntity Framework Core sono possibili anche con questa integrazione.

Aggiungere AzurePostgreSQL risorsa del server

Dopo aver installato l'integrazione dell'hosting .NET AspireAzurePostgreSQL, chiamare il metodo di estensione AddAzurePostgresFlexibleServer nel progetto host dell'app:

var builder = DistributedApplication.CreateBuilder(args);

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

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

La chiamata precedente a AddAzurePostgresFlexibleServer configura la risorsa server PostgresSQL da distribuire come AzurePostgres flessibile Server.

Importante

Per impostazione predefinita, AddAzurePostgresFlexibleServer configura l'autenticazione Microsoft Entra ID. Ciò richiede modifiche alle applicazioni che devono connettersi a queste risorse. Per altre informazioni, vedere integrazione Client.

Suggerimento

Quando si chiama AddAzurePostgresFlexibleServer, chiama in modo implicito AddAzureProvisioning, che aggiunge il supporto per la generazione di risorse Azure in modo dinamico durante l'avvio dell'app. L'app deve configurare la sottoscrizione e il percorso appropriati. Per ulteriori informazioni, vedere Distribuzione locale: Configurazione.

Bicep di provisioning generato

Se non si ha familiarità con Bicep, si tratta di un linguaggio specifico del dominio per la definizione delle risorse Azure. Con .NET.NET Aspirenon è necessario scrivere Bicep a mano, ma le API di provisioning generano Bicep automaticamente. Quando si pubblica l'app, il Bicep generato viene prodotto insieme al file manifesto. Quando si aggiunge una risorsa AzurePostgreSQL, viene generato il bicep seguente:

Alterna AzurePostgreSQL Bicep.

@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}'

Il bicep precedente è un modulo che effettua il provisioning di un server flessibile AzurePostgreSQL con le impostazioni predefinite seguenti:

• authConfig: configurazione di autenticazione del server di PostgreSQL. Il valore predefinito è ActiveDirectoryAuth abilitato e PasswordAuth disabilitato.
• availabilityZone: zona di disponibilità del server PostgreSQL. Il valore predefinito è 1.
• backup: configurazione di backup del server di PostgreSQL. Il valore predefinito è BackupRetentionDays impostato su 7 e GeoRedundantBackup impostato su Disabled.
• highAvailability: configurazione a disponibilità elevata del server PostgreSQL. Il valore predefinito è Disabled.
• storage: configurazione di archiviazione del server PostgreSQL. Il valore predefinito è StorageSizeGB impostato su 32.
• version: versione del server di PostgreSQL. Il valore predefinito è 16.
• sku: SKU del server di PostgreSQL. Il valore predefinito è Standard_B1ms.
• tags: tag del server di PostgreSQL. Il valore predefinito è aspire-resource-name impostato sul nome della risorsa Aspire, in questo caso postgres-flexible.

Oltre al server flessibile PostgreSQL, viene eseguito anche il provisioning di una regola firewall Azure per consentire l'accesso a tutti gli indirizzi IP Azure. Viene infine creato un amministratore per il server PostgreSQL e la stringa di connessione viene restituita come variabile di output. Il Bicep generato è un punto di partenza e può essere personalizzato per soddisfare i requisiti specifici.

Personalizzare l'infrastruttura di provisioning

Tutte le risorse .NET AspireAzure sono sottoclassi del tipo di AzureProvisioningResource. Questo tipo consente la personalizzazione del Bicep generato fornendo un'API fluente per configurare le risorse Azure, utilizzando l'API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Ad esempio, è possibile configurare il kind, consistencyPolicy, locationse altro ancora. L'esempio seguente illustra come personalizzare la risorsa AzureAzure Cosmos DB:

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

Il codice precedente:

• Concatena una chiamata all'API ConfigureInfrastructure:
  • Il parametro infra è un'istanza del tipo AzureResourceInfrastructure.
  • Le risorse provisionabili vengono recuperate chiamando il metodo GetProvisionableResources().
  • Viene recuperato il singolo PostgreSqlFlexibleServer.
  • Il sku è configurato con PostgreSqlFlexibleServerSkuTier.Burstable.
  • Le proprietà a disponibilità elevata vengono impostate con PostgreSqlFlexibleServerHighAvailabilityMode.ZoneRedundant nella zona di disponibilità standby "2".
  • Un tag viene aggiunto al server flessibile con una chiave di ExampleKey e un valore di Example value.

Sono disponibili molte altre opzioni di configurazione per personalizzare la risorsa server flessibile PostgreSQL. Per altre informazioni, vedere Azure.Provisioning.PostgreSql. Per ulteriori informazioni, vedere Azure. Personalizzazione della configurazione.

Connettersi a un server flessibile AzurePostgreSQL esistente

Potrebbe essere disponibile un server flessibile AzurePostgreSQL esistente a cui connettersi. Anziché rappresentare una nuova risorsa server flessibile AzurePostgreSQL, è possibile aggiungere una stringa di connessione all'host dell'app. Per aggiungere una connessione a un server flessibile AzurePostgreSQL esistente, chiamare il metodo AddConnectionString:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddConnectionString("postgres");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(postgres);

// After adding all resources, run the app...

Nota

Le stringhe di connessione vengono usate per rappresentare un'ampia gamma di informazioni di connessione, tra cui connessioni di database, broker messaggi, URI endpoint e altri servizi. Nella .NET.NET Aspire denominazione, il termine "stringa di connessione" viene usato per rappresentare qualsiasi tipo di informazioni di connessione.

La stringa di connessione viene configurata nella configurazione dell'host dell'app, in genere in segreti utente, nella sezione ConnectionStrings. L'host dell'app inserisce questa stringa di connessione come variabile di ambiente in tutte le risorse dipendenti, ad esempio:

{
    "ConnectionStrings": {
        "postgres": "Server=<PostgreSQL-server-name>.postgres.database.azure.com;Database=<database-name>;Port=5432;Ssl Mode=Require;User Id=<username>;"
    }
}

La risorsa dipendente può accedere alla stringa di connessione inserita chiamando il metodo GetConnectionString e passando il nome della connessione come parametro, in questo caso "postgres". L'API GetConnectionString è abbreviata per IConfiguration.GetSection("ConnectionStrings")[name].

Eseguire la risorsa AzurePostgreSQL come contenitore

L'integrazione dell'hosting AzurePostgreSQL supporta l'esecuzione del server PostgreSQL come contenitore locale. Ciò è utile per le situazioni in cui si vuole eseguire il server PostgreSQL localmente a scopo di sviluppo e test, evitando la necessità di effettuare il provisioning di una risorsa Azure o connettersi a un server AzurePostgreSQL esistente.

Per eseguire il server PostgreSQL come contenitore, chiamare il metodo RunAsContainer:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddAzurePostgresFlexibleServer("postgres")
                      .RunAsContainer();

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

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

Il codice precedente configura una risorsa Server flessibile AzurePostgreSQL per l'esecuzione in locale in un contenitore.

Consiglio

Il metodo RunAsContainer è utile per lo sviluppo e il test locali. L'API espone un delegato facoltativo che consente di personalizzare la configurazione PostgresServerResource sottostante, ad esempio l'aggiunta di pgAdmin, pgWeb, l'aggiunta di un volume di dati o il montaggio dell'associazione dati e l'aggiunta di un montaggio di binding init. Per ulteriori informazioni, consultare la sezione sull'integrazione dell'hosting .NET AspirePostgreSQL.

Configurare il server AzurePostgreSQL per l'uso dell'autenticazione password

Per impostazione predefinita, il server AzurePostgreSQL è configurato per l'uso dell'autenticazione Microsoft Entra ID. Se si vuole usare l'autenticazione password, è possibile configurare il server per l'uso dell'autenticazione della password chiamando il metodo WithPasswordAuthentication:

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

Il codice precedente configura il server AzurePostgreSQL per l'uso dell'autenticazione password. I parametri username e password vengono aggiunti all'host dell'app come parametri e viene chiamato il metodo WithPasswordAuthentication per configurare il server AzurePostgreSQL per l'uso dell'autenticazione della password. Per altre informazioni, vedere Parametri esterni.

integrazione Client

Per iniziare con l'integrazione client .NET AspirePostgreSQL, installare il pacchetto NuGet 📦Aspire.Npgsql nel progetto che consuma il client, ovvero il progetto per l'applicazione che utilizza il client PostgreSQL. L'integrazione client PostgreSQL registra un'istanza di NpgsqlDataSource che è possibile usare per interagire con PostgreSQL.

.NET

dotnet add package Aspire.Npgsql

PackageReference

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

Aggiungere il client Npgsql

Nel file Program.cs del progetto che utilizza il client chiamare il metodo di estensione AddNpgsqlDataSource in qualsiasi IHostApplicationBuilder per registrare un NpgsqlDataSource da usare tramite il contenitore di inserimento delle dipendenze. Il metodo accetta un parametro del nome di connessione.

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Suggerimento

Il parametro connectionName deve corrispondere al nome usato quando si aggiunge la risorsa server PostgreSQL nel progetto host dell'app. Per altre informazioni, vedere Aggiungere PostgreSQL risorsa server.

Dopo aver aggiunto NpgsqlDataSource al generatore, è possibile ottenere l'istanza di NpgsqlDataSource usando l'iniezione delle dipendenze. Ad esempio, per recuperare l'oggetto origine dati da un servizio di esempio, definirlo come parametro del costruttore e assicurarsi che la classe ExampleService sia registrata con il contenitore di inserimento delle dipendenze:

public class ExampleService(NpgsqlDataSource dataSource)
{
    // Use dataSource...
}

Per ulteriori informazioni su dependency injection, vedere .NET inserimento delle dipendenze.

Aggiungere il client Npgsql con chiave

In alcuni casi potrebbe essere necessario registrare più istanze di NpgsqlDataSource con nomi di connessione diversi. Per registrare i client Npgsql con chiave, chiamare il metodo AddKeyedNpgsqlDataSource:

builder.AddKeyedNpgsqlDataSource(name: "chat");
builder.AddKeyedNpgsqlDataSource(name: "queue");

È quindi possibile recuperare le istanze di NpgsqlDataSource usando l'iniezione di dipendenze. Ad esempio, per recuperare la connessione da un servizio di esempio:

public class ExampleService(
    [FromKeyedServices("chat")] NpgsqlDataSource chatDataSource,
    [FromKeyedServices("queue")] NpgsqlDataSource queueDataSource)
{
    // Use data sources...
}

Per ulteriori informazioni sui servizi con chiave, consultare la sezione .NET Inserimento delle Dipendenze: Servizi con Chiave.

Configurazione

L'integrazione .NET AspirePostgreSQL offre più approcci di configurazione e opzioni per soddisfare i requisiti e le convenzioni del progetto.

Usare una stringa di connessione

Quando si usa una stringa di connessione dalla sezione di configurazione ConnectionStrings, è possibile specificare il nome della stringa di connessione quando si chiama il metodo AddNpgsqlDataSource:

builder.AddNpgsqlDataSource("postgresdb");

La stringa di connessione verrà quindi recuperata dalla sezione di configurazione ConnectionStrings:

{
  "ConnectionStrings": {
    "postgresdb": "Host=myserver;Database=postgresdb"
  }
}

Per altre informazioni, vedere ConnectionString.

Usare i provider di configurazione

L'integrazione .NET AspirePostgreSQL supporta Microsoft.Extensions.Configuration. Carica il NpgsqlSettings da appsettings.json o da altri file di configurazione usando la chiave di Aspire:Npgsql. Esempio appsettings.json che configura alcune delle opzioni:

L'esempio seguente mostra un file appsettings.json che configura alcune delle opzioni disponibili:

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

Per lo schema completo PostgreSQL di integrazione client JSON, vedere Aspire. Npgsql/ConfigurationSchema.json.

Usare delegati in linea

È anche possibile passare il delegato Action<NpgsqlSettings> configureSettings per configurare alcune o tutte le opzioni direttamente, ad esempio per disabilitare i controlli di integrità.

builder.AddNpgsqlDataSource(
    "postgresdb",
     static settings => settings.DisableHealthChecks = true);

Controlli di integrità

Per impostazione predefinita, le integrazioni di .NET.NET Aspire abilitano verifiche di integrità per tutti i servizi. Per altre informazioni, vedere panoramica delle integrazioni .NET.NET Aspire.

• Aggiunge il NpgSqlHealthCheck, che verifica che i comandi possano essere eseguiti correttamente sul database Postgres sottostante.
• Si integra con l'endpoint HTTP /health, che specifica che tutti i controlli di integrità registrati devono essere passati affinché l'app sia considerata pronta ad accettare il traffico

Osservabilità e telemetria

.NET .NET Aspire le integrazioni configurano automaticamente le impostazioni di registrazione dei log, tracciamento e metriche, talvolta note come i pilastri dell'osservabilità. Per altre informazioni sull'osservabilità e la telemetria dell'integrazione, vedere panoramica delle integrazioni .NET.NET Aspire. A seconda del servizio di backup, alcune integrazioni possono supportare solo alcune di queste funzionalità. Ad esempio, alcune integrazioni supportano la registrazione e la traccia, ma non le metriche. Le funzionalità di telemetria possono essere disabilitate anche usando le tecniche presentate nella sezione Configurazione.

Registrazione

L'integrazione .NET AspirePostgreSQL usa le categorie di log seguenti:

• Npgsql.Connection
• Npgsql.Command
• Npgsql.Transaction
• Npgsql.Copy
• Npgsql.Replication
• Npgsql.Exception

Tracciatura

L'integrazione .NET AspirePostgreSQL genererà le attività di traccia seguenti usando OpenTelemetry:

• Npgsql

Metriche

L'integrazione .NET AspirePostgreSQL genererà le metriche seguenti usando 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

Aggiungere Azure client Npgsql autenticato

Per impostazione predefinita, quando si chiama AddAzurePostgresFlexibleServer nell'integrazione dell'hosting PostgreSQL, viene configurato il pacchetto NuGet .Identity di📦Azureper abilitare l'autenticazione.

.NET

dotnet add package Azure.Identity

PackageReference

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

La connessione PostgreSQL può essere utilizzata usando l'integrazione client e Azure.Identity:

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

Il frammento di codice precedente illustra come usare la classe DefaultAzureCredential del pacchetto di Azure.Identity per eseguire l'autenticazione con ID Microsoft Entra e recuperare un token per connettersi al database PostgreSQL. Il metodo UsePeriodicPasswordProvider viene usato per fornire il token al generatore di stringhe di connessione.

Vedere anche

• PostgreSQL documenti
• database Azure per PostgreSQL
• integrazione di .NET AspirePostgreSQL
• .NET .NET Aspire integrazioni
• .NET Aspire GitHub repo