intégration de .NET AspirePostgreSQL

Article
01/31/2025

inclut :intégration de l'hébergement et intégration 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 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 package NuGet 📦Aspire.Hosting.PostgreSQL :

.NET CLI
packageReference

dotnet add package Aspire.Hosting.PostgreSQL

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

Pour plus d’informations, consultez dotnet add package ou Gestion des dépendances de 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 serveur PostgreSQL et à votre instance de base de données PostgreSQL (la variable postgresdb) est utilisée pour ajouter une dépendance au ExampleProject. 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 le cycle de vie des ressources du 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 la ressource PostgreSQL de pgAdmin

Lorsque vous ajoutez des ressources PostgreSQL au builder avec la méthode AddPostgres, vous pouvez chaîner des appels à WithPgAdmin pour ajouter le conteneur dpage/pgadmin4. 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 au builder avec la méthode AddPostgres, vous pouvez chaîner des appels à WithPgWeb pour ajouter le conteneur sosedoff/pgweb. 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 inscrites sont utilisées pour créer un fichier de configuration par instance, et chaque configuration est liée au répertoire pgweb de signet de conteneur . Pour plus d’informations, consultez la documentation PgWeb : Server marque-pages 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")
                      .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...

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

Ajoutez la ressource serveur PostgreSQL avec un montage de liaison de fichiers.

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, idéal pour le développement et le test où 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 du serveur PostgreSQL avec le montage d'association initial

Pour ajouter un montage de liaison 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, l’exécution de scripts d’interpréteur de commandes exécutables ou fichiers de commandes .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 de Client

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

.NET CLI
packageReference

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 ressource 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 injection de dépendances.

Ajouter un client Npgsql à 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 avec clé, voir la section .NET injection de dépendances : services avec clé.

Configuration

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 la 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 obtenir le schéma complet de l’intégration du client PostgreSQLJSON, 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);

Vérifications d’intégrité

Par défaut, les intégrations .NET.NET Aspire activent des vérifications de santé pour tous les services. Pour plus d’informations, consultez .NET.NET Aspire vue d’ensemble des intégrations.

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 jugée prête à recevoir du trafic.

Observabilité et télémétrie

Les intégrations .NET.NET Aspire configurent automatiquement la journalisation, le suivi et les métriques, parfois appelées les piliers de l’observabilité. Pour plus d’informations sur l’observabilité de l’intégration et la télémétrie, consultez .NET.NET Aspire 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 journaux 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

Partager via