intégration de .NET AspirePostgreSQL

Article
12/14/2024

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

Le PostgreSQL hébergeant des modèles d’intégration un PostgreSQLserver comme type de PostgresServerResource. Pour accéder à ce type et aux API qui vous permettent de l’ajouter à votre package NuGet d’hébergement 📦AspirePostgreSQL dans le projet hôte de l’application .

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

Dans votre projet hôte d’application, appelez AddPostgres sur l’instance de builder pour ajouter une ressource PostgreSQLserver, 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 PostgreSQLserver sur votre ordinateur local. Une référence à votre PostgreSQLserver et à votre instance de base de données PostgreSQL (la variable postgresdb) est utilisée pour ajouter une dépendance au ExampleProject. La ressource PostgreSQLserver 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 à une PostgreSQLserverexistante, 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 PostgreSQLserver et de base de données. La méthode WithPgAdmin ajoute un conteneur qui sert un tableau de bord d’administration web pour les bases de données PostgreSQL.

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.

Ajouter la ressource PostgreSQLserver avec volume de données

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

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 PostgreSQLserver en dehors du cycle de vie de son conteneur. Le volume de données est monté au chemin /var/lib/postgresql/data dans le conteneur PostgreSQLserver et lorsqu’un paramètre name n’est pas fourni, un nom est généré aléatoirement. 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.

Ajouter PostgreSQLserver ressource avec montage de liaison de données

Pour ajouter un montage de liaison de données à la ressource PostgreSQLserver, 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 PostgreSQLserver entre les redémarrages de conteneur. Le montage de liaison de données est monté sur le chemin C:\PostgreSQL\Data sous Windows (ou /PostgreSQL/Data sur Unix) de l’ordinateur hôte dans le conteneur PostgreSQLserver. Pour plus d’informations sur les montages de liaison des données, consultez Docker docs : Montages de liaison.

Ajouter la ressource PostgreSQLserver avec montage par liaison init

Pour ajouter un montage de liaison init à la ressource PostgreSQLserver, 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 PostgreSQLserver avec le dossier d'init des conteneurs . Ce dossier est utilisé pour l’initialisation et l’exécution de scripts d’interpréteur de commandes 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 C:\PostgreSQL\Init sous Windows (ou /PostgreSQL/Init sur Unix) sur l'ordinateur hôte dans le conteneur PostgreSQLserver.

Ajouter PostgreSQLserver ressource 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 PostgreSQLserver. La vérification d’intégrité vérifie que le PostgreSQLserver est en cours d’exécution et qu’une connexion peut être établie à celui-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 .NET AspirePostgreSQLclient, installez la 📦Aspire. Npgsql package NuGet dans le projet clientconsommant, c’est-à-dire le projet pour l’application qui utilise le PostgreSQLclient. L’intégration PostgreSQLclient 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 Npgsql client

Dans le fichier Program.cs de votre projet consommant client, appelez la méthode d’extension AddNpgsqlDataSource sur tous les IHostApplicationBuilder pour enregistrer un 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 PostgreSQLserver dans le projet hôte de l’application. Pour plus d’informations, consultez Ajouter PostgreSQLserverressource .

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 Npgsql avec clé client

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 PostgreSQLclient d’intégration JSON, 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

intégration d’hébergement AzurePostgreSQL

Pour déployer vos ressources PostgreSQL sur Azure, installez le 📦Aspire. Hébergement.Azure.PostgreSQL package NuGet :

.NET CLI
packageReference

dotnet add package Aspire.Hosting.Azure.PostgreSQL

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

Ajouter AzurePostgreSQLserver ressource

Une fois que vous avez installé l’intégration d’hébergement .NET AspireAzurePostgreSQL, appelez la méthode d’extension AddAzurePostgresFlexibleServer dans votre projet hôte d’application :

var builder = DistributedApplication.CreateBuilder(args);

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

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

L'appel précédent à AddAzurePostgresFlexibleServer configure la ressource PostgreSQL server pour être déployée en tant que solution flexible AzurePostgresServer.

Important

Par défaut, AddAzurePostgresFlexibleServer configure l’authentification Microsoft Entra ID. Cela nécessite des modifications apportées aux applications qui doivent se connecter à ces ressources. Pour plus d’informations, consultez l'intégration de Client.

Ajouter Azure Npgsql authentifié client

Par défaut, lorsque vous appelez AddAzurePostgresFlexibleServer dans votre intégration d’hébergement PostgreSQL, il configure 📦Azure. Identity package NuGet pour activer l’authentification :

.NET CLI
packageReference

dotnet add package Azure.Identity

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

La connexion PostgreSQL peut être consommée à l’aide de l’intégration client et 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));
});

L’extrait de code précédent montre comment utiliser la classe DefaultAzureCredential à partir du package Azure.Identity pour s’authentifier auprès de Microsoft Entra ID et récupérer un jeton pour se connecter à la base de données PostgreSQL. La méthode UsePeriodicPasswordProvider est utilisée pour fournir le jeton au générateur de chaînes de connexion.

Partager via

intégration de .NET AspirePostgreSQL

Intégration de l’hébergement

Ajouter une ressource PostgreSQLserver

Ajouter la ressource PostgreSQL de pgAdmin

Ajouter la ressource pgWeb PostgreSQL

Ajouter la ressource PostgreSQLserver avec volume de données

Ajouter PostgreSQLserver ressource avec montage de liaison de données

Ajouter la ressource PostgreSQLserver avec montage par liaison init

Ajouter PostgreSQLserver ressource avec des paramètres

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

intégration de Client

Ajouter Npgsql client

Ajouter Npgsql avec clé client

Configuration

Utiliser une chaîne de connexion

Utiliser des fournisseurs de configuration

Utiliser des délégués en ligne

Vérifications d’intégrité

Observabilité et télémétrie

Exploitation forestière

Traçage

Métriques

intégration d’hébergement AzurePostgreSQL

Ajouter AzurePostgreSQLserver ressource

Ajouter Azure Npgsql authentifié client

Voir aussi

Ressources supplémentaires