Notes
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
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 AspirePostgreSQLEntity Framework Core permet de se connecter à des bases de données existantes PostgreSQL ou de créer de nouvelles instances avec l'image de conteneur .NET à partir de 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 📦Aspire. Hébergement.PostgreSQL Package NuGet :
dotnet add package Aspire.Hosting.PostgreSQL
Pour plus d’informations, consultez dotnet add package ou .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 pgAdmin PostgreSQL
Lorsque vous ajoutez PostgreSQL des ressources à la builder en utilisant 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 PostgreSQL des ressources 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 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 aux montages de liaison , consultez la documentation Docker : 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 à l’aide du service managé Azure Database pour PostgreSQL héberger la base de données déployée au lieu d’un conteneur dans ACA, 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 données ont des fonctionnalités limitées par rapport aux volumes, qui offrent de meilleures performances, une meilleure portabilité et une sécurité accrue, ce qui les rend 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 montage de données est effectué sur le chemin C:\PostgreSQL\Data sous Windows (ou /PostgreSQL/Data sur Unix) sur la machine hôte, dans le conteneur 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 à l'aide du dossier init des conteneurs. Ce dossier est utilisé pour l’initialisation, 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 effectué à C:\PostgreSQL\Init sous Windows (ou à /PostgreSQL/Init sur Unix) sur la machine hôte, dans le conteneur de 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 de l'intégrité des intégrations 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
intégration Client
Pour commencer avec l’intégration du .NET AspirePostgreSQLEntity Framework Core client, installez le package NuGet 📦Aspire.Npgsql.EntityFrameworkCore.PostgreSQL dans le projet qui consomme le client, c'est-à-dire, le projet pour l’application qui utilise le PostgreSQL client. 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.
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 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 une ressource de 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 .NET l’injection de dépendances.
Enrichir un contexte de base de données Npgsql
Vous préférez peut-être utiliser la méthode Entity Framework standard pour obtenir un contexte de base de données et l’ajouter au conteneur d’injection de dépendances :
builder.Services.AddDbContext<YourDbContext>(options =>
options.UseNpgsql(builder.Configuration.GetConnectionString("postgresdb")
?? throw new InvalidOperationException("Connection string 'postgresdb' not found.")));
Remarque
Le nom de la chaîne de connexion que vous passez à la méthode GetConnectionString 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.
Vous disposez d’une plus grande flexibilité lorsque vous créez le contexte de base de données de cette façon, par exemple :
- Vous pouvez réutiliser le code de configuration existant pour le contexte de base de données sans le réécrire pour .NET.NET Aspire.
- Vous pouvez utiliser les intercepteurs Entity Framework Core pour modifier les opérations de base de données.
- Vous pouvez choisir de ne pas utiliser le regroupement de contextes Entity Framework Core, ce qui peut mieux fonctionner dans certaines circonstances.
Si vous utilisez cette méthode, vous pouvez améliorer le contexte de la base de données avec des réessais de style .NET.NET Aspire, des contrôles de l'intégrité, la journalisation, et des fonctionnalités de télémétrie en appelant la méthode EnrichNpgsqlDbContext :
builder.EnrichNpgsqlDbContext<YourDbContext>(
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 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 connaître le schéma complet PostgreSQLEntity Framework Core d’intégration JSON du client, consultez Aspire. Npgsql.EntityFrameworkCore.PostgreSQL/ConfigurationSchema.json.
Utiliser des délégués en ligne
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>();
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 :
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 typeTContext. - S’intègre au point de terminaison HTTP
/health, spécifiant que toutes les vérifications d'intégrité enregistrées doivent réussir pour que l'application soit jugée prête à accepter le 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 AspirePostgreSQLEntity Framework Core utilise les catégories de journal suivantes :
Microsoft.EntityFrameworkCore.ChangeTrackingMicrosoft.EntityFrameworkCore.Database.CommandMicrosoft.EntityFrameworkCore.Database.ConnectionMicrosoft.EntityFrameworkCore.Database.TransactionMicrosoft.EntityFrameworkCore.MigrationsMicrosoft.EntityFrameworkCore.InfrastructureMicrosoft.EntityFrameworkCore.MigrationsMicrosoft.EntityFrameworkCore.ModelMicrosoft.EntityFrameworkCore.Model.ValidationMicrosoft.EntityFrameworkCore.QueryMicrosoft.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_contextsec_Microsoft_EntityFrameworkCore_total_queriesec_Microsoft_EntityFrameworkCore_queries_per_secondec_Microsoft_EntityFrameworkCore_total_save_changesec_Microsoft_EntityFrameworkCore_save_changes_per_secondec_Microsoft_EntityFrameworkCore_compiled_query_cache_hit_rateec_Microsoft_Entity_total_execution_strategy_operation_failuresec_Microsoft_E_execution_strategy_operation_failures_per_secondec_Microsoft_EntityFramew_total_optimistic_concurrency_failuresec_Microsoft_EntityF_optimistic_concurrency_failures_per_second
Npgsql :
ec_Npgsql_bytes_written_per_secondec_Npgsql_bytes_read_per_secondec_Npgsql_commands_per_secondec_Npgsql_total_commandsec_Npgsql_current_commandsec_Npgsql_failed_commandsec_Npgsql_prepared_commands_ratioec_Npgsql_connection_poolsec_Npgsql_multiplexing_average_commands_per_batchec_Npgsql_multiplexing_average_write_time_per_batch
Voir aussi
Collaborer avec nous sur GitHub
La source de ce contenu se trouve sur GitHub, où vous pouvez également créer et examiner les problèmes et les demandes de tirage. Pour plus d’informations, consultez notre guide du contributeur.
