Freigeben über

.NET Aspire SQL Server-Integration

  • Artikel

umfasst:Hosting-Integration und Client Integration

SQL Server ist ein relationales Datenbankverwaltungssystem, das von Microsoft entwickelt wurde. Mit der .NET AspireSQL Server-Integration können Sie eine Verbindung mit vorhandenen SQL Server Instanzen herstellen oder neue Instanzen aus .NET mit dem mcr.microsoft.com/mssql/server Containerimageerstellen.

Hosting-Integration

Das SQL Server Host-Integrationsmodell modelliert das server als den SqlServerServerResource-Typ und die Datenbank als den 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 Verwalten von Paketabhängigkeiten in .NET-Anwendungen.

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-Generators an AddDatabase, um 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>()
       .WithReference(db)
       .WaitFor(db);

// After adding all resources, run the app...

Anmerkung

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 database genannt und dann zu ExampleProjecthinzugefügt. Die SQL Server-Ressource enthält Standardanmeldeinformationen mit einem username von sa und einem zufälligen password, der mithilfe der CreateDefaultPasswordParameter-Methode generiert 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 tatsächlich wird der Ressourcenname lediglich durch ein -password Suffix formatiert. Weitere Informationen finden Sie unter sicheren Speicher von geheimen App-Schlüsseln in der Entwicklung in ASP.NET Core und Hinzufügen SQL Server Ressource mit Parametern.

Die WithReference-Methode konfiguriert eine Verbindung im ExampleProject namens database.

Trinkgeld

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.

Fügen Sie die SQL Server-Ressource mit Datenvolumen hinzu

Rufen Sie die WithDataVolume-Methode für die SQL Server-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.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

// After adding all resources, run the app...

Das Datenvolumen wird verwendet, um die SQL Server-Daten außerhalb des Lebenszyklus des Containers zu speichern. Das Datenvolumen wird am /var/opt/mssql Pfad im Container SQL Server bereitgestellt, und wenn kein name Parameter angegeben wird, wird der Name zufällig generiert. Weitere Informationen zu Datenvolumes und Details dazu, warum sie gegenüber Bind-Einbindungenbevorzugt werden, finden Sie unter Docker-Dokumentation: Volumes.

Warnung

Das Kennwort wird im Datenvolume gespeichert. Wenn Sie ein Datenvolume verwenden und sich das Kennwort ändert, funktioniert es erst dann wieder, wenn Sie das Volume löschen.

Fügen Sie die Ressource SQL Server mit einem Daten-Bindemount hinzu.

Rufen Sie die WithDataBindMount-Methode auf, um der SQL Server-Ressource ein Daten-Bind-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.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

// After adding all resources, run the app...

Wichtig

Bind-Mounts haben eingeschränkte Funktionalität im Vergleich zu Volumes, die eine bessere Leistung, Portabilität und Sicherheit bieten und sie dadurch für Produktionsumgebungen besser geeignet machen. Bind-Mounts ermöglichen jedoch direkten Zugriff und die Bearbeitung von Dateien auf dem Hostsystem, ideal für Entwicklungs- und Testzwecke, bei denen Änderungen in Echtzeit erforderlich sind.

Datenbindungs-Bereitstellungen basieren auf dem Dateisystem des Hostcomputers, um die SQL Server Daten über Containerneustarts hinweg beizubehalten. Die Datenbindungsbereitstellung wird auf dem C:\SqlServer\Data unter Windows (oder /SqlServer/Data auf Unix) Pfad auf dem Hostcomputer im container SQL Server bereitgestellt. Weitere Informationen zu Bind-Mounts finden Sie in der Docker Dokumentation: Bind-Mounts.

Fügen Sie die Ressource SQL Server mit Parametern hinzu

Wenn Sie das vom Containerimage verwendete Kennwort explizit angeben möchten, können Sie diese Anmeldeinformationen als Parameter angeben. 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.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

// After adding all resources, run the app...

Weitere Informationen zum Bereitstellen von Parametern finden Sie unter externe Parameter.

Verbindung zu Datenbankressourcen herstellen

Wenn der .NET Aspire App-Host ausgeführt wird, kann auf die Datenbankressourcen des serverüber externe Tools wie SQL Server Management Studio (SSMS) oder Azure Data Studiozugegriffen werden. 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:

  1. Öffnen Sie SSMS.

  2. Wählen Sie im Dialogfeld Verbinden mit Server die Registerkarte Zusätzliche Verbindungsparameter aus.

  3. Fügen Sie die Verbindungszeichenfolge in das Feld Zusätzliche Verbindungsparameter ein und wählen Sie Verbindenaus.

    SQL Server Management Studio: Verbindung zu Server Dialogfeld herstellen.

  4. Wenn Sie verbunden sind, können Sie die Datenbankressource im Objekt-Explorersehen:

    SQL Server Management Studio: Mit datenbank verbunden.

Weitere Informationen finden Sie unter SQL Server Management Studio: Herstellen einer Verbindung mit einem server.

Hosten von Integritätsprüfungen für Integration

Die SQL Server Hostingintegration fügt automatisch eine Integritätsprüfung für die SQL Server Ressource hinzu. Die Systemprüfung überprüft, ob die SQL Server ausgeführt wird und ob eine Verbindung hergestellt werden kann.

Die Hostingintegration basiert auf dem 📦 AspNetCore.HealthChecks.SqlServer NuGet-Paket.

Client Integration

Um mit der .NET AspireSQL Serverclient-Integration zu beginnen, installieren Sie die 📦Aspire. Microsoft.Data.SqlClient NuGet-Paket im projekt client-verbrauchend, d. h. das Projekt für die Anwendung, die die SQL Serverclientverwendet. Die SQL Serverclient-Integration registriert eine SqlConnection Instanz, die Sie für die Interaktion mit SQL Serververwenden können.

