intégration .NET AspirePostgreSQL

2025-04-10

Inclut : intégration d’hébergement —&— Client

PostgreSQL est un système de base de données relationnelle open source puissant avec de nombreuses années de développement actif qui lui a valu une solide réputation de fiabilité, de robustesse des fonctionnalités et de performances. l'intégration .NET AspirePostgreSQL permet de se connecter à des bases de données PostgreSQL existantes ou de créer de nouvelles instances à partir de .NET avec l'image du conteneur docker.io/library/postgres.

Intégration de l’hébergement

Les modèles d'intégration de PostgreSQL modélisent différentes ressources de PostgreSQL sous les types suivants.

Pour accéder à ces types et API pour les exprimer en tant que ressources dans votre projet hôte d’application , installez le 📦Aspire. Hébergement.PostgreSQL Package NuGet :

.NET CLI
RéférenceDePaquet

dotnet add package Aspire.Hosting.PostgreSQL

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

Pour plus d’informations, consultez dotnet add package ou Gérer les dépendances des packages dans les applications .NET.

Ajouter une ressource de serveur PostgreSQL

Dans votre projet hôte d’application, appelez AddPostgres sur l’instance de builder pour ajouter une ressource de serveur PostgreSQL, puis appelez AddDatabase sur l’instance postgres pour ajouter une ressource de base de données, comme illustré dans l’exemple suivant :

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

Lorsque .NET.NET Aspire ajoute une image conteneur à l’hôte de l’application, comme illustré dans l’exemple précédent avec l’image docker.io/library/postgres, il crée une instance de serveur PostgreSQL sur votre ordinateur local. Une référence à votre PostgreSQL instance de serveur et de base de données (la postgresdb variable) est utilisée pour ajouter une dépendance à l’instance ExampleProject.

Lors de l’ajout d’une ressource de base de données au modèle d’application, la base de données est créée s’il n’existe pas déjà. La création de la base de données s’appuie sur les API d’événementing de l’application, en particulier ResourceReadyEvent. En d’autres termes, lorsque la postgres ressource est prête, l’événement est déclenché et la ressource de base de données est créée.

La ressource de serveur PostgreSQL inclut des informations d’identification par défaut avec une username de "postgres" et des password générées de manière aléatoire à l’aide de la méthode CreateDefaultPasswordParameter.

La méthode WithReference configure une connexion dans le ExampleProject nommé "messaging". Pour plus d’informations, consultez cycle de vie des ressources de conteneur.

Pourboire

Si vous préférez vous connecter à un serveur PostgreSQL existant, appelez AddConnectionString à la place. Pour plus d’informations, consultez Référencer les ressources existantes.

Ajouter une PostgreSQL ressource avec des scripts de base de données

Par défaut, lorsque vous ajoutez un PostgresDatabaseResource, il s’appuie sur le script suivant pour créer la base de données :

CREATE DATABASE "<QUOTED_DATABASE_NAME>"

Pour modifier le script par défaut, chaînez un appel à la WithCreationScript méthode sur le générateur de ressources de base de données :

var builder = DistributedApplication.CreateBuilder(args);

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

var databaseName = "app_db";
var creationScript = $$"""
    -- Create the database
    CREATE DATABASE {{databaseName}};

    """;

var db = postgres.AddDatabase(databaseName)
                 .WithCreationScript(creationScript);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

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

L’exemple précédent crée une base de données nommée app_db. Le script est exécuté lors de la création de la ressource de base de données. Le script est passé sous forme de chaîne à la WithCreationScript méthode, qui est ensuite exécutée dans le contexte de la PostgreSQL ressource.

Remarque

La connexion à une commande de base de données (\c) n’est pas prise en charge lors de l’utilisation du script de création.

Ajouter la ressource PostgreSQL de pgAdmin

Lorsque vous ajoutez des ressources à PostgreSQL avec la méthode builder, vous pouvez enchaîner des appels à AddPostgres pour ajouter le conteneur WithPgAdmin. Ce conteneur est un client multiplateforme pour les bases de données PostgreSQL, qui sert un tableau de bord d’administration web. Prenons l’exemple suivant :

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

