intégration de .NET AspireSQL Server

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 Server 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

Les modèles d'intégration SQL Server intègrent le server en tant que type SqlServerServerResource et la base de données en tant que 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

<PackageReference Include="Aspire.Hosting.SqlServer"
                  Version="*" />

Pour plus d’informations, consultez dotnet add package ou Gérer les dépendances de package dans les applications .NET.

Ajouter la ressource SQL Server et celle 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é à AddDatabasepour 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...

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 stockage sécurisé 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 dans le développement dans ASP.NET Core et Ajouter SQL Server ressource avec des paramètres.

La méthode WithReference configure une connexion dans le ExampleProject nommé database.

Ajouter la ressource SQL Server avec un 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 d’accès /var/opt/mssql dans le conteneur SQL Server et lorsqu’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 par rapport aux montages de liaison , consultez les docs Docker : Volumes.

Ajouter une ressource SQL Server avec un montage lié de 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...

Les montages de liaison de données s’appuient sur le système de fichiers de la machine hôte pour conserver les données SQL Server lors des 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 la documentation Docker : montage de liaison.

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 Aspire s’exécute, les ressources de base de données de serversont 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 tableau de bord .NET.NET Aspire : volet Détails de la ressource. 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.

Vérifications de l’intégrité des intégrations 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 Serverclient, installez la 📦Aspire. Microsoft.Data.SqlClient package NuGet dans le projet client-consommant, c’est-à-dire le projet pour l’application qui utilise le SQL Serverclient. L’intégration SQL Serverclient inscrit une instance de SqlConnection que vous pouvez utiliser pour interagir avec SQL Server.

dotnet add package Aspire.Microsoft.Data.SqlClient

<PackageReference Include="Aspire.Microsoft.Data.SqlClient"
                  Version="*" />

Ajouter SQL Serverclient

Dans le fichier Program.cs de votre projet utilisant client, appelez la méthode d’extension AddSqlServerClient sur un IHostApplicationBuilder quelconque pour enregistrer un SqlConnection à utiliser via le conteneur d’injection de dépendance. La méthode prend un paramètre de nom de connexion.

builder.AddSqlServerClient(connectionName: "database");

Vous pouvez ensuite récupérer l’instance SqlConnection à l’aide de l’injection de dépendances. Par exemple, pour récupérer la connexion à partir d’un exemple de service :

public class ExampleService(SqlConnection connection)
{
    // Use connection...
}

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

Ajouter des SQL Serverclient à clé

Il peut arriver que vous souhaitiez inscrire plusieurs instances de SqlConnection avec différents noms de connexion. Pour enregistrer les clients à clé SQL Server, appelez la méthode AddKeyedSqlServerClient :

builder.AddKeyedSqlServerClient(name: "mainDb");
builder.AddKeyedSqlServerClient(name: "loggingDb");

Vous pouvez ensuite récupérer les instances SqlConnection à l’aide de l’injection de dépendances. Par exemple, pour récupérer la connexion à partir d’un exemple de service :

public class ExampleService(
    [FromKeyedServices("mainDb")] SqlConnection mainDbConnection,
    [FromKeyedServices("loggingDb")] SqlConnection loggingDbConnection)
{
    // Use connections...
}

Pour plus d’informations sur les services à clé, consultez .NET injection de dépendances : services à clé.

Configuration

L’intégration .NET AspireSQL Server fournit plusieurs options pour configurer la connexion en fonction des exigences et des 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 pouvez fournir le nom de la chaîne de connexion lors de l’appel de la méthode AddSqlServerClient :

builder.AddSqlServerClient(connectionName: "sql");

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

{
  "ConnectionStrings": {
    "database": "Data Source=myserver;Initial Catalog=master"
  }
}

Pour plus d’informations sur la mise en forme de cette chaîne de connexion, consultez la ConnectionString.

Utiliser des fournisseurs de configuration

L'intégration de .NET AspireetSQL Server prend en charge Microsoft.Extensions.Configuration. Il charge le MicrosoftDataSqlClientSettings à partir de la configuration à l’aide de la clé Aspire:Microsoft:Data:SqlClient. L’extrait de code suivant est un exemple de fichier appsettings.json qui configure certaines des options :

{
  "Aspire": {
    "Microsoft": {
      "Data": {
        "SqlClient": {
          "ConnectionString": "YOUR_CONNECTIONSTRING",
          "DisableHealthChecks": false,
          "DisableMetrics": true
        }
      }
    }
  }
}

Pour obtenir le schéma complet SQL Serverclient d’intégration JSON, consultez Aspire. Microsoft.Data.SqlClient/ConfigurationSchema.json.

Utiliser des délégués en ligne

Vous pouvez également transmettre le délégué Action<MicrosoftDataSqlClientSettings> configureSettings pour configurer certaines ou toutes les options inline, par exemple pour désactiver les vérifications d’intégrité à partir du code :

builder.AddSqlServerClient(
    "database",
    static settings => settings.DisableHealthChecks = true);

Client vérifications d’intégrité de l’intégration

Par défaut, les .NET.NET Aspire intégrations activent les vérifications de l'état de santé pour tous les services. Pour plus d’informations, consultez .NET.NET Aspire vue d’ensemble des intégrations.

Intégration .NET AspireSQL Server :

• Ajoute la vérification de l'intégrité lorsque MicrosoftDataSqlClientSettings.DisableHealthChecks est falseet tente de se connecter au SQL Server.
• 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 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 AspireSQL Server n’active actuellement pas la journalisation par défaut en raison des limitations de la Microsoft.Data.SqlClient.

Traçage

L’intégration .NET AspireSQL Server émet les activités de suivi suivantes à l’aide de OpenTelemetry:

• OpenTelemetry.Instrumentation.SqlClient

Métriques

L’intégration .NET AspireSQL Server émet les métriques suivantes à l’aide de OpenTelemetry:

• Microsoft.Data.SqlClient.EventSource
  • active-hard-connections
  • hard-connects
  • hard-disconnects
  • active-soft-connects
  • soft-connects
  • soft-disconnects
  • number-of-non-pooled-connections
  • number-of-pooled-connections
  • number-of-active-connection-pool-groups
  • number-of-inactive-connection-pool-groups
  • number-of-active-connection-pools
  • number-of-inactive-connection-pools
  • number-of-active-connections
  • number-of-free-connections
  • number-of-stasis-connections
  • number-of-reclaimed-connections

Voir aussi

• Azure Base de données SQL
• SQL Server
• .NET .NET Aspire exemples de conteneurs de base de données
• intégrations .NET.NET Aspire
• .NET Aspire GitHub repo de référentiel