dotnet add package Aspire.Microsoft.Data.SqlClient

Hinzufügen von SQL Serverclient

Rufen Sie in der Datei Program.cs Ihres client-verbrauchenden Projekts die AddSqlServerClient-Erweiterungsmethode für ein beliebiges IHostApplicationBuilder auf, um eine SqlConnection für die Verwendung über den Abhängigkeitsinjektionscontainer zu registrieren. Die Methode verwendet einen Verbindungsnamenparameter.

builder.AddSqlServerClient(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, sollte derselbe Name verwendet werden, wenn Sie AddSqlServerClientaufrufen. Weitere Informationen finden Sie unter Add SQL Server Ressource und Datenbankressource.

Anschließend können Sie die SqlConnection Instanz mithilfe der Abhängigkeitseinfügung abrufen. So rufen Sie beispielsweise die Verbindung aus einem Beispieldienst ab:

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

Weitere Informationen zur Abhängigkeitsinjektion finden Sie unter .NET Abhängigkeitsinjektion.

Hinzufügen von Schlüssel SQL Serverclient

Es kann Situationen geben, in denen Sie mehrere SqlConnection Instanzen mit unterschiedlichen Verbindungsnamen registrieren möchten. Um SQL Server-Schlüssel-Clients zu registrieren, rufen Sie die AddKeyedSqlServerClient-Methode auf:

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

Wichtig

Bei der Verwendung von Schlüsseldiensten wird erwartet, dass Ihre SQL Server-Ressource zwei benannte Datenbanken konfiguriert hat, eine für die mainDb und eine für die loggingDb.

Anschließend können Sie die SqlConnection Instanzen mithilfe der Abhängigkeitseinfügung abrufen. So rufen Sie beispielsweise die Verbindung aus einem Beispieldienst ab:

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

Weitere Informationen zu schlüsselbasierten Diensten finden Sie unter .NET Abhängigkeitsinjektion: Keyed Services.

Konfiguration

Die .NET AspireSQL Server-Integration bietet mehrere Optionen zum Konfigurieren der Verbindung basierend auf den Anforderungen und Konventionen Ihres Projekts.

Verwenden Sie eine Verbindungszeichenfolge

Wenn Sie eine Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings verwenden, können Sie beim Aufrufen der AddSqlServerClient-Methode den Namen der Verbindungszeichenfolge angeben:

builder.AddSqlServerClient(connectionName: "sql");

Anschließend wird die Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings abgerufen.

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

Weitere Informationen zum Formatieren dieser Verbindungszeichenfolge finden Sie im ConnectionString-.

Verwenden Sie Konfigurationsanbieter

Die .NET AspireSQL Server-Integration unterstützt Microsoft.Extensions.Configuration. Sie lädt die MicrosoftDataSqlClientSettings mithilfe des Aspire:Microsoft:Data:SqlClient Schlüssels aus der Konfiguration. Der folgende Codeausschnitt ist ein Beispiel für eine appsettings.json Datei, die einige der Optionen konfiguriert:

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

Die vollständige SQL Serverclient Integration JSON Schemas finden Sie unter Aspire. Microsoft.Data.SqlClient/ConfigurationSchema.json.

Verwenden Sie Inline-Delegaten

Sie können auch den Action<MicrosoftDataSqlClientSettings> configureSettings Delegat übergeben, um einige oder alle Optionen inline einzurichten, z. B. um Gesundheitsprüfungen aus Code zu deaktivieren.

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

Client Integrations-Gesundheitsprüfungen

Standardmäßig aktivieren .NET.NET Aspire Integrationen Integritätsprüfungen für alle Dienste. Weitere Informationen finden Sie unter .NET.NET Aspire Integrationsübersicht.

Die .NET AspireSQL Server Integration:

  • Fügt die Gesundheitsprüfung hinzu, wenn MicrosoftDataSqlClientSettings.DisableHealthChecksfalseist, und versucht, eine Verbindung mit der SQL Serverherzustellen.
  • Integriert in den /health HTTP-Endpunkt, der angibt, dass alle registrierten Gesundheitsprüfungen bestehen müssen, damit die App als bereit für die Annahme des Datenverkehrs gilt.

Observability und Telemetrie

.NET .NET Aspire Integrationen richten automatisch Protokollierungs-, Ablaufverfolgungs- und Metrikkonfigurationen ein, die manchmal als die Säulen der Beobachtbarkeitbezeichnet werden. Weitere Informationen zur Integrations-Observability und Telemetrie finden Sie unter .NET.NET Aspire Übersicht über Integrationen. Je nach unterstützendem Dienst unterstützen einige Integrationen nur einige dieser Funktionen. Beispielsweise unterstützen einige Integrationen Protokollierung und Ablaufverfolgung, aber keine Metriken. Telemetrie-Features können auch mithilfe der Techniken deaktiviert werden, die im Abschnitt Konfiguration beschrieben werden.

Protokollierung

Die .NET AspireSQL Server-Integration aktiviert derzeit standardmäßig die Protokollierung nicht, aufgrund von Einschränkungen der Microsoft.Data.SqlClient.

Nachverfolgung

Die .NET AspireSQL Server-Integration gibt die folgenden Protokollierungsaktivitäten mithilfe von OpenTelemetryaus.

  • OpenTelemetry.Instrumentation.SqlClient

Messgrößen

Die .NET AspireSQL Server Integration gibt die folgenden Metriken mithilfe von OpenTelemetryaus:

  • 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

Siehe auch