Le code précédent ajoute un conteneur basé sur l’image docker.io/dpage/pgadmin4. Le conteneur est utilisé pour gérer les ressources du serveur et de la base de données PostgreSQL. La méthode WithPgAdmin ajoute un conteneur qui sert un tableau de bord d’administration web pour les bases de données PostgreSQL.

Configurer le port de l’hôte pgAdmin

Pour configurer le port hôte du conteneur pgAdmin, appelez la méthode WithHostPort sur la ressource de serveur PostgreSQL. L’exemple suivant montre comment configurer le port hôte pour le conteneur pgAdmin :

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

Le code précédent ajoute et configure le port hôte pour le conteneur pgAdmin. Le port hôte est autrement attribué de manière aléatoire.

Ajouter la ressource pgWeb PostgreSQL

Lorsque vous ajoutez des ressources à \PostgreSQL avec la méthode \builder, vous pouvez chaîner des appels à \AddPostgres pour ajouter le conteneur \\WithPgWeb\. Ce conteneur est un client multiplateforme pour les bases de données PostgreSQL, qui sert un tableau de bord d’administration web. Prenons l’exemple suivant :

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

Le code précédent ajoute un conteneur basé sur l’image docker.io/sosedoff/pgweb. Toutes les instances de PostgresDatabaseResource enregistrées sont utilisées pour créer un fichier de configuration par instance, et chaque fichier de configuration est associé au répertoire de favoris du conteneur pgweb . Pour plus d’informations, consultez la documentation PgWeb : Server signets de connexion.

Configurer le port hôte pgWeb

Pour configurer le port hôte du conteneur pgWeb, appelez la méthode WithHostPort sur la ressource de serveur PostgreSQL. L’exemple suivant montre comment configurer le port hôte pour le conteneur pgAdmin :

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgWeb(pgWeb => pgWeb.WithHostPort(5050));

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

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

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

Le code précédent ajoute et configure le port hôte pour le conteneur pgWeb. Le port hôte est autrement attribué de manière aléatoire.

Ajouter PostgreSQL ressource de serveur avec un volume de données

Pour ajouter un volume de données à la ressource du serveur PostgreSQL, appelez la méthode WithDataVolume sur la ressource de serveur PostgreSQL :

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

Le volume de données est utilisé pour conserver les données du serveur PostgreSQL en dehors du cycle de vie de son conteneur. Le volume de données est monté sur le chemin d’accès /var/lib/postgresql/data dans le conteneur du serveur PostgreSQL et lorsqu’un paramètre name n’est pas fourni, le nom est généré au hasard. Pour plus d’informations sur les volumes de données et sur la raison pour laquelle ils sont préférés par rapport aux montages de liaison, consultez Docker la documentation : Volumes.

Important

Certaines des intégrations de base de données, y compris l’intégration .NET AspirePostgreSQL, ne peuvent pas réussir à utiliser les volumes de données après le déploiement vers Azure Container Apps (ACA). Cela est dû au fait que L’ACA utilise Server Le bloc de messages (SMB) pour connecter des conteneurs à des volumes de données, et certains systèmes ne peuvent pas utiliser cette connexion. Dans le Aspire tableau de bord, une base de données affectée par ce problème a un état d’activation ou d’échec de l’activation , mais elle n’est jamais répertoriée comme en cours d’exécution.

Vous pouvez résoudre le problème en utilisant le service managé Azure Database for PostgreSQL pour héberger la base de données déployée au lieu d’un conteneur dans ACA, ce qui est l’approche recommandée, indépendamment de ce problème. Le code hôte d’application suivant montre comment déployer une base de données sur Azure Base de données pour PostgreSQL, mais l’exécuter en tant que conteneur, avec un volume de données, pendant le développement :

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddAzurePostgresFlexibleServer("postgres")
                      .RunAsContainer(container => 
                      {
                        container.WithDataVolume();
                      });

builder.Build().Run();

