Partager via

intégration de .NET AspirePostgreSQLEntity Framework Core

  • Article

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

L'intégration d'hébergement du modèle PostgreSQL représente un PostgreSQLserver comme le type PostgresServerResource. Pour accéder à ce type et à ces API qui vous permettent de l’ajouter à votre 📦Aspire. HébergementPostgreSQL, package NuGet dans le projet hôte de l’application .

dotnet add package Aspire.Hosting.PostgreSQL

Pour plus d’informations, consultez dotnet add package ou Gérer les dépendances de paquets 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 cycle de vie des ressources 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 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 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 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.

Ajouter une ressource PostgreSQLserver avec des volumes 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é sur le chemin d’accès /var/lib/postgresql/data dans le conteneur PostgreSQLserver et si un paramètre name n’est pas fourni, le 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 aux montages de liaison , consultez la documentation Docker : 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, 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 PostgreSQLserver lors des redémarrages des conteneurs. Le montage de liaison de données est monté dans le chemin C:\PostgreSQL\Data sur Windows (ou sur le chemin /PostgreSQL/Data sur Unix) sur l’ordinateur hôte du conteneur PostgreSQLserver. Pour plus d’informations sur les montages de liaison de données, consultez Docker docs : Liaison de montages.

Ajouter la ressource PostgreSQLserver avec montage de liaison d'initialisation

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 l’ordinateur hôte pour initialiser la base de données PostgreSQLserver 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 .sql fichiers de commande après la création du dossier postgres-data. Le montage bind init est monté sur le chemin C:\PostgreSQL\Init sur Windows (ou sur le chemin d'accès /PostgreSQL/Init sur Unix) de 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é confirme que le PostgreSQLserver fonctionne et qu’une connexion peut être établie avec 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 AspirePostgreSQLEntity Framework Coreclient, installez le package NuGet 📦Aspire.Npgsql.EntityFrameworkCore.PostgreSQL dans le projet qui consomme client, c’est-à-dire le projet pour l’application utilisant PostgreSQLclient. L’intégration .NET AspirePostgreSQLEntity Framework Coreclient inscrit vos instances de sous-classe DbContext souhaitées que vous pouvez utiliser pour interagir avec PostgreSQL.

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

Ajouter un contexte de base de données Npgsql

Dans le fichier Program.cs de votre projet consommant client, appelez la méthode d’extension AddNpgsqlDbContext sur n’importe quel IHostApplicationBuilder pour enregistrer votre sous-classe DbContext afin de l'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 PostgreSQLserver dans le projet hôte de l’application. Pour plus d’informations, consultez Ajouter PostgreSQLserverressource .

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",
          "DbContextPooling": true,
          "DisableHealthChecks": true,
          "DisableTracing": true
        }
      }
    }
  }
}

Pour obtenir le schéma complet PostgreSQLEntity Framework CoreclientJSON d’intégration, 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>",
          "DbContextPooling": true,
          "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 CanConnectAsync de EF Core. 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.Infrastructure
  • 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 émettra 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

intégration d’hébergement AzurePostgreSQL

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

dotnet add package Aspire.Hosting.Azure.PostgreSQL

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 server PostgreSQL pour être déployée comme AzurePostgres flexible Server.

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

Ajouter Azureclient Npgsql authentifié

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 :

dotnet add package Azure.Identity

La connexion PostgreSQL peut être utilisée en utilisant l’intégration client et Azure.Identity:

builder.AddNpgsqlDbContext<YourDbContext>(
    "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.

Voir aussi