intégration de .NET AspireSQL ServerEntity Framework Core
inclut :intégration d’hébergement et Client intégration
SQL Server est un système de gestion de base de données relationnelle développé par Microsoft. L’intégration .NET AspireSQL ServerEntity Framework Core vous permet de vous connecter à des instances de SQL Server existantes ou de créer de nouvelles instances à partir de .NET avec l’image conteneur mcr.microsoft.com/mssql/server
.
Intégration de l’hébergement
L'intégration d'hébergement SQL Server modélise le serveur comme le type SqlServerServerResource et la base de données comme le type SqlServerDatabaseResource. Pour accéder à ces types et API, ajoutez le package NuGet 📦Aspire.Hosting.SqlServer dans le projet hôte de l'application .
dotnet add package Aspire.Hosting.SqlServer
Pour plus d’informations, consultez dotnet add package ou gérer les dépendances des packages dans .NET applications.
Ajouter la ressource SQL Server et la ressource de base de données
Dans votre projet hôte d’application, appelez AddSqlServer pour ajouter et retourner un générateur de ressources SQL Server. Chaînez un appel au générateur de ressources retourné vers AddDatabaseafin d'ajouter la ressource de base de données SQL Server.
var builder = DistributedApplication.CreateBuilder(args);
var sql = builder.AddSqlServer("sql")
.WithLifetime(ContainerLifetime.Persistent);
var db = sql.AddDatabase("database");
builder.AddProject<Projects.ExampleProject>()
.WithReference(db)
.WaitFor(db);
// After adding all resources, run the app...
Note
Le conteneur SQL Server est lent à démarrer. Il est donc préférable d'adopter une stratégie de durée de vie persistante pour éviter les redémarrages inutiles. Pour plus d’informations, consultez durée de vie des ressources du conteneur.
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 mcr.microsoft.com/mssql/server
, il crée une instance de SQL Server sur votre ordinateur local. Une référence à votre générateur de ressources SQL Server (la variable sql
) est utilisée pour ajouter une base de données. La base de données est nommée database
, puis ajoutée au ExampleProject
. La ressource SQL Server inclut les informations d’identification par défaut avec une username
de sa
et une password
aléatoire générée à l’aide de la méthode CreateDefaultPasswordParameter.
Lorsque l’hôte de l’application s’exécute, le mot de passe est stocké dans le magasin de secrets de l’hôte d’application. Elle est ajoutée à la section Parameters
, par exemple :
{
"Parameters:sql-password": "<THE_GENERATED_PASSWORD>"
}
Le nom du paramètre est sql-password
, mais il suffit de mettre en forme le nom de la ressource avec un suffixe -password
. Pour plus d’informations, consultez Stockage sécurisé des secrets d’application en développement dans ASP.NET Core et ajouter la ressource SQL Server avec des paramètres.
La méthode WithReference configure une connexion dans le ExampleProject
nommé database
.
Pourboire
Si vous préférez vous connecter à une SQL Serverexistante, appelez AddConnectionString à la place. Pour plus d’informations, consultez Référencer les ressources existantes.
Ajouter la ressource SQL Server avec le volume de données
Pour ajouter un volume de données à la ressource SQL Server, appelez la méthode WithDataVolume sur la ressource SQL Server :
var builder = DistributedApplication.CreateBuilder(args);
var sql = builder.AddSqlServer("sql")
.WithDataVolume();
var db = sql.AddDatabase("database");
builder.AddProject<Projects.ExampleProject>()
.WithReference(db)
.WaitFor(db);
// After adding all resources, run the app...
Le volume de données est utilisé pour conserver les données SQL Server en dehors du cycle de vie de son conteneur. Le volume de données est monté sur le chemin /var/opt/mssql
dans le conteneur SQL Server et lorsqu’un paramètre name
n’est pas fourni, le nom est généré de manière aléatoire. 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 la documentation Docker : Volumes.
Avertissement
Le mot de passe est stocké dans le volume de données. Lors de l’utilisation d’un volume de données et si le mot de passe change, il ne fonctionnera pas tant que vous ne supprimez pas le volume.
Ajouter la ressource SQL Server avec un montage de liaison des données
Pour ajouter un montage de liaison de données à la ressource SQL Server, appelez la méthode WithDataBindMount :
var builder = DistributedApplication.CreateBuilder(args);
var sql = builder.AddSqlServer("sql")
.WithDataBindMount(source: @"C:\SqlServer\Data");
var db = sql.AddDatabase("database");
builder.AddProject<Projects.ExampleProject>()
.WithReference(db)
.WaitFor(db);
// 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 une plus grande 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 SQL Server entre les redémarrages de conteneur. Le montage de liaison de données est monté sur le chemin d’accès C:\SqlServer\Data
sur Windows (ou /SqlServer/Data
sur Unix) sur l’ordinateur hôte dans le conteneur SQL Server. Pour plus d’informations sur les montages de liaison de données, consultez Docker docs : Liaison de montages.
Ajouter SQL Server ressource avec des paramètres
Lorsque vous souhaitez fournir explicitement le mot de passe utilisé 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 password = builder.AddParameter("password", secret: true);
var sql = builder.AddSqlServer("sql", password);
var db = sql.AddDatabase("database");
builder.AddProject<Projects.ExampleProject>()
.WithReference(db)
.WaitFor(db);
// After adding all resources, run the app...
Pour plus d’informations sur la fourniture de paramètres, consultez paramètres externes.
Se connecter aux ressources de base de données
Lorsque l’hôte d’application .NET.NET Aspire s’exécute, les ressources de base de données du serveur sont accessibles à partir d’outils externes, tels que SQL Server Management Studio (SSMS) ou Azure Data Studio. La chaîne de connexion de la ressource de base de données est disponible dans les variables d’environnement des ressources dépendantes et est accessible à l’aide du dashboard .NET.NET Aspire, dans le volet des détails des ressources. La variable d’environnement est nommée ConnectionStrings__{name}
où {name}
est le nom de la ressource de base de données, dans cet exemple, il s’agit de database
. Utilisez la chaîne de connexion pour vous connecter à la ressource de base de données à partir d’outils externes. Imaginez que vous disposez d’une base de données nommée todos
avec une table dbo.Todos
unique.
Pour vous connecter à la ressource de base de données à partir de SQL Server Management Studio, procédez comme suit :
Ouvrez SSMS.
Dans la boîte de dialogue Se connecter à Server, sélectionnez l’onglet Paramètres de connexion supplémentaires.
Collez la chaîne de connexion dans le champ Paramètres de connexion supplémentaires, puis sélectionnez Connecter.
Si vous êtes connecté, vous pouvez voir la ressource de base de données dans l’Explorateur d’objets :
Pour plus d’informations, consultez SQL Server Management Studio : Se connecter à un serveur.
Vérifications d’intégrité de l’intégration d’hébergement
L’intégration d’hébergement SQL Server ajoute automatiquement un contrôle d’intégrité pour la ressource SQL Server. La vérification d’intégrité vérifie que le SQL Server 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.SqlServer.
intégration de Client
Pour commencer à utiliser l’intégration .NET AspireSQL ServerEntity Framework Core, installez le package NuGet 📦Aspire.Microsoft.EntityFrameworkCore.SqlServer dans le projet qui utilise le client, à savoir le projet pour l’application qui utilise le client SQL ServerEntity Framework Core.
dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer
Pour plus d’informations, consultez dotnet add package ou gérer les dépendances des packages dans .NET applications.
Ajouter le contexte de la base de données SQL Server
Dans le fichier Program.cs de votre projet consommant le client, appelez la méthode d’extension AddSqlServerDbContext sur n’importe quel IHostApplicationBuilder pour inscrire un DbContext à utiliser via le conteneur d’injection de dépendances. La méthode prend un paramètre de nom de connexion.
builder.AddSqlServerDbContext<ExampleDbContext>(connectionName: "database");
Pourboire
Le paramètre connectionName
doit correspondre au nom utilisé lors de l’ajout de la ressource de base de données SQL Server dans le projet hôte de l’application. En d’autres termes, lorsque vous appelez AddDatabase
et fournissez un nom de database
ce même nom doit être utilisé lors de l’appel de AddSqlServerDbContext
. Pour plus d’informations, consultez Ajouter SQL Server ressource et ressource de base de données.
Pour récupérer un objet ExampleDbContext
à partir d’un service :
public class ExampleService(ExampleDbContext context)
{
// Use context...
}
Pour plus d’informations sur l’injection de dépendances, consultez .NET injection de dépendances.
Ajouter le contexte de base de données SQL Server avec un enrichissement
Pour enrichir le DbContext
avec des services supplémentaires, tels que les réessais automatiques, les contrôles de santé, les journaux et la télémétrie, appelez la méthode EnrichSqlServerDbContext :
builder.EnrichSqlServerDbContext<ExampleDbContext>(
connectionName: "database",
configureSettings: settings =>
{
settings.DisableRetry = false;
settings.CommandTimeout = 30 // seconds
});
Le paramètre settings
est une instance de la classe MicrosoftEntityFrameworkCoreSqlServerSettings.
Configuration
L’intégration .NET AspireSQL ServerEntity Framework Core fournit plusieurs approches et options de configuration pour répondre aux exigences et conventions de votre projet.
Utiliser la 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 builder.AddSqlServerDbContext<TContext>()
:
builder.AddSqlServerDbContext<ExampleDbContext>("sql");
La chaîne de connexion est récupérée à partir de la section de configuration ConnectionStrings
:
{
"ConnectionStrings": {
"sql": "Data Source=myserver;Initial Catalog=master"
}
}
La EnrichSqlServerDbContext
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 AspireSQL ServerEntity Framework Core prend en charge Microsoft.Extensions.Configuration. Il charge le MicrosoftEntityFrameworkCoreSqlServerSettings à partir de fichiers de configuration tels que appsettings.json à l’aide de la clé Aspire:Microsoft:EntityFrameworkCore:SqlServer
. Si vous avez configuré vos configurations dans la section Aspire:Microsoft:EntityFrameworkCore:SqlServer
, vous pouvez simplement appeler la méthode sans passer de paramètre.
Voici un exemple de fichier appsettings.json qui configure certaines des options disponibles :
{
"Aspire": {
"Microsoft": {
"EntityFrameworkCore": {
"SqlServer": {
"ConnectionString": "YOUR_CONNECTIONSTRING",
"DbContextPooling": true,
"DisableHealthChecks": true,
"DisableTracing": true,
"DisableMetrics": false
}
}
}
}
}
Utiliser des configurations inline
Vous pouvez également transmettre le délégué Action<MicrosoftEntityFrameworkCoreSqlServerSettings>
pour configurer certaines ou toutes les options en ligne, par exemple pour désactiver les métriques :
builder.AddSqlServerDbContext<YourDbContext>(
"sql",
static settings =>
settings.DisableMetrics = true);
Configurer plusieurs connexions DbContext
Si vous souhaitez inscrire plusieurs DbContext
avec une configuration différente, vous pouvez utiliser $"Aspire.Microsoft.EntityFrameworkCore.SqlServer:{typeof(TContext).Name}"
nom de section de configuration. La configuration json se présente comme suit :
{
"Aspire": {
"Microsoft": {
"EntityFrameworkCore": {
"SqlServer": {
"ConnectionString": "YOUR_CONNECTIONSTRING",
"DbContextPooling": true,
"DisableHealthChecks": true,
"DisableTracing": true,
"DisableMetrics": false,
"AnotherDbContext": {
"ConnectionString": "AnotherDbContext_CONNECTIONSTRING",
"DisableTracing": false
}
}
}
}
}
}
Ensuite, en appelant la méthode AddSqlServerDbContext
avec un paramètre de type AnotherDbContext
, cela chargerait les paramètres depuis la section Aspire:Microsoft:EntityFrameworkCore:SqlServer:AnotherDbContext
.
builder.AddSqlServerDbContext<AnotherDbContext>("another-sql");
Options de configuration
Voici les options configurables avec les valeurs par défaut correspondantes :
Nom | Description |
---|---|
ConnectionString |
Chaîne de connexion de la base de données SQL Server à laquelle se connecter. |
DbContextPooling |
Valeur booléenne qui indique si le contexte de base de données sera mis en pool ou créé explicitement chaque fois qu’il est demandé |
MaxRetryCount |
Nombre maximal de nouvelles tentatives. La valeur par défaut est 6, définissez-la sur 0 pour désactiver le mécanisme de nouvelle tentative. |
DisableHealthChecks |
Valeur booléenne qui indique si la vérification d’intégrité de la base de données est désactivée ou non. |
DisableTracing |
Valeur booléenne qui indique si le suivi OpenTelemetry est désactivé ou non. |
DisableMetrics |
Valeur booléenne qui indique si les métriques OpenTelemetry sont désactivées ou non. |
Timeout |
Temps en secondes d’attente de l’exécution de la commande. |
Vérifications d’intégrité
Par défaut, les .NET.NET Aspire intégrations permettent les contrôles de l'état de santé pour tous les services. Pour plus d’informations, consultez .NET.NET Aspire vue d’ensemble des intégrations.
Par défaut, l’intégration .NET Aspire Sql ServerEntity Framework Core gère les opérations suivantes :
- Ajoute la
DbContextHealthCheck
, qui appelle la méthode EF Core de CanConnectAsync. Le nom du contrôle de santé est le nom du typeTContext
. - S’intègre au point de terminaison HTTP
/health
, qui spécifie que toutes les vérifications d’intégrité enregistrées doivent être validées pour que l’application soit prête à accepter du trafic.
Observabilité et télémétrie
.NET .NET Aspire intégrations configurent automatiquement la journalisation, le suivi et les métriques, parfois appelés 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 AspireSQL ServerEntity Framework Core utilise les catégories de log suivantes :
Microsoft.EntityFrameworkCore.ChangeTracking
Microsoft.EntityFrameworkCore.Database.Command
Microsoft.EntityFrameworkCore.Database.Connection
Microsoft.EntityFrameworkCore.Database.Transaction
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 AspireSQL ServerEntity Framework Core émettra les activités de suivi suivantes à l’aide de OpenTelemetry:
- "OpenTelemetry.Instrumentation.EntityFrameworkCore"
Métriques
L’intégration .NET AspireSQL ServerEntity 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
Voir aussi
- documentation Azure SQL Database
- intégrations .NET.NET Aspire
- .NET Aspire GitHub dépôt