Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
Inclusief:
—&— Client integratie
SQL Server is een relationeel databasebeheersysteem dat is ontwikkeld door Microsoft. Met de .NET AspireSQL Server-integratie kunt u verbinding maken met bestaande SQL Server-instanties of nieuwe instanties maken vanuit .NET met de mcr.microsoft.com/mssql/server containerafbeelding.
Hostingintegratie
De SQL Server-hostingintegratie modelleert de server als het SqlServerServerResource-type en de database als het SqlServerDatabaseResource-type. Als u toegang wilt krijgen tot deze typen en API's, voegt u het NuGet-pakket 📦Aspire.Hosting.SqlServer toe aan het app-hostproject.
dotnet add package Aspire.Hosting.SqlServer
Zie dotnet pakket toevoegen of Pakketafhankelijkheden beheren in .NET toepassingenvoor meer informatie.
SQL Server resource en databaseresource toevoegen
Roep in uw app-hostingsproject AddSqlServer aan om een resourcebouwer voor SQL Server toe te voegen en te retourneren. Verbind een oproep met de geretourneerde resource builder naar AddDatabaseom de databaseresource SQL Server toe te voegen.
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();
Notitie
De SQL Server container start traag op, dus het is beter om een permanente levensduur te gebruiken om onnodige herstarts te voorkomen. Zie Levensduur van containerresourcesvoor meer informatie.
Wanneer .NET.NET Aspire een containerinstallatiekopie toevoegt aan de app-host, zoals wordt weergegeven in het vorige voorbeeld met de mcr.microsoft.com/mssql/server-installatiekopie, wordt er een nieuw SQL Server exemplaar op uw lokale computer gemaakt. Een verwijzing naar de SQL Server resourcebouwer (de sql variabele) wordt gebruikt om een database toe te voegen. De database heeft de naam database en wordt vervolgens toegevoegd aan de ExampleProject.
Wanneer u een databaseresource toevoegt aan het app-model, wordt de database gemaakt als deze nog niet bestaat. Het maken van de database is afhankelijk van de gebeurtenis-API's van de app-host, met name ResourceReadyEvent. Met andere woorden, wanneer de sql resource gereed is, wordt de gebeurtenis getriggerd en wordt de databaseresource gemaakt.
De SQL Server-resource bevat standaardreferenties met een username van sa en een willekeurige password die is gegenereerd met behulp van de CreateDefaultPasswordParameter-methode.
Wanneer de app-host wordt uitgevoerd, wordt het wachtwoord opgeslagen in de geheime opslag van de app-host. Deze wordt toegevoegd aan de sectie Parameters, bijvoorbeeld:
{
"Parameters:sql-password": "<THE_GENERATED_PASSWORD>"
}
De naam van de parameter is sql-password, maar eigenlijk is het alleen het opmaken van de resourcenaam met een -password achtervoegsel. Voor meer informatie, zie Veilige opslag van app-geheimen in ontwikkeling in ASP.NET Core en SQL Server resource toevoegen met parameters.
De methode WithReference configureert een verbinding in de ExampleProject met de naam database.
Aanbeveling
Als u liever verbinding wilt maken met een bestaande SQL Server, roept u in plaats daarvan AddConnectionString aan. Raadpleeg bestaande bronnenvoor meer informatie.
Resource toevoegen SQL Server met databasescripts
Wanneer u een SqlServerDatabaseResourcetoevoegt, is het standaard afhankelijk van het volgende SQL-script om de database te maken:
IF
(
NOT EXISTS
(
SELECT 1
FROM sys.databases
WHERE name = @DatabaseName
)
)
CREATE DATABASE [<QUOTED_DATABASE_NAME>];
Als u het standaardscript wilt wijzigen, koppelt u een aanroep aan de WithCreationScript methode in de opbouwfunctie voor databaseresources:
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();
In het voorgaande voorbeeld wordt een database gemaakt met een naam app_db met één todos tabel. Het SQL-script wordt uitgevoerd wanneer de databaseresource wordt gemaakt. Het script wordt doorgegeven als een tekenreeks aan de WithCreationScript methode, die vervolgens wordt uitgevoerd in de context van de SQL Server resource.
SQL Server resource toevoegen met gegevensvolume
Als u een gegevensvolume wilt toevoegen aan de SQL Server-resource, roept u de methode WithDataVolume aan voor de SQL Server resource:
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();
Het gegevensvolume wordt gebruikt om de SQL Server gegevens buiten de levenscyclus van de container te behouden. Het gegevensvolume wordt gekoppeld aan het /var/opt/mssql pad in de SQL Server container en wanneer er geen name parameter wordt opgegeven, wordt de naam willekeurig gegenereerd. Voor meer informatie over gegevensvolumes en waarom ze de voorkeur hebben boven bind mounts , zie Docker documentatie: Volumes.
Waarschuwing
Het wachtwoord wordt opgeslagen in het gegevensvolume. Wanneer u een gegevensvolume gebruikt en als het wachtwoord wordt gewijzigd, werkt het pas als u het volume verwijdert.
SQL Server resource toevoegen met koppeling voor gegevensbinding
Als u een koppeling voor gegevensbinding wilt toevoegen aan de SQL Server-resource, roept u de WithDataBindMount methode aan:
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();
Belangrijk
Koppelingsbestanden hebben beperkte functionaliteit in vergelijking met volumes, die betere prestaties, draagbaarheid, en beveiliging bieden, waardoor ze geschikter zijn voor productieomgevingen. Bindmounts bieden echter directe toegang tot en de mogelijkheid om bestanden op het hostsysteem te wijzigen, ideaal voor ontwikkeling en testen wanneer realtime wijzigingen nodig zijn.
Data-bind-mounts maken gebruik van het bestandssysteem van de hostmachine om de SQL Server-data bij herstarten van de container te behouden. De koppeling voor gegevensbinding wordt gekoppeld aan de C:\SqlServer\Data in Windows (of /SqlServer/Data op Unix) op de hostcomputer in de SQL Server container. Zie Docker docs: Bindingskoppelingenvoor meer informatie over de koppeling van gegevens.
SQL Server resource toevoegen met parameters
Wanneer u expliciet het wachtwoord wilt opgeven dat door de containerafbeelding wordt gebruikt, kunt u deze inloggegevens als parameters opgeven. Bekijk het volgende alternatieve voorbeeld:
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();
Zie Externe parametersvoor meer informatie over het opgeven van parameters.
Verbinding maken met databasebronnen
Wanneer de .NET.NET Aspire-app-host wordt uitgevoerd, kunnen de databasebronnen van de server worden geopend vanuit externe hulpprogramma's, zoals SQL Server Management Studio (SSMS) of MSSQL voor Visual Studio Code. De verbindingsreeks voor de databaseresource is beschikbaar in de omgevingsvariabelen van afhankelijke resources en wordt geopend via het .NET.NET Aspire dashboard: Resourcedetails deelvenster. De omgevingsvariabele heet ConnectionStrings__{name} waar {name} de naam van de databaseresource is, in dit voorbeeld is deze database. Gebruik de verbindingsreeks om verbinding te maken met de databaseresource vanuit externe hulpprogramma's. Stel dat u een database hebt met de naam todos met één dbo.Todos tabel.
Voer de volgende stappen uit om vanuit SQL Server Management Studio verbinding te maken met de databaseresource:
Open SQL Server Management Studio.
Selecteer in het dialoogvenster Verbinding maken met Server het tabblad Aanvullende verbindingsparameters.
Plak de verbindingsreeks in het veld Aanvullende verbindingsparameters en selecteer Verbinding maken.
Als u verbinding hebt, ziet u de databaseresource in de Objectverkenner:
Zie SQL Server Management Studio: Verbinding maken met een servervoor meer informatie.
Gezondheidscontroles voor hostingintegratie
De SQL Server hostingintegratie voegt automatisch een statuscontrole toe voor de SQL Server resource. De gezondheidscontrole controleert of de SQL Server draait en of er een verbinding kan worden gemaakt.
De hostingintegratie is afhankelijk van het 📦 AspNetCore.HealthChecks.SqlServer NuGet-pakket.
Client integratie
Installeer het NuGet-pakket .NET Aspire in het project dat de client gebruikt, dat wil zeggen, het project voor de toepassing die gebruikmaakt van de SQL Server-client, om aan de slag te gaan met de 📦Aspire-clientintegratie. De SQL Server-clientintegratie registreert een SqlConnection exemplaar dat u kunt gebruiken om met SQL Serverte communiceren.
dotnet add package Aspire.Microsoft.Data.SqlClient
SQL Server-client toevoegen
Roep in het Program.cs bestand van het clientgebruikte project de AddSqlServerClient-extensiemethode aan op een IHostApplicationBuilder om een SqlConnection te registreren voor gebruik via de container voor afhankelijkheidsinjectie. De methode gebruikt een verbindingsnaamparameter.
builder.AddSqlServerClient(connectionName: "database");
Aanbeveling
De parameter connectionName moet overeenkomen met de naam die wordt gebruikt bij het toevoegen van de SQL Server databaseresource in het app-hostproject. Met andere woorden, wanneer u AddDatabase aanroept en een naam opgeeft van database diezelfde naam moet worden gebruikt bij het aanroepen van AddSqlServerClient. Voor meer informatie, zie SQL Server-bron en databaseresource toevoegen.
Vervolgens kunt u het SqlConnection exemplaar ophalen met behulp van afhankelijkheidsinjectie. Als u bijvoorbeeld de verbinding wilt ophalen uit een voorbeeldservice:
public class ExampleService(SqlConnection connection)
{
// Use connection...
}
Voor meer informatie over afhankelijkheidsinjectie, zie .NET afhankelijkheidsinjectie.
Voeg klant met sleutel SQL Server toe
Er kunnen situaties zijn waarin u meerdere SqlConnection exemplaren met verschillende verbindingsnamen wilt registreren. Om kliënten met sleutel SQL Server te registreren, roept u de methode AddKeyedSqlServerClient op.
builder.AddKeyedSqlServerClient(name: "mainDb");
builder.AddKeyedSqlServerClient(name: "loggingDb");
Belangrijk
Wanneer u sleutelservices gebruikt, wordt verwacht dat uw SQL Server resource twee benoemde databases heeft geconfigureerd, één voor de mainDb en één voor de loggingDb.
Vervolgens kunt u de SqlConnection instanties ophalen via afhankelijkheidsinjectie. Als u bijvoorbeeld de verbinding wilt ophalen uit een voorbeeldservice:
public class ExampleService(
[FromKeyedServices("mainDb")] SqlConnection mainDbConnection,
[FromKeyedServices("loggingDb")] SqlConnection loggingDbConnection)
{
// Use connections...
}
Voor meer informatie over sleutelservices, zie .NET afhankelijkheidsinjectie: sleutelservices.
Configuratie
De .NET AspireSQL Server-integratie biedt meerdere opties voor het configureren van de verbinding op basis van de vereisten en conventies van uw project.
Een verbindingsreeks gebruiken
Wanneer u een verbindingsreeks uit de sectie ConnectionStrings configuratie gebruikt, kunt u de naam van de verbindingsreeks opgeven bij het aanroepen van de AddSqlServerClient methode:
builder.AddSqlServerClient(connectionName: "sql");
Vervolgens wordt de verbindingsreeks opgehaald uit de ConnectionStrings configuratiesectie:
{
"ConnectionStrings": {
"database": "Data Source=myserver;Initial Catalog=master"
}
}
Zie de ConnectionStringvoor meer informatie over het opmaken van deze verbindingsreeks.
Configuratieproviders gebruiken
De .NET AspireSQL Server-integratie ondersteunt Microsoft.Extensions.Configuration. Het laadt de MicrosoftDataSqlClientSettings vanuit de configuratie door gebruik te maken van de Aspire:Microsoft:Data:SqlClient-sleutel. Het volgende codefragment is een voorbeeld van een appsettings.json-bestand waarmee een aantal van de opties wordt geconfigureerd:
{
"Aspire": {
"Microsoft": {
"Data": {
"SqlClient": {
"ConnectionString": "YOUR_CONNECTIONSTRING",
"DisableHealthChecks": false,
"DisableMetrics": true
}
}
}
}
}
Zie voor het volledige SQL Server clientintegratieschema JSON, Aspire.Microsoft.Data.SqlClient/ConfigurationSchema.json.
Gebruik inline delegaten
U kunt ook de Action<MicrosoftDataSqlClientSettings> configureSettings gedelegeerde doorgeven om enkele of alle opties direct in te stellen, bijvoorbeeld om gezondheidscontroles vanuit de code uit te schakelen.
builder.AddSqlServerClient(
"database",
static settings => settings.DisableHealthChecks = true);
gezondheidscontroles voor integratie Client
Standaard kunnen .NET.NET Aspire integraties statuscontroles voor alle services inschakelen. Zie .NET.NET Aspire overzicht van integratiesvoor meer informatie.
De .NET AspireSQL Server-integratie:
- De gezondheidscontrole wordt toegevoegd wanneer MicrosoftDataSqlClientSettings.DisableHealthChecks
falseis, wat probeert verbinding te maken met de SQL Server. - Integreert met het
/healthHTTP-eindpunt, waarmee alle geregistreerde gezondheidscontroles moeten slagen zodat de app als gereed wordt beschouwd voor het accepteren van verkeer.
Waarneembaarheid en telemetrie
.NET .NET Aspire integraties automatisch configuraties voor logboekregistratie, tracering en metrische gegevens instellen, die ook wel bekend staan als de pijlers van waarneembaarheid. Zie .NET.NET Aspire overzicht van integratieintegratiesvoor meer informatie over de waarneembaarheid en telemetrie van integraties. Afhankelijk van de back-upservice ondersteunen sommige integraties mogelijk slechts enkele van deze functies. Sommige integraties ondersteunen bijvoorbeeld logboekregistratie en tracering, maar geen metrische gegevens. Telemetriefuncties kunnen ook worden uitgeschakeld met behulp van de technieken die worden weergegeven in de sectie Configuratie.
Loggen
De integratie van .NET AspireSQL Server schakelt logboekregistratie momenteel niet standaard in vanwege beperkingen van de Microsoft.Data.SqlClient.
Opsporing
De .NET AspireSQL Server-integratie verzendt de volgende traceringsactiviteiten met behulp van OpenTelemetry:
OpenTelemetry.Instrumentation.SqlClient
Statistieken
De integratie van .NET AspireSQL Server verzendt de volgende metrische gegevens met behulp van OpenTelemetry:
- Microsoft.Data.SqlClient.EventSource
active-hard-connectionshard-connectshard-disconnectsactive-soft-connectssoft-connectssoft-disconnectsnumber-of-non-pooled-connectionsnumber-of-pooled-connectionsnumber-of-active-connection-pool-groupsnumber-of-inactive-connection-pool-groupsnumber-of-active-connection-poolsnumber-of-inactive-connection-poolsnumber-of-active-connectionsnumber-of-free-connectionsnumber-of-stasis-connectionsnumber-of-reclaimed-connections
Zie ook
Met ons samenwerken op GitHub
De bron voor deze inhoud vindt u op GitHub, waar u ook problemen en pull-aanvragen kunt maken en controleren. Bekijk onze gids voor inzenders voor meer informatie.