Ajoutez la ressource serveur PostgreSQL avec un montage de liaison de données.

Pour ajouter un montage de liaison de données à la ressource de serveur PostgreSQL, appelez la méthode WithDataBindMount :

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

Important

Les montages de liaison de données ont des fonctionnalités limitées par rapport aux volumes , qui offrent de meilleures performances, portabilité et sécurité, ce qui les rend plus adaptés aux environnements de production. Toutefois, les montages de liaison autorisent l’accès direct et la modification des fichiers sur le système hôte, ce qui est idéal pour le développement et le test dont les modifications en temps réel sont nécessaires.

Les montages de liaison de données s’appuient sur le système de fichiers de l’ordinateur hôte pour conserver les données du serveur PostgreSQL entre les redémarrages de conteneur. Le point de montage de liaison de données est monté au chemin d'accès C:\PostgreSQL\Data sur Windows (ou /PostgreSQL/Data sur Unix) sur la machine hôte, dans le conteneur du serveur PostgreSQL. Pour plus d’informations sur les montages de liaison des données, consultez Docker docs : Montages de liaison.

Ajouter la ressource serveur PostgreSQL avec le montage par liaison initial

Pour ajouter un "bind mount" d'init à la ressource du serveur PostgreSQL, appelez la méthode WithInitBindMount :

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

Le montage de liaison init s'appuie sur le système de fichiers de la machine hôte pour initialiser la base de données du serveur PostgreSQL avec le dossier "init" des conteneurs . Ce dossier est utilisé pour l'initialisation et l'exécution de scripts de shell exécutables ou de fichiers de commande .sql après la création du dossier postgres-data. Le montage de liaison init est monté sur le chemin d'accès C:\PostgreSQL\Init sous Windows (ou /PostgreSQL/Init sur Unix) sur la machine hôte dans le conteneur serveur PostgreSQL.

Ajouter PostgreSQL ressource de serveur avec des paramètres

Lorsque vous souhaitez fournir explicitement le nom d’utilisateur et le mot de passe utilisés par l’image conteneur, vous pouvez fournir ces informations d’identification en tant que paramètres. Prenons l’exemple de remplacement suivant :

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

Pour plus d’informations sur la fourniture de paramètres, consultez Paramètres externes.

Vérifications d’intégrité de l’intégration d’hébergement

L’intégration d’hébergement PostgreSQL ajoute automatiquement un contrôle d’intégrité pour la ressource de serveur PostgreSQL. La vérification d’intégrité vérifie que le serveur PostgreSQL est en cours d’exécution et qu’une connexion peut être établie à celle-ci.

L’intégration de l’hébergement s’appuie sur le package NuGet AspNetCore.HealthChecks.Npgsql.

intégration Client

Pour commencer avec l’intégration du .NET AspirePostgreSQL client, installez le package NuGet Npgsql 📦Aspire dans le projet consommateur, c’est-à-dire le projet de l’application qui utilise le PostgreSQL client. L’intégration PostgreSQL du client inscrit une instance NpgsqlDataSource que vous pouvez utiliser pour interagir avec PostgreSQL.

.NET CLI
RéférenceDePaquet

dotnet add package Aspire.Npgsql

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

Ajouter un client Npgsql

Dans le fichier Program.cs de votre projet client-consommateur, appelez la méthode d’extension AddNpgsqlDataSource sur un(e) IHostApplicationBuilder pour enregistrer un(e) NpgsqlDataSource à utiliser via le conteneur d’injection de dépendances. La méthode prend un paramètre de nom de connexion.

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Pourboire

Le paramètre connectionName doit correspondre au nom utilisé lors de l’ajout de la ressource de serveur PostgreSQL dans le projet hôte de l’application. Pour plus d’informations, consultez Ajouter PostgreSQL une ressource de serveur.

Après avoir ajouté NpgsqlDataSource au générateur, vous pouvez obtenir l’instance NpgsqlDataSource à l’aide de l’injection de dépendances. Par exemple, pour récupérer votre objet source de données à partir d’un exemple de service, définissez-le en tant que paramètre de constructeur et vérifiez que la classe ExampleService est inscrite auprès du conteneur d’injection de dépendances :

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

