Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Enthält:
Hosting-Integration —&— Client Integration
SQL Server ist ein relationales Datenbankverwaltungssystem, das von Microsoft entwickelt wurde. Mit der .NET AspireSQL ServerEntity Framework Core Integration können Sie eine Verbindung mit vorhandenen SQL Server Instanzen herstellen oder neue Instanzen aus .NET dem mcr.microsoft.com/mssql/server Containerimage erstellen.
Integration von Hosting
Die SQL Server Hostintegration modelliert den Server als SqlServerServerResource Typ und die Datenbank als SqlServerDatabaseResource Typ. Um auf diese Typen und APIs zuzugreifen, fügen Sie das NuGet-Paket 📦Aspire.Hosting.SqlServer im App-Host--Projekt hinzu.
dotnet add package Aspire.Hosting.SqlServer
Weitere Informationen finden Sie unter dotnet add package oder unter Paketabhängigkeiten in .NET-Anwendungen verwalten.
Füge eine SQL Server Ressource und eine Datenbankressource hinzu
Rufen Sie in Ihrem App-Hostprojekt AddSqlServer auf, um einen SQL Server Ressourcen-Generator hinzuzufügen und zurückzugeben. Verketten Sie einen Aufruf des zurückgegebenen Ressourcen-Builders mit AddDatabase, um die SQL Server Datenbankressource hinzuzufügen.
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();
Hinweis
Es dauert lange, bis der SQL Server-Container startet. Daher ist es am besten, eine dauerhafte-Lebensdauer zu verwenden, um unnötige Neustarts zu vermeiden. Weitere Informationen finden Sie unter Lebensdauer von Containerressourcen.
Wenn .NET.NET Aspire dem App-Host ein Containerimage hinzufügt, wie im vorherigen Beispiel mit dem mcr.microsoft.com/mssql/server-Image gezeigt, wird eine neue SQL Server Instanz auf dem lokalen Computer erstellt. Ein Verweis auf den SQL Server Ressourcen-Generator (die sql Variable) wird verwendet, um eine Datenbank hinzuzufügen. Die Datenbank wird als database benannt und dann zu ExampleProjecthinzugefügt.
Wenn Sie dem App-Modell eine Datenbankressource hinzufügen, wird die Datenbank erstellt, sofern sie noch nicht vorhanden ist. Die Erstellung der Datenbank basiert insbesondere auf den App-Hostereignis-APIs.ResourceReadyEvent Anders ausgedrückt: Wenn die sql Ressource bereit ist, wird das Ereignis ausgelöst, und die Datenbankressource wird erstellt.
Die Ressource SQL Server enthält Standardanmeldeinformationen mit einem username von sa und einem zufällig generierten password, der mithilfe der CreateDefaultPasswordParameter-Methode erstellt wurde.
Wenn der App-Host ausgeführt wird, wird das Kennwort in der geheimen Ablage des App-Hosts gespeichert. Sie wird dem Abschnitt Parameters hinzugefügt, z. B.:
{
"Parameters:sql-password": "<THE_GENERATED_PASSWORD>"
}
Der Name des Parameters ist sql-password, aber eigentlich wird der Ressourcenname nur mit dem Suffix -password formatiert. Weitere Informationen finden Sie unter sichere Speicherung von App-Geheimnissen in der Entwicklung in ASP.NET Core und Hinzufügen einer Ressource mit ParameternSQL Server.
Die WithReference-Methode konfiguriert eine Verbindung im ExampleProject namens database.
Tipp
Wenn Sie lieber eine Verbindung mit einer vorhandenen SQL Serverherstellen möchten, rufen Sie stattdessen AddConnectionString an. Weitere Informationen finden Sie unter Referenzieren vorhandener Ressourcen.
Hinzufügen einer SQL Server Ressource mit Datenbankskripts
Wenn Sie ein SqlServerDatabaseResourceObjekt hinzufügen, basiert es standardmäßig auf dem folgenden SQL-Skript, um die Datenbank zu erstellen:
IF
(
NOT EXISTS
(
SELECT 1
FROM sys.databases
WHERE name = @DatabaseName
)
)
CREATE DATABASE [<QUOTED_DATABASE_NAME>];
Um das Standardskript zu ändern, verketten Sie einen Aufruf der WithCreationScript Methode im Datenbankressourcen-Generator:
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();
Im vorherigen Beispiel wird eine Datenbank namens app_db mit einer einzelnen todos-Tabelle erstellt. Das SQL-Skript wird ausgeführt, wenn die Datenbankressource erstellt wird. Das Skript wird als Zeichenfolge an die WithCreationScript Methode übergeben, die dann im Kontext der SQL Server Ressource ausgeführt wird.
SQL Server Ressource mit Datenvolumen hinzufügen
Rufen Sie die SQL Server-Methode für die WithDataVolume-Ressource auf, um der SQL Server-Ressource ein Datenvolume hinzuzufügen:
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();
Das Datenvolumen wird verwendet, um die SQL Server-Daten außerhalb des Lebenszyklus des Containers zu speichern. Das Datenvolumen wird am Pfad /var/opt/mssql im Container SQL Server bereitgestellt, und wenn kein Parameter name angegeben wird, wird der Name zufällig generiert. Weitere Informationen zu Datenvolumes und Details dazu, warum sie gegenüber Bind-Mountsbevorzugt werden, finden Sie in der Docker-Dokumentation: Datenvolumes.
Warnung
Das Kennwort wird im Datenvolume gespeichert. Wenn Sie ein Datenvolumen verwenden und sich das Kennwort ändert, funktioniert es nicht, bis Sie das Volumen löschen.
Ressource SQL Server mit Datenbind-Einbindung hinzufügen
Rufen Sie die SQL Server-Methode auf, um der WithDataBindMount-Ressource ein Datenbindungs-Mount hinzuzufügen.
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();
Wichtig
Daten-Bind-Mounts haben im Vergleich zu Volumes eine eingeschränkte Funktionalität. Volumes bieten bessere Leistung, Portabilität und Sicherheit, wodurch sie besser für Produktionsumgebungen geeignet sind. Bind-Mounts ermöglichen jedoch den direkten Zugriff und die Änderung von Dateien auf dem Host-System, ideal für Entwicklung und Tests, bei denen eine Echtzeitänderung erforderlich ist.
Data Bind Mounts basieren auf dem Dateisystem des Hostcomputers, um die SQL Server Daten über Containerneustarts hinweg zu persistieren. Die Datenbindemontage wird unter Windows am Pfad C:\SqlServer\Data (oder am Pfad /SqlServer/Data auf Unix) auf dem Hostcomputer im Container SQL Server montiert. Weitere Informationen zu Bind-Mounts für Daten finden Sie in der Docker Dokumentation: Bind-Mounts.
Ressource SQL Server mit Parametern hinzufügen
Wenn Sie das vom Container-Image verwendete Kennwort explizit angeben möchten, können Sie die Zugangsdaten als Parameter übergeben. Betrachten Sie das folgende alternative Beispiel:
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();
Weitere Informationen zum Bereitstellen von Parametern finden Sie unter externe Parameter.
Verbindung zu Datenbankressourcen herstellen
Wenn der .NET.NET Aspire-App-Host ausgeführt wird, können auf die Datenbankressourcen des Servers über externe Tools zugegriffen werden, z. B. SQL Server Management Studio (SSMS) oder MSSQL für Visual Studio Code. Die Verbindungszeichenfolge für die Datenbankressource ist in den Umgebungsvariablen der abhängigen Ressourcen verfügbar und wird über das .NET.NET Aspire Dashboard aufgerufen: Ressourcendetails Fenster. Die Umgebungsvariable wird ConnectionStrings__{name} benannt, wobei {name} der Name der Datenbankressource ist, in diesem Beispiel ist sie database. Verwenden Sie die Verbindungszeichenfolge, um aus externen Tools auf die Datenbankressource zuzugreifen. Stellen Sie sich vor, Sie haben eine Datenbank mit dem Namen todos mit einer einzelnen dbo.Todos Tabelle.
Führen Sie die folgenden Schritte aus, um eine Verbindung mit der Datenbankressource aus SQL Server Management Studio herzustellen:
Öffnen Sie SSMS.
Wählen Sie im Dialogfeld Verbinden mit Server die Registerkarte Zusätzliche Verbindungsparameter aus.
Fügen Sie die Verbindungszeichenfolge in das Feld Zusätzliche Verbindungsparameter ein und wählen Sie Verbindenaus.
Wenn Sie verbunden sind, können Sie die Datenbankressource im Objekt-Explorersehen:
Weitere Informationen finden Sie unter SQL Server Management Studio: Herstellen einer Verbindung mit einem Server.
Durchführung von Integrationsgesundheitsprüfungen
Die SQL Server Hosting-Integration fügt automatisch eine Gesundheitsprüfung für die SQL Server Ressource hinzu. Die Gesundheitsprüfung stellt sicher, dass die SQL Server läuft und eine Verbindung dazu hergestellt werden kann.
Die Hostingintegration basiert auf dem 📦 AspNetCore.HealthChecks.SqlServer NuGet-Paket.
Client Anbindung
Um mit der .NET AspireSQL ServerEntity Framework Core Integration zu beginnen, installieren Sie die 📦Aspire. Microsoft.EntityFrameworkCore.SqlServer NuGet-Paket im clientverwendenden Projekt, d. h. das Projekt für die Anwendung, die den SQL ServerEntity Framework Core Client verwendet.
dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer
Weitere Informationen finden Sie unter dotnet add package oder unter Paketabhängigkeiten in .NET-Anwendungen verwalten.
Hinzufügen des SQL Server Datenbankkontexts
Rufen Sie in der Program.cs-Datei Ihres Projekts, das einen Client verwendet, die AddSqlServerDbContext-Erweiterungsmethode für jedes IHostApplicationBuilder auf, um eine DbContext für die Verwendung über den Dependency-Injection-Container zu registrieren. Die Methode verwendet einen Verbindungsnamenparameter.
builder.AddSqlServerDbContext<ExampleDbContext>(connectionName: "database");
Tipp
Der parameter connectionName muss mit dem Namen übereinstimmen, der beim Hinzufügen der SQL Server-Datenbankressource im App-Hostprojekt verwendet wird. Anders ausgedrückt: Wenn Sie AddDatabase aufrufen und einen Namen von database angeben, soll derselbe Name beim Aufrufen von AddSqlServerDbContextverwendet werden. Weitere Informationen finden Sie unter Add SQL Server Ressource und Datenbankressource.
So rufen Sie ExampleDbContext Objekt aus einem Dienst ab:
public class ExampleService(ExampleDbContext context)
{
// Use context...
}
Weitere Informationen zur Abhängigkeitsinjektion finden Sie unter .NET Abhängigkeitsinjektion.
Anreichern eines SQL Server Datenbankkontexts
Möglicherweise möchten Sie die standardmäßige Entity Framework-Methode verwenden, um einen Datenbankkontext abzurufen und ihn dem Abhängigkeitsinjektionscontainer hinzuzufügen.
builder.Services.AddDbContext<ExampleDbContext>(options =>
options.UseSqlServer(builder.Configuration.GetConnectionString("database")
?? throw new InvalidOperationException("Connection string 'database' not found.")));
Hinweis
Der Name der Verbindungszeichenfolge, den Sie an die GetConnectionString Methode übergeben, muss mit dem Namen übereinstimmen, der beim Hinzufügen der SQL Server-Ressource im App-Hostprojekt verwendet wird. Weitere Informationen finden Sie unter Add SQL Server Ressource und Datenbankressource.
Sie haben mehr Flexibilität, wenn Sie den Datenbankkontext auf diese Weise erstellen, z. B.:
- Sie können vorhandenen Konfigurationscode für den Datenbankkontext wiederverwenden, ohne ihn für .NET.NET Aspireneu zu schreiben.
- Sie können Entity Framework Core Interceptors verwenden, um Datenbankvorgänge zu ändern.
- Sie können sich entscheiden, Entity Framework Core Kontextpooling nicht zu verwenden, was unter bestimmten Umständen besser funktioniert.
Wenn Sie diese Methode verwenden, können Sie den Datenbankkontext mit .NET.NET Aspire-style-Wiederholungen, Integritätsüberprüfungen, Protokollierungs- und Telemetriefunktionen verbessern, indem Sie die EnrichSqlServerDbContext-Methode aufrufen:
builder.EnrichSqlServerDbContext<ExampleDbContext>(
configureSettings: settings =>
{
settings.DisableRetry = false;
settings.CommandTimeout = 30; // seconds
});
Der settings-Parameter ist eine Instanz der MicrosoftEntityFrameworkCoreSqlServerSettings Klasse.
Konfiguration
Die .NET AspireSQL ServerEntity Framework Core Integration bietet mehrere Konfigurationsmethoden und -optionen, um die Anforderungen und Konventionen Ihres Projekts zu erfüllen.
Verbindungstring verwenden
Wenn Sie eine Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings verwenden, geben Sie beim Aufrufen von builder.AddSqlServerDbContext<TContext>()den Namen der Verbindungszeichenfolge an:
builder.AddSqlServerDbContext<ExampleDbContext>("sql");
Die Verbindungszeichenfolge wird aus dem Konfigurationsabschnitt ConnectionStrings abgerufen.
{
"ConnectionStrings": {
"sql": "Data Source=myserver;Initial Catalog=master"
}
}
Der EnrichSqlServerDbContext wird den ConnectionStrings Konfigurationsabschnitt nicht verwenden, da erwartet wird, dass zum Zeitpunkt des Aufrufs ein DbContext registriert wird.
Weitere Informationen finden Sie in der ConnectionString.
Verwendung von Konfigurationsanbietern
Die .NET AspireSQL ServerEntity Framework Core-Integration unterstützt Microsoft.Extensions.Configuration. Sie lädt die MicrosoftEntityFrameworkCoreSqlServerSettings aus Konfigurationsdateien wie appsettings.json mithilfe des Aspire:Microsoft:EntityFrameworkCore:SqlServer-Schlüssels. Wenn Sie Ihre Konfigurationen im Abschnitt Aspire:Microsoft:EntityFrameworkCore:SqlServer eingerichtet haben, können Sie die Methode einfach aufrufen, ohne Parameter zu übergeben.
Im Folgenden finden Sie ein Beispiel für eine appsettings.json Datei, die einige der verfügbaren Optionen konfiguriert:
{
"Aspire": {
"Microsoft": {
"EntityFrameworkCore": {
"SqlServer": {
"ConnectionString": "YOUR_CONNECTIONSTRING",
"DbContextPooling": true,
"DisableHealthChecks": true,
"DisableTracing": true,
"DisableMetrics": false
}
}
}
}
}
Verwenden Sie Inlinekonfigurationen
Sie können den Action<MicrosoftEntityFrameworkCoreSqlServerSettings> Delegat auch übergeben, um einige oder alle Optionen direkt einzurichten, z. B. um die Metriken zu deaktivieren:
builder.AddSqlServerDbContext<YourDbContext>(
"sql",
static settings =>
settings.DisableMetrics = true);
Konfigurieren mehrerer DbContext-Verbindungen
Wenn Sie mehrere DbContext mit unterschiedlicher Konfiguration registrieren möchten, können Sie den Namen des $"Aspire.Microsoft.EntityFrameworkCore.SqlServer:{typeof(TContext).Name}"-Konfigurationsabschnitts verwenden. Die JSON-Konfiguration würde wie folgt aussehen:
{
"Aspire": {
"Microsoft": {
"EntityFrameworkCore": {
"SqlServer": {
"ConnectionString": "YOUR_CONNECTIONSTRING",
"DbContextPooling": true,
"DisableHealthChecks": true,
"DisableTracing": true,
"DisableMetrics": false,
"AnotherDbContext": {
"ConnectionString": "AnotherDbContext_CONNECTIONSTRING",
"DisableTracing": false
}
}
}
}
}
}
Anschließend würde das Aufrufen der AddSqlServerDbContext-Methode mit dem AnotherDbContext-Typ-Parameter die Einstellungen aus dem Aspire:Microsoft:EntityFrameworkCore:SqlServer:AnotherDbContext-Abschnitt laden.
builder.AddSqlServerDbContext<AnotherDbContext>("another-sql");
Konfigurationsoptionen
Hier sind die konfigurierbaren Optionen mit entsprechenden Standardwerten:
| Name | BESCHREIBUNG |
|---|---|
ConnectionString |
Die Verbindungszeichenfolge der SQL Server Datenbank, mit der eine Verbindung hergestellt werden soll. |
DbContextPooling |
Ein boolescher Wert, der angibt, ob der Db-Kontext jedes Mal, wenn er angefordert wird, pooliert oder explizit erstellt wird |
MaxRetryCount |
Die maximale Anzahl von Wiederholungsversuchen. Der Standardwert ist 6, legen Sie ihn auf 0 fest, um den Wiederholungsmechanismus zu deaktivieren. |
DisableHealthChecks |
Ein boolescher Wert, der angibt, ob die Datenbankintegritätsprüfung deaktiviert ist oder nicht. |
DisableTracing |
Ein boolescher Wert, der angibt, ob die OpenTelemetry Nachverfolgung deaktiviert ist. |
DisableMetrics |
Ein boolescher Wert, der angibt, ob die OpenTelemetry Metriken deaktiviert sind oder nicht. |
Timeout |
Die Zeit in Sekunden, bis der Befehl ausgeführt wird. |
Client Integrationsgesundheitsprüfungen
Standardmäßig sind bei .NET.NET AspireClient-IntegrationenGesundheitsprüfungen für alle Dienste aktiviert. Ebenso stellen viele .NET.NET AspireHostingintegrationen auch Gesundheitsprüfungsendpunkte bereit. Weitere Informationen finden Sie unter:
Standardmäßig behandelt die .NET Aspire Sql-Integration ServerEntity Framework Core Folgendes:
- Fügt
DbContextHealthCheckhinzu, die die EF Core-Methode von CanConnectAsyncaufruft. Der Name des Gesundheitschecks ist der Name desTContextTyps. - Integriert mit dem
/healthHTTP-Endpunkt, der angibt, dass alle registrierten Integritätsprüfungen bestanden werden müssen, damit die Anwendung als bereit zur Annahme von Datenverkehr gilt.
Beobachtbarkeit und Telemetrie
.NET .NET Aspire Integrationen richten automatisch Protokollierungs-, Nachverfolgungs- und Metrikkonfigurationen ein, die manchmal als die Säulen der Observierbarkeitbezeichnet werden. Weitere Informationen zur Integrations-Observability und Telemetrie finden Sie in der .NET.NET Aspire Integrationsübersicht. Abhängig vom Backend-Service unterstützen einige Integrationen möglicherweise nur einige dieser Funktionen. Beispielsweise unterstützen einige Integrationen Protokollierung und Ablaufverfolgung, aber keine Metriken. Telemetrie-Funktionen können auch mithilfe der Techniken deaktiviert werden, die im Abschnitt Konfiguration beschrieben sind.
Protokollierung
Die .NET AspireSQL ServerEntity Framework Core Integration verwendet die folgenden Protokollkategorien:
Microsoft.EntityFrameworkCore.ChangeTrackingMicrosoft.EntityFrameworkCore.Database.CommandMicrosoft.EntityFrameworkCore.Database.ConnectionMicrosoft.EntityFrameworkCore.Database.TransactionMicrosoft.EntityFrameworkCore.InfrastructureMicrosoft.EntityFrameworkCore.MigrationsMicrosoft.EntityFrameworkCore.ModelMicrosoft.EntityFrameworkCore.Model.ValidationMicrosoft.EntityFrameworkCore.QueryMicrosoft.EntityFrameworkCore.Update
Nachverfolgung
Die .NET AspireSQL ServerEntity Framework Core Integration wird die folgenden Ablaufverfolgungen mithilfe von OpenTelemetryausgeben:
- "OpenTelemetry. Instrumentation.EntityFrameworkCore"
Metriken
Die .NET AspireSQL ServerEntity Framework Core Integration gibt die folgenden Metriken mithilfe von OpenTelemetryaus:
- Microsoft.EntityFrameworkCore:
ec_Microsoft_EntityFrameworkCore_active_db_contextsec_Microsoft_EntityFrameworkCore_total_queriesec_Microsoft_EntityFrameworkCore_queries_per_secondec_Microsoft_EntityFrameworkCore_total_save_changesec_Microsoft_EntityFrameworkCore_save_changes_per_secondec_Microsoft_EntityFrameworkCore_compiled_query_cache_hit_rateec_Microsoft_Entity_total_execution_strategy_operation_failuresec_Microsoft_E_execution_strategy_operation_failures_per_secondec_Microsoft_EntityFramew_total_optimistic_concurrency_failuresec_Microsoft_EntityF_optimistic_concurrency_failures_per_second
Siehe auch
Zusammenarbeit auf GitHub
Die Quelle für diesen Inhalt finden Sie auf GitHub, wo Sie auch Issues und Pull Requests erstellen und überprüfen können. Weitere Informationen finden Sie in unserem Leitfaden für Mitwirkende.
