Freigeben über

.NET Aspire SQL Server-Integration

Enthält:Hosting-Integration inbegriffen Hosting-Integration —&— Client Integration inbegriffenClient 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

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 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 an den zurückgegebenen Ressourcen-Builder 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();

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.

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 SQL Server-Ressource enthält Standardanmeldedaten mit einem username von sa und einem zufälligen password, das 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 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.

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

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 /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 SQL Server-Methode auf, um der WithDataBindMount-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.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

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.

Datenbindungseinbindungen stützen sich auf das Dateisystem des Hostrechners, um die SQL Server-Daten über Neustarts von Containern hinweg beizubehalten. 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 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.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:

  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.

Durchführung von Integritätsprüfungen für Integrationen

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 Server Clientintegration zu beginnen, installieren Sie das 📦Aspire.Microsoft.Data.SqlClient NuGet-Paket in dem Projekt, das den Client verwendet, also dem Projekt der Anwendung, welche den SQL Server Client nutzt. Die SQL Server Clientintegration registriert eine SqlConnection Instanz, die Sie für die Interaktion mit SQL Serververwenden können.

dotnet add package Aspire.Microsoft.Data.SqlClient

Füge SQL Server-Client hinzu

Rufen Sie in der Program.cs-Datei Ihres Projekts, das Client-Dienste konsumiert, die AddSqlServerClient-Erweiterungsmethode für jedes IHostApplicationBuilder auf, um eine SqlConnection für die Verwendung über den Dependency Injection-Container 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 des Clients mit Schlüssel SQL Server

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. Es lädt die MicrosoftDataSqlClientSettings aus der Konfiguration mithilfe des Aspire:Microsoft:Data:SqlClient Schlüssels. 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ändigen SQL Server Clientintegration-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 Gesundheitsprü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