Pour plus d’informations sur l’injection de dépendances, consultez .NET l’injection de dépendances.

Ajouter un client Npgsql avec clé

Il peut arriver que vous souhaitiez inscrire plusieurs instances de NpgsqlDataSource avec différents noms de connexion. Pour enregistrer des clients Npgsql identifiés par clé, appelez la méthode AddKeyedNpgsqlDataSource :

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

Vous pouvez ensuite récupérer les instances NpgsqlDataSource à l’aide de l’injection de dépendances. Par exemple, pour récupérer la connexion à partir d’un exemple de service :

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

Pour plus d’informations sur les services à clé, consultez .NET l’injection de dépendances : services à clé.

Paramétrage

L’intégration .NET AspirePostgreSQL fournit plusieurs approches et options de configuration pour répondre aux exigences et conventions de votre projet.

Utiliser une chaîne de connexion

Lorsque vous utilisez une chaîne de connexion à partir de la section de configuration ConnectionStrings, vous pouvez fournir le nom de la chaîne de connexion lors de l’appel de la méthode AddNpgsqlDataSource :

builder.AddNpgsqlDataSource("postgresdb");

Ensuite, la chaîne de connexion est récupérée à partir de la section de configuration ConnectionStrings :

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

Pour plus d’informations, consultez ConnectionString.

Utiliser des fournisseurs de configuration

L’intégration .NET AspirePostgreSQL prend en charge Microsoft.Extensions.Configuration. Il charge le NpgsqlSettings à partir de appsettings.json ou d’autres fichiers de configuration à l’aide de la clé Aspire:Npgsql. Exemple appsettings.json qui configure certaines des options suivantes :

L’exemple suivant montre un fichier appsettings.json qui configure certaines des options disponibles :

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

Pour connaître le schéma complet PostgreSQL d’intégration JSON du client, consultez Aspire. Npgsql/ConfigurationSchema.json.

Utiliser des délégués en ligne

Vous pouvez également transmettre le délégué Action<NpgsqlSettings> configureSettings pour configurer certaines ou toutes les options en ligne, par exemple pour désactiver les vérifications de santé :

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

Client contrôles de santé de l’intégration

Par défaut, les intégrations de clients .NET.NET Aspire ont les contrôles de santé activés pour tous les services. De même, de nombreuses intégrations d'hébergement .NET.NET Aspire activent également les endpoints de vérification de santé. Pour plus d’informations, consultez :

.NET contrôles d’intégrité d’application en C#
vérifications de santé dans ASP.NET Core

Ajoute le NpgSqlHealthCheck, qui vérifie que les commandes peuvent être exécutées avec succès sur la base de données Postgres sous-jacente.
S’intègre au point de terminaison HTTP /health, qui spécifie que tous les contrôles d'intégrité enregistrés doivent passer pour que l'application soit considérée comme prête à recevoir du trafic.

Observabilité et télémétrie

.NET .NET Aspire les intégrations configurent automatiquement les configurations de journalisation, de suivi et de métriques, parfois appelées piliers de l’observabilité. Pour plus d’informations sur l’observabilité et la télémétrie d’intégration, consultez .NET.NET Aspire la vue d’ensemble des intégrations. Selon le service de stockage, certaines intégrations peuvent uniquement prendre en charge certaines de ces fonctionnalités. Par exemple, certaines intégrations prennent en charge la journalisation et le suivi, mais pas les métriques. Les fonctionnalités de télémétrie peuvent également être désactivées à l’aide des techniques présentées dans la section Configuration .

Exploitation forestière

L’intégration .NET AspirePostgreSQL utilise les catégories de logs suivantes :

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

Traçage

L’intégration .NET AspirePostgreSQL émet les activités de suivi suivantes à l’aide de OpenTelemetry:

Npgsql

Métriques

L’intégration .NET AspirePostgreSQL émet les métriques suivantes à l’aide de 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