intégration de .NET AspirePostgreSQLEntity Framework Core

Article
01/31/2025

inclut :intégration d’hébergement et intégrationClient

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 AspirePostgreSQLEntity Framework Core 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 modèle d'intégration PostgreSQL héberge diverses ressources 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 Gérer les dépendances de paquets 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 cycle de vie des ressources 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 pgAdmin PostgreSQL

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 PostgreSQL pgWeb

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 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 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")
                      .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 aux montages de liaison , consultez la documentation Docker : 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, une meilleure portabilité et sécurité, les rendant ainsi plus adaptés aux environnements de production. Toutefois, les montages de liaison autorisent un accès direct et une modification des fichiers sur le système hôte, ce qui est idéal pour le développement et le test lorsque des modifications en temps réel s'imposent.

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 de données, consultez Docker docs : Liaison de montages.

Ajouter la ressource serveur PostgreSQL avec montage de bind init

Pour ajouter un init bind mount à 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é à l'emplacement C:\PostgreSQL\Init sous Windows (ou chemin d'accès /PostgreSQL/Init sur Unix) sur la machine hôte dans le conteneur du 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 AspirePostgreSQLEntity Framework Core, installez le 📦Aspire. Npgsql.EntityFrameworkCore.PostgreSQL package NuGet dans le projet consommant le client, c’est-à-dire le projet pour l’application qui utilise le client PostgreSQL. L’intégration du client .NET AspirePostgreSQLEntity Framework Core inscrit vos instances de sous-classe DbContext souhaitées que vous pouvez utiliser pour interagir avec PostgreSQL.

.NET CLI
packageReference

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

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

Ajouter un contexte de base de données Npgsql

Dans le fichier Program.cs de votre projet consommant le client, appelez la méthode d’extension AddNpgsqlDbContext sur n’importe quelle IHostApplicationBuilder pour inscrire votre sous-classe DbContext à utiliser via le conteneur d’injection de dépendances. La méthode prend un paramètre de nom de connexion.

builder.AddNpgsqlDbContext<YourDbContext>(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é YourDbContext au générateur, vous pouvez obtenir l’instance YourDbContext à 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(YourDbContext context)
{
    // Use context...
}

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

Ajouter un contexte de base de données Npgsql avec enrichissement

Pour enrichir le DbContext avec des services supplémentaires, comme les tentatives automatiques, les vérifications d’intégrité, la journalisation et la télémétrie, appelez la méthode EnrichNpgsqlDbContext :

builder.EnrichNpgsqlDbContext<YourDbContext>(
    connectionName: "postgresdb",
    configureSettings: settings =>
    {
        settings.DisableRetry = false;
        settings.CommandTimeout = 30;
    });

Le paramètre settings est une instance de la classe NpgsqlEntityFrameworkCorePostgreSQLSettings.

Paramètres

L’intégration .NET AspirePostgreSQLEntity Framework Core 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 fournissez le nom de la chaîne de connexion lors de l’appel de la méthode AddNpgsqlDbContext :

builder.AddNpgsqlDbContext<MyDbContext>("pgdb");

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

{
  "ConnectionStrings": {
    "pgdb": "Host=myserver;Database=test"
  }
}

La EnrichNpgsqlDbContext n’utilise pas la section de configuration ConnectionStrings, car elle s’attend à ce qu’un DbContext soit inscrit au point où il est appelé.

Pour plus d’informations, consultez la ConnectionString.

Utiliser des fournisseurs de configuration

L’intégration .NET AspirePostgreSQLEntity Framework Core prend en charge Microsoft.Extensions.Configuration. Il charge le NpgsqlEntityFrameworkCorePostgreSQLSettings à partir de fichiers de configuration tels que appsettings.json à l’aide de la clé Aspire:Npgsql:EntityFrameworkCore:PostgreSQL. Si vous avez configuré vos configurations dans la section Aspire:Npgsql:EntityFrameworkCore:PostgreSQL, vous pouvez simplement appeler la méthode sans passer de paramètre.

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

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

Pour obtenir le schéma complet d’intégration client PostgreSQLEntity Framework CoreJSON, consultez Aspire. Npgsql.EntityFrameworkCore.PostgreSQL/ConfigurationSchema.json.

Utiliser des délégués inline

Vous pouvez également transmettre le délégué Action<NpgsqlEntityFrameworkCorePostgreSQLSettings> pour configurer certaines ou toutes les options en ligne, par exemple pour définir le ConnectionString:

builder.AddNpgsqlDbContext<YourDbContext>(
    "pgdb",
    static settings => settings.ConnectionString = "<YOUR CONNECTION STRING>");

Configurer plusieurs classes DbContext

Si vous souhaitez inscrire plusieurs DbContext avec une configuration différente, vous pouvez utiliser $"Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:{typeof(TContext).Name}" nom de section de configuration. La configuration json se présente comme suit :

{
  "Aspire": {
    "Npgsql": {
      "EntityFrameworkCore": {
        "PostgreSQL": {
          "ConnectionString": "<YOUR CONNECTION STRING>",
          "DisableHealthChecks": true,
          "DisableTracing": true,
          "AnotherDbContext": {
            "ConnectionString": "<ANOTHER CONNECTION STRING>",
            "DisableTracing": false
          }
        }
      }
    }
  }
}

Ensuite, l'appel de la méthode AddNpgsqlDbContext avec le paramètre de type AnotherDbContext chargerait les paramètres depuis la section Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:AnotherDbContext.

builder.AddNpgsqlDbContext<AnotherDbContext>();

Vérifications d’intégrité

Par défaut, les intégrations .NET.NET Aspire permettent les contrôles d'intégrité pour tous les services. Pour plus d’informations, consultez .NET.NET Aspire vue d’ensemble des intégrations.

Par défaut, les intégrations .NET AspirePostgreSQLEntity Framework Core gèrent les éléments suivants :

Ajoute la DbContextHealthCheck, qui appelle la méthode EF Core de CanConnectAsync. Le nom du test de santé est le nom du type TContext.
S’intègre au point de terminaison HTTP /health, qui spécifie que toutes les vérifications de l'état de santé enregistrées doivent réussir pour que l'application soit considérée comme prête à accepter le trafic.

Observabilité et télémétrie

.NET .NET Aspire intégrations configurent automatiquement les configurations de journalisation, de suivi et de 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 AspirePostgreSQLEntity Framework Core utilise les catégories de journal suivantes :

Microsoft.EntityFrameworkCore.ChangeTracking
Microsoft.EntityFrameworkCore.Database.Command
Microsoft.EntityFrameworkCore.Database.Connection
Microsoft.EntityFrameworkCore.Database.Transaction
Microsoft.EntityFrameworkCore.Migrations
Microsoft.EntityFrameworkCore.Infrastructure
Microsoft.EntityFrameworkCore.Migrations
Microsoft.EntityFrameworkCore.Model
Microsoft.EntityFrameworkCore.Model.Validation
Microsoft.EntityFrameworkCore.Query
Microsoft.EntityFrameworkCore.Update

Traçage

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

Npgsql

Métriques

L’intégration .NET AspirePostgreSQLEntity Framework Core émet les métriques suivantes à l’aide de OpenTelemetry:

Microsoft.EntityFrameworkCore :
- ec_Microsoft_EntityFrameworkCore_active_db_contexts
- ec_Microsoft_EntityFrameworkCore_total_queries
- ec_Microsoft_EntityFrameworkCore_queries_per_second
- ec_Microsoft_EntityFrameworkCore_total_save_changes
- ec_Microsoft_EntityFrameworkCore_save_changes_per_second
- ec_Microsoft_EntityFrameworkCore_compiled_query_cache_hit_rate
- ec_Microsoft_Entity_total_execution_strategy_operation_failures
- ec_Microsoft_E_execution_strategy_operation_failures_per_second
- ec_Microsoft_EntityFramew_total_optimistic_concurrency_failures
- ec_Microsoft_EntityF_optimistic_concurrency_failures_per_second
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

Voir aussi

PostgreSQL docs
.NET Aspire Azure PostgreSQLintégrationEntity Framework Core
intégrations .NET.NET Aspire
.NET Aspire GitHub de dépôt

Partager via