.NET Aspire SQL Server integráció

Tartalmazza:hosting integráció és Client integráció

SQL Server a Microsoft által kifejlesztett relációsadatbázis-kezelő rendszer. A .NET AspireSQL Server integráció lehetővé teszi, hogy meglévő SQL Server példányokhoz csatlakozzon, vagy új példányokat hozzon létre a .NET-ból, a mcr.microsoft.com/mssql/server konténerképsegítségével.

Üzemeltetési integráció

Az integrációs SQL Server a kiszolgálót SqlServerServerResource típusként, az adatbázist pedig SqlServerDatabaseResource típusként modellozza. Az ilyen típusok és API-k eléréséhez adja hozzá a 📦Aspire.Hosting.SqlServer NuGet csomagot az alkalmazásgazda projektjébe.

dotnet add package Aspire.Hosting.SqlServer

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

További információ: dotnet add package vagy Csomagfüggőségek kezelése a .NET alkalmazásokban.

SQL Server erőforrás és adatbázis-erőforrás hozzáadása

Az alkalmazásgazda projektjében hívja meg a AddSqlServer-t egy SQL Server erőforrás-építő hozzáadására és visszaküldésére. A visszaadott erőforrás-építőhöz fűzze hozzá a hívást, hogy a AddDatabase adatbázis-erőforrást hozzáadja a SQL Server-hoz.

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

Amikor .NET.NET Aspire egy konténer képfájlt ad hozzá az alkalmazás gazdagépéhez, ahogyan az az előző példában az mcr.microsoft.com/mssql/server képfájlnál is látható, egy új SQL Server példányt hoz létre a helyi gépeden. A SQL Server erőforrás-készítőre (a sql változóra) mutató hivatkozással adatbázist adhat hozzá. Az adatbázis neve database, majd hozzáadják a ExampleProject-hez. Az SQL Server erőforrás alapértelmezett hitelesítő adatokat tartalmaz, usernamesa és véletlenszerű password generálva a CreateDefaultPasswordParameter metódus használatával.

Az alkalmazásgazda futtatásakor a jelszó az alkalmazásgazda titkos tárolójában lesz tárolva. A Parameters szakaszhoz lesz hozzáadva, például:

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

A paraméter neve sql-password, de valójában csak -password utótaggal formázhatja az erőforrás nevét. További információkért lásd: Az alkalmazás titkainak biztonságos tárolása fejlesztés közben ASP.NET Core,, és . Erőforrás hozzáadása paraméterekkel: SQL Server.

A WithReference metódus konfigurál egy kapcsolatot a ExampleProject-ben, amelynek neve database.

SQL Server erőforrás hozzáadása adatmennyiséggel

Ha adatkötetet szeretne hozzáadni az SQL Server erőforráshoz, hívja meg a WithDataVolume erőforrás SQL Server metódusát:

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

Az adatkötet a tároló életciklusán kívüli SQL Server adatok megőrzésére szolgál. Az adatkötet a /var/opt/mssql tároló SQL Server elérési útjára van csatlakoztatva, és ha nincs megadva name paraméter, a rendszer véletlenszerűen hozza létre a nevet. További információ az adatmennyiségekről és arról, hogy miért előnyben részesítik őket a függesztésekkel szemben, lásd a(z) Docker dokumentumokat: Kötetek.

SQL Server erőforrás hozzáadása adatkötés csatolásával

Ha adatkötési csatlakoztatást szeretne hozzáadni az SQL Server erőforráshoz, hívja meg a WithDataBindMount metódust:

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

Az adatkötési csatlakoztatások a gazdagép fájlrendszerére támaszkodnak, hogy a tároló újraindítása során megőrizze a SQL Server adatokat. Az adatkötés csatlakoztatása a windowsos C:\SqlServer\Data (vagy /SqlServer/DataUnix) útvonalon van csatlakoztatva a SQL Server tároló gazdagépén. Az adatkötési csatlakoztatásokkal kapcsolatos további információkért lásd Docker dokumentumokat: Kötési csatlakoztatások.

SQL Server erőforrás hozzáadása paraméterekkel

Ha explicit módon meg szeretné adni a tárolólemezkép által használt jelszót, paraméterekként megadhatja ezeket a hitelesítő adatokat. Tekintse meg a következő alternatív példát:

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

További információ a paraméterek megadásáról: Külső paraméterek.

Csatlakozás adatbázis-erőforrásokhoz

A .NET.NET Aspire alkalmazásgazda futtatásakor a kiszolgáló adatbázis-erőforrásai külső eszközökről érhetők el, például SQL Server Management Studio (SSMS) vagy MSSQL Visual Studio Code. Az adatbázis-erőforrás kapcsolati lánca a függő erőforrások környezeti változói között található, és a .NET.NET Aspire irányítópult Erőforrás-részletek paneljén érhető el. A környezeti változó neve ConnectionStrings__{name}, ahol a {name} az adatbázis-erőforrás neve, ebben a példában ez database. A kapcsolati sztring használatával külső eszközökről csatlakozhat az adatbázis-erőforráshoz. Tegyük fel, hogy egyetlen todos táblával rendelkező dbo.Todos nevű adatbázissal rendelkezik.

Integrációs állapotellenőrzések üzemeltetése

A SQL Server üzemeltetési integráció automatikusan hozzáad egy állapotellenőrzést a SQL Server erőforráshoz. Az állapotellenőrzés ellenőrzi, hogy a SQL Server fut-e, és hogy létre lehet-e hozni vele kapcsolatot.

Az üzemeltetési integráció az AspNetCore.HealthChecks.SqlServer NuGet-csomag támaszkodik.

Client integráció

Az .NET AspireSQL Server ügyfélintegráció első lépéseihez telepítse a 📦AspireMicrosoft.Data.SqlClient NuGet-csomagot az ügyfelet használó projektben, vagyis a SQL Server ügyfelet használó alkalmazás projektjében. A SQL Server ügyfélintegráció regisztrál egy SqlConnection példányt, amelyet felhasználhat a SQL Server-val való interakcióra.

dotnet add package Aspire.Microsoft.Data.SqlClient

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

SQL Server-ügyfél hozzáadása

Az ügyfél által használt projekt Program.cs fájljában hívja meg a AddSqlServerClient bővítménymetódusát bármelyik IHostApplicationBuilder esetében, hogy regisztráljon egy SqlConnection-at a függőség-injektáló tárolón keresztül való használatra. A metódus egy kapcsolatnévparamétert használ.

builder.AddSqlServerClient(connectionName: "database");

Ezután függőséginjektálással lekérheti a SqlConnection-példányt. Ha például egy példaszolgáltatásból szeretné lekérni a kapcsolatot:

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

További információ a függőséginjektálásról: .NET függőséginjektálás.

Adja hozzá azonosított SQL Server-ügyfelet

Előfordulhatnak olyan helyzetek, amikor több SqlConnection példányt szeretne regisztrálni különböző kapcsolatnevekkel. A kulcsos SQL Server ügyfelek regisztrálásához hívja meg a AddKeyedSqlServerClient metódust:

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

Ezután függőséginjektálással lekérheti a SqlConnection példányokat. Ha például egy példaszolgáltatásból szeretné lekérni a kapcsolatot:

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

További információ a kulcsos szolgáltatásokról: .NET függőséginjektálás: Kulcsos szolgáltatások.

Konfiguráció

A .NET AspireSQL Server integráció több lehetőséget is kínál a kapcsolat konfigurálására a projekt követelményei és konvenciói alapján.

Kapcsolati lánc használata

Ha a ConnectionStrings konfigurációs szakaszból használ kapcsolati sztringet, megadhatja a kapcsolati sztring nevét a AddSqlServerClient metódus meghívásakor:

builder.AddSqlServerClient(connectionName: "sql");

Ezután a kapcsolati sztring lekérése történik a ConnectionStrings konfigurációs szakaszból.

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

A kapcsolati sztring formázásáról további információt a ConnectionStringcímű témakörben talál.

Konfigurációs szolgáltatók használata

A .NET AspireSQL Server integráció támogatja a Microsoft.Extensions.Configuration. A MicrosoftDataSqlClientSettings-t a konfigurációból a Aspire:Microsoft:Data:SqlClient kulcs használatával tölti be. Az alábbi kódrészlet egy példa egy appsettings.json fájlra, amely konfigurál néhány beállítást:

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

A teljes SQL Server ügyfél-integrációs JSON sémát lásd: Aspire. Microsoft.Data.SqlClient/ConfigurationSchema.json.

Beágyazott delegálók használata

A Action<MicrosoftDataSqlClientSettings> configureSettings delegáltat is átadhatja, hogy néhány vagy az összes beállítást közvetlenül konfigurálja, például letilthatja az állapotellenőrzéseket a kódból.

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

Client integrációs állapot felmérés

Alapértelmezés szerint az .NET.NET Aspire integrációk lehetővé teszik állapotellenőrzéseket az összes szolgáltatás esetében. További információ: .NET.NET Aspire integrációk áttekintése.

A .NET AspireSQL Server integrációja:

• Hozzáadja az állapot-ellenőrzést, ha MicrosoftDataSqlClientSettings.DisableHealthChecksfalse, és csatlakozik a SQL Server-höz.
• Integrálható a /health HTTP-végponttal, amely meghatározza, hogy az összes regisztrált állapot-ellenőrzésnek át kell mennie ahhoz, hogy az alkalmazás készen álljon a forgalom elfogadására.

Megfigyelhetőség és telemetria

.NET .NET Aspire integrációk automatikusan beállítják a naplózási, nyomkövetési és metrikakonfigurációkat, amelyeket más néven a megfigyelhetőség alappillérei. Az integráció megfigyelhetőségéről és telemetriáról további információt .NET.NET Aspire integrációk áttekintésében. A háttérszolgáltatástól függően egyes integrációk csak bizonyos funkciókat támogatnak. Egyes integrációk például támogatják a naplózást és a nyomkövetést, a metrikákat azonban nem. A telemetriai funkciók a Konfiguráció szakaszban ismertetett technikákkal is letilthatók.

Fakitermelés

A .NET AspireSQL Server integráció jelenleg nem engedélyezi alapértelmezés szerint a naplózást a Microsoft.Data.SqlClientkorlátozásai miatt.

Nyomkövetés

A .NET AspireSQL Server integráció a következő nyomkövetési tevékenységeket bocsátja ki a OpenTelemetryhasználatával:

• OpenTelemetry.Instrumentation.SqlClient

Metrikák

Az .NET AspireSQL Server integráció a következő metrikákat bocsátja ki a OpenTelemetryhasználatával:

• 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

Lásd még:

• Azure SQL Adatbázis
• SQL Server
• .NET .NET Aspire adatbázistárolók mintája
• .NET .NET Aspire integrációk
• .NET Aspire GitHub repo