Partager via


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}{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 :

  1. Ouvrez SSMS.

  2. Dans la boîte de dialogue Se connecter à Server, sélectionnez l’onglet Paramètres de connexion supplémentaires.

  3. Collez la chaîne de connexion dans le champ Paramètres de connexion supplémentaires, puis sélectionnez Connecter.

    SQL Server Management Studio : se connecter à la boîte de dialogue Server.

  4. Si vous êtes connecté, vous pouvez voir la ressource de base de données dans l’Explorateur d’objets :

    SQL Server Management Studio : connecté à la base de données.

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 type TContext.
  • 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