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
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
L'intégration d'hébergement SQL Server modélise le serveur 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
Pour plus d’informations, consultez dotnet add package ou Gérer les dépendances des packages 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>("exampleproject")
.WithReference(db)
.WaitFor(db);
// After adding all resources, run the app...
builder.Build().Run();
Remarque
Le conteneur SQL Server est lent à démarrer, il est donc préférable d'utiliser une durée de vie persistante pour éviter les redémarrages inutiles. Pour plus d’informations, consultez durée de vie des ressources de 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
.
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 sql
ressource est prête, l’événement est déclenché et la ressource de base de données est créée.
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
.
Conseil / Astuce
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 une SQL Server ressource avec des scripts de base de données
Par défaut, lorsque vous ajoutez un SqlServerDatabaseResource, cela s'appuie sur le script SQL suivant pour créer la base de données :
IF
(
NOT EXISTS
(
SELECT 1
FROM sys.databases
WHERE name = @DatabaseName
)
)
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 sql = builder.AddSqlServer("sql")
.WithLifetime(ContainerLifetime.Persistent);
var databaseName = "app-db";
var creationScript = $$"""
IF DB_ID('{{databaseName}}') IS NULL
CREATE DATABASE [{{databaseName}}];
GO
-- Use the database
USE [{{databaseName}}];
GO
-- Create the todos table
CREATE TABLE todos (
id INT PRIMARY KEY IDENTITY(1,1), -- Unique ID for each todo
title VARCHAR(255) NOT NULL, -- Short description of the task
description TEXT, -- Optional detailed description
is_completed BIT DEFAULT 0, -- Completion status
due_date DATE, -- Optional due date
created_at DATETIME DEFAULT GETDATE() -- Creation timestamp
);
GO
""";
var db = sql.AddDatabase(databaseName)
.WithCreationScript(creationScript);
builder.AddProject<Projects.AspireApp_ExampleProject>("exampleproject")
.WithReference(db)
.WaitFor(db);
// After adding all resources, run the app...
builder.Build().Run();
L'exemple précédent crée une base de données nommée app_db
avec une table todos
unique. Le script SQL est exécuté lors de la création de la ressource de base de données. Le script est passé en tant que chaîne au WithCreationScript
méthode, qui est ensuite exécutée dans le contexte de la ressource SQL Server.
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.AspireApp_ExampleProject>("exampleproject")
.WithReference(db)
.WaitFor(db);
// After adding all resources, run the app...
builder.Build().Run();
Le volume de données est utilisé pour conserver les données SQL Server en dehors du cycle de vie de son conteneur. Lorsqu’un paramètre /var/opt/mssql
n’est pas fourni, le volume de données est monté à l'emplacement SQL Server dans le conteneur name
et le nom est généré aléatoirement. Pour plus d’informations sur les volumes de données et pourquoi ils sont préférés par rapport aux bind mounts, voir 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 avec liaison 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.AspireApp_ExampleProject>("exampleproject")
.WithReference(db)
.WaitFor(db);
// After adding all resources, run the app...
builder.Build().Run();
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 par lien autorisent l’accès direct et la modification des fichiers sur le système hôte, idéal pour le développement et les tests où des 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 lors des redémarrages du conteneur. Le point de montage de liaison de données est monté à C:\SqlServer\Data
sous Windows (ou /SqlServer/Data
sur Unix) sur le chemin de la machine hôte dans le conteneur SQL Server. Pour plus d'informations sur les montages de liaison de données, consultez les documents Docker : montages 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.AspireApp_ExampleProject>("exampleproject")
.WithReference(db)
.WaitFor(db);
// After adding all resources, run the app...
builder.Build().Run();
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 MSSQL pour Visual Studio Code. 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.
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 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. Le contrôle de santé vérifie que le SQL Server fonctionne 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 Client
Pour commencer à utiliser l’intégration du client .NET AspireSQL Server, installez le 📦Aspire. Microsoft.Data.SqlClient package NuGet dans le projet consommant le client, c’est-à-dire le projet pour l’application qui utilise le client SQL Server. L’intégration du client SQL Server inscrit une instance de SqlConnection que vous pouvez utiliser pour interagir avec SQL Server.
dotnet add package Aspire.Microsoft.Data.SqlClient
Ajouter SQL Server client
Dans le fichier Program.cs de votre projet consommant le client, appelez la méthode d’extension AddSqlServerClient sur n’importe quel IHostApplicationBuilder pour inscrire un SqlConnection
à utiliser via le conteneur d’injection de dépendances. La méthode prend un paramètre de nom de connexion.
builder.AddSqlServerClient(connectionName: "database");
Conseil / Astuce
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 AddSqlServerClient
. Pour plus d’informations, consultez Ajouter SQL Server une ressource et une ressource de base de données.
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 un client SQL Server avec clé
Il peut arriver que vous souhaitiez inscrire plusieurs instances de SqlConnection
avec différents noms de connexion. Pour enregistrer des clients à clé SQL Server, appelez la méthode AddKeyedSqlServerClient :
builder.AddKeyedSqlServerClient(name: "mainDb");
builder.AddKeyedSqlServerClient(name: "loggingDb");
Important
Lorsque vous utilisez des services à clé, il est prévu que votre ressource SQL Server a configuré deux bases de données nommées, une pour le mainDb
et l’autre pour le 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 avec clé, voir la section .NET injection de dépendances : services avec clé.
Paramétrage
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 depuis la configuration en utilisant 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 de l’intégration du client SQL ServerJSON, 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 en ligne, par exemple pour désactiver les contrôles de santé depuis le code :
builder.AddSqlServerClient(
"database",
static settings => settings.DisableHealthChecks = true);
Client vérifications de l'état d'intégration
Par défaut, les intégrations .NET.NET Aspire activent les contrôles de santé pour tous les services. Pour plus d’informations, consultez .NET.NET Aspire vue d’ensemble des intégrations.
L'intégration .NET AspireSQL Server :
- Ajoute la vérification de l'état de santé lorsque MicrosoftDataSqlClientSettings.DisableHealthChecks est
false
, et 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