.NET Aspire SQL Server integrering

Artikel
12/15/2024

omfattar:Hostingintegration och integreringClient

SQL Server är ett relationsdatabashanteringssystem som utvecklats av Microsoft. Med integreringen .NET AspireSQL Server kan du ansluta till befintliga SQL Server-instanser eller skapa nya instanser från .NET med mcr.microsoft.com/mssql/server containeravbildningen.

Integrering av värdtjänster

SQL Server som är värd för integrering modellerar server som SqlServerServerResource typ och databas som SqlServerDatabaseResource typ. Om du vill komma åt dessa typer och API:er lägger du till 📦Aspire.Hosting.SqlServer NuGet-paket i appvärdprojektet.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.SqlServer

<PackageReference Include="Aspire.Hosting.SqlServer"
                  Version="*" />

Mer information finns i dotnet add package eller Hantera paketberoenden i .NET applikationer.

Lägg till SQL Server resurs och databasresurs

I appvärdprojektet anropar du AddSqlServer för att lägga till och returnera en SQL Server resursbyggare. Länka ett anrop från den returnerade resursbyggaren till AddDatabaseför att lägga till SQL Server databasresurs.

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...

Not

Det går långsamt att starta den SQL Server containern, så det är bäst att använda en beständig livslängd för att undvika onödiga omstarter. Mer information finns i containerresursens livslängd.

När .NET.NET Aspire lägger till en containeravbildning i appvärden, som du ser i föregående exempel med mcr.microsoft.com/mssql/server avbildningen, skapar den en ny SQL Server instans på den lokala datorn. En referens till din SQL Server resursbyggare (variabeln sql) används för att lägga till en databas. Databasen heter database och läggs sedan till i ExampleProject. Den SQL Server resursen innehåller standardautentiseringsuppgifter med en username av sa och en slumpmässig password som genereras med hjälp av metoden CreateDefaultPasswordParameter.

När appvärden körs lagras lösenordet i appvärdens hemliga arkiv. Det läggs till i avsnittet Parameters, till exempel:

{
  "Parameters:sql-password": "<THE_GENERATED_PASSWORD>"
}

Namnet på parametern är sql-password, men egentligen är det bara att formatera resursnamnet med ett -password suffix. Mer information finns i Säker lagring av apphemligheter under utveckling i ASP.NET Core och Lägg till SQL Server resurs med parametrar.

Metoden WithReference konfigurerar en anslutning i ExampleProject med namnet database.

Tips

Om du hellre vill ansluta till en befintlig SQL Serveranropar du AddConnectionString i stället. Mer information finns i Referera till befintliga resurser.

Lägga till SQL Server resurs med datavolym

Om du vill lägga till en datavolym i resursen SQL Server anropar du metoden WithDataVolume på den SQL Server resursen:

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...

Datavolymen används för att bevara SQL Server data utanför containerns livscykel. Datavolymen monteras på sökvägen /var/opt/mssql i containern SQL Server och när en name parameter inte tillhandahålls genereras namnet slumpmässigt. Mer information om datavolymer och information om varför de föredras framför bindningsmonteringarfinns i Docker dokument: Volymer.

Varning

Lösenordet lagras i datavolymen. När du använder en datavolym och om lösenordet ändras fungerar det inte förrän du tar bort volymen.

Lägg till SQL Server resurs med databindningsmontering

Om du vill lägga till en databindningsknytpunkt till SQL Server-resursen, anropar du WithDataBindMount-metoden.

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...

Viktig

Data bindningsmonteringar har begränsade funktioner jämfört med volymer, vilket ger bättre prestanda, portabilitet och säkerhet, vilket gör dem mer lämpliga för produktionsmiljöer. Bindningsmonteringar tillåter dock direkt åtkomst och ändring av filer i värdsystemet, perfekt för utveckling och testning där realtidsändringar behövs.

Databindningar förlitar sig på värddatorns filsystem för att spara SQL Server-data vid omstarter av containrar. Databindningsmonteringen monteras på sökvägen C:\SqlServer\Data i Windows (eller /SqlServer/Data på Unix) på värddatorn i SQL Server-containern. Mer information om databindningsmonteringar finns i Docker dokument: Bind monteringar.

Lägga till SQL Server resurs med parametrar

När du uttryckligen vill ange lösenordet som används av containeravbildningen kan du ange dessa autentiseringsuppgifter som parametrar. Tänk dig följande alternativa exempel:

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...

Mer information om hur du tillhandahåller parametrar finns i Externa parametrar.

Ansluta till databasresurser

När .NET Aspire appserver körs kan du komma åt server:s databasresurser från externa verktyg, såsom SQL Server Management Studio (SSMS) eller Azure Data Studio. Anslutningssträngen för databasresursen finns tillgänglig i de beroende resursernas miljövariabler och nås via .NET.NET Aspire-instrumentpanelen: Resursdetaljer-rutan. Miljövariabeln heter ConnectionStrings__{name} där {name} är namnet på databasresursen. I det här exemplet är den database. Använd anslutningssträngen för att ansluta till databasresursen från externa verktyg. Anta att du har en databas med namnet todos med en enda dbo.Todos tabell.

SQL Server Management Studio
Azure Data Studio

Följ dessa steg för att ansluta till databasresursen från SQL Server Management Studio:

Öppna SSMS.
I dialogrutan Anslut till Server väljer du fliken Ytterligare anslutningsparametrar.
Klistra in anslutningssträngen i fältet Ytterligare anslutningsparametrar och välj Anslut.
Om du är ansluten kan du se databasresursen i Object Explorer:

Mer information finns i SQL Server Management Studio: Anslut till en server.

Utförande av integreringshälsokontroller

SQL Server värdintegrering lägger automatiskt till en hälsokontroll för den SQL Server resursen. Hälsokontrollen verifierar att SQL Server körs och att en anslutning kan upprättas till den.

NuGet-paketet 📦 AspNetCore.HealthChecks.SqlServer förlitar sig värdintegreringen på.

Client integrering

Kom igång med .NET AspireSQL Serverclient-integreringen genom att installera 📦Aspire. Microsoft.Data.SqlClient NuGet-paketet i det client-förbrukande projektet, d.v.s. projektet för programmet som använder SQL Serverclient. SQL Server client-integreringen registrerar en SqlConnection instans som du kan använda för att interagera med SQL Server.

.NET CLI
PackageReference

dotnet add package Aspire.Microsoft.Data.SqlClient

<PackageReference Include="Aspire.Microsoft.Data.SqlClient"
                  Version="*" />

Lägg till SQL Serverclient

I ditt client-förbrukande projekt ska du i den Program.cs filen anropa AddSqlServerClient-tilläggsmetoden på alla IHostApplicationBuilder för att registrera en SqlConnection för användning via beroendeinjektionscontainern. Metoden tar en parameter för anslutningsnamn.

builder.AddSqlServerClient(connectionName: "database");

Tips

Parametern connectionName måste matcha namnet som används när du lägger till SQL Server-databasresursen i appvärdprojektet. Med andra ord, när du anropar AddDatabase och anger ett namn på database ska samma namn användas när du anropar AddSqlServerClient. För mer information, se Lägg till resurs SQL Server och databasresurs.

Du kan sedan hämta SqlConnection-instansen med hjälp av beroendeinjektion. Om du till exempel vill hämta anslutningen från en exempeltjänst:

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

Mer information om beroendeinmatning finns i .NET beroendeinmatning.

Lägg till kodade SQL Serverclient

Det kan finnas situationer där du vill registrera flera SqlConnection instanser med olika anslutningsnamn. Om du vill registrera nyckelade SQL Server klienter anropar du metoden AddKeyedSqlServerClient:

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

Viktig

När du använder nyckelade tjänster förväntas din SQL Server resurs ha konfigurerat två namngivna databaser, en för mainDb och en för loggingDb.

Sedan kan du hämta SqlConnection-instanser med hjälp av beroendeinjektion. Om du till exempel vill hämta anslutningen från en exempeltjänst:

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

För mer information om nyckelade tjänster, se .NET beroendeinjicering: Nyckelade tjänster.

Konfiguration

Den .NET AspireSQL Server integreringen innehåller flera alternativ för att konfigurera anslutningen baserat på kraven och konventionerna i ditt projekt.

Använda en anslutningssträng

När du använder en anslutningssträng från ConnectionStrings-konfigurationsavsnittet kan du ange namnet på anslutningssträngen när du anropar metoden AddSqlServerClient:

builder.AddSqlServerClient(connectionName: "sql");

Sedan hämtas anslutningssträngen från ConnectionStrings-konfigurationsavsnittet:

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

Mer information om hur du formaterar anslutningssträngen finns i ConnectionString.

Använda konfigurationsprovidrar

.NET Aspire SQL Server-integreringen stöder Microsoft.Extensions.Configuration. Den läser in MicrosoftDataSqlClientSettings från konfigurationen med hjälp av Aspire:Microsoft:Data:SqlClient-nyckeln. Följande kodfragment är ett exempel på en appsettings.json fil som konfigurerar några av alternativen:

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

Det fullständiga SQL Serverclient integrationsschemat JSON finns i Aspire. Microsoft.Data.SqlClient/ConfigurationSchema.json.

Använda infogade ombud

Du kan också skicka delegering Action<MicrosoftDataSqlClientSettings> configureSettings för att konfigurera vissa eller alla alternativ inline, till exempel för att inaktivera hälsokontroller från kod.

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

Client hälsokontroller för integrering

Som standard aktiverar .NET.NET Aspire integreringar hälsokontroller för alla tjänster. Mer information finns i översikten över .NET.NET Aspire integreringar.

Integreringen .NET AspireSQL Server:

Lägger till hälsokontrollen när MicrosoftDataSqlClientSettings.DisableHealthChecks är false, vilken försöker ansluta till SQL Server.
Integrerar med /health HTTP-slutpunkt, som anger att alla registrerade hälsokontroller ska passera för att appen ska anses vara redo att acceptera trafik.

Observerbarhet och telemetri

.NET .NET Aspire integreringar konfigurerar automatiskt konfigurationer för loggning, spårning och mått, som ibland kallas grundpelarna för observerbarhet. Mer information om integreringsobservabilitet och telemetri finns i översikten över .NET.NET Aspire integreringar. Beroende på säkerhetskopieringstjänsten kanske vissa integreringar bara stöder vissa av dessa funktioner. Vissa integreringar stöder till exempel loggning och spårning, men inte mått. Telemetrifunktioner kan också inaktiveras med hjälp av de tekniker som visas i avsnittet Configuration.

Skogsavverkning

Den .NET AspireSQL Server integreringen aktiverar för närvarande inte loggning som standard på grund av begränsningar i Microsoft.Data.SqlClient.

Spårning

.NET Aspire SQL Server-integreringen genererar följande spårningsaktiviteter med hjälp av OpenTelemetry:

OpenTelemetry.Instrumentation.SqlClient

Mått

Integreringen .NET AspireSQL Server genererar följande mått med hjälp av 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

Dela via