integrace .NET AspireSQL Server

Článek
12/12/2024

zahrnuje:integrace hostování a Client integrace

SQL Server je systém pro správu relačních databází vyvinutý Microsoftem. Integrace .NET AspireSQL Server umožňuje připojit se k existujícím instancím SQL Server nebo vytvářet nové instance z .NET pomocí mcr.microsoft.com/mssql/server image kontejneru.

Integrace hostování

Hostování integrace SQL Server modeluje server jako typ SqlServerServerResource a databázi jako typ SqlServerDatabaseResource. Pokud chcete získat přístup k těmto typům a rozhraním API, přidejte 📦Aspire.Hosting.SqlServer balíček NuGet do projektu hostitele aplikace .

.NET rozhraní příkazového řádku
PackageReference

dotnet add package Aspire.Hosting.SqlServer

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

Další informace najdete v tématu dotnet add package nebo Spravujte závislosti balíčků v aplikacích .NET.

Přidání prostředku SQL Server a databázového prostředku

V projektu hostitele aplikace zavolejte AddSqlServer a přidejte a vraťte tvůrce prostředků SQL Server. Zřetězte volání pro vráceného tvůrce zdrojů na AddDatabasea přidejte databázový prostředek SQL Server.

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

Poznámka

Kontejner SQL Server se pomalu spustí, takže je nejlepší použít trvalou dobu života, abyste se vyhnuli zbytečným restartováním. Další informace najdete v tématu Životnost prostředků kontejneru.

Když .NET.NET Aspire přidá do hostitele aplikace image kontejneru, jak je znázorněno v předchozím příkladu s imagí mcr.microsoft.com/mssql/server, vytvoří na místním počítači novou instanci SQL Server. K přidání databáze se používá odkaz na návrháře zdrojů SQL Server (proměnná sql). Databáze se jmenuje database a pak se přidá do ExampleProject. Prostředek SQL Server obsahuje výchozí přihlašovací údaje, usernamesa a náhodný password vygenerovaný pomocí metody CreateDefaultPasswordParameter.

Když se hostitel aplikace spustí, heslo se uloží do úložiště tajných kódů hostitele aplikace. Přidá se do oddílu Parameters, například:

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

Název parametru je sql-password, ale ve skutečnosti pouze formátuje název prostředku s příponou -password. Další informace najdete v tématu Bezpečné ukládání tajných kódů aplikací při vývoji v ASP.NET Core a Přidání prostředku SQL Server s parametry.

Metoda WithReference nakonfiguruje připojení v ExampleProject s názvem database.

Spropitné

Pokud byste se raději připojili k existujícímu SQL Server, volejte místo toho AddConnectionString. Další informace naleznete v tématu Odkaz na existující prostředky.

Přidat SQL Server prostředek s objemem dat

Pokud chcete do prostředku SQL Server přidat datový svazek, zavolejte metodu WithDataVolume prostředku SQL Server:

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

Objem dat se používá k zachování SQL Server dat mimo životní cyklus kontejneru. Datový svazek se připojí k cestě /var/opt/mssql v kontejneru SQL Server a když není zadaný parametr name, název se náhodně vygeneruje. Další informace o datových svazcích a podrobnosti o tom, proč se upřednostňují před připojení vazby, najdete v dokumentaci Docker: Svazky.

Varování

Heslo je uloženo v datovém svazku. Pokud používáte datový svazek a heslo se změní, nebude to fungovat, dokud svazek neodstraníte.

Přidání prostředku SQL Server s připojením vazby dat

Chcete-li přidat vazbu dat k prostředku SQL Server, zavolejte metodu WithDataBindMount:

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

Důležitý

Připojení vazby dat mají v porovnání s svazkyomezené funkce, které nabízejí lepší výkon, přenositelnost a zabezpečení, což je vhodnější pro produkční prostředí. Vazebná připojení však umožňují přímý přístup a úpravy souborů v hostitelském systému, ideální pro vývoj a testování vyžadující změny v reálném čase.

Připojení vazby dat využívají systém souborů hostitelského počítače k zachování SQL Server dat napříč restartováními kontejneru. Datová vazba je připojena k C:\SqlServer\Data ve Windows (nebo /SqlServer/Data na cestě Unix) na hostitelském počítači v kontejneru SQL Server. Další informace o připojeních datových vazeb najdete v dokumentaci Docker: Připojení vazby.

Přidejte prostředek SQL Server s parametry

Pokud chcete explicitně zadat heslo používané imagí kontejneru, můžete tyto přihlašovací údaje zadat jako parametry. Podívejte se na následující alternativní příklad:

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

Další informace o poskytování parametrů naleznete v tématu Externí parametry.

Připojení k databázovým prostředkům

Když se hostitel aplikace spustí, dají se k databázovým prostředkům přistupovat z externích nástrojů, jako je Management Studio (SSMS) nebo Data Studio. Řetězec připojení pro databázový zdroj je k dispozici v proměnných prostředí závislých zdrojů a je přístupný pomocí řídicího panelu .NET.NET Aspire: podokně Podrobnosti o prostředku. Proměnná prostředí má název ConnectionStrings__{name} kde {name} je název databázového prostředku, v tomto příkladu je to database. Připojovací řetězec použijte pro připojení k databázovému prostředku z externích nástrojů. Představte si, že máte databázi s názvem todos s jednou tabulkou dbo.Todos.

SQL Server Management Studio
Azure Data Studio

Pokud se chcete připojit k databázovému prostředku ze sady SQL Server Management Studio, postupujte takto:

Otevřete SSMS.
V dialogovém okně Připojení k Server vyberte kartu Další připojovací parametry.
Vložte připojovací řetězec do pole Další parametry připojení a vyberte Připojit.
Pokud jste připojení, zobrazí se prostředek databáze v průzkumníku objektů :

Další informace naleznete v části SQL Server Management Studio: Připojte se k server.

Hostování kontrol stavu integrace

Integrace hostování SQL Server automaticky přidá kontrolu stavu prostředku SQL Server. Kontrola stavu ověřuje, že SQL Server běží a že lze navázat připojení.

Integrace hostování spoléhá na balíček NuGet 📦 AspNetCore.HealthChecks.SqlServer.

integrace Client

Pokud chcete začít s integrací .NET AspireSQL Serverclient, nainstalujte 📦Aspire.Microsoft.Data.SqlClient balíček NuGet v projektu client, tj. projekt aplikace, která využívá SQL Serverclient. Integrace SQL Serverclient registruje instanci SqlConnection, kterou můžete použít k interakci s SQL Server.

.NET rozhraní příkazového řádku
PackageReference

dotnet add package Aspire.Microsoft.Data.SqlClient

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

Přidejte SQL Serverclient

V souboru Program.cs projektu, který využívá client, zavolejte metodu rozšíření AddSqlServerClient na libovolném IHostApplicationBuilder a zaregistrujte SqlConnection pro použití prostřednictvím kontejneru injektáže závislostí. Metoda přebírá parametr názvu připojení.

builder.AddSqlServerClient(connectionName: "database");

Spropitné

Parametr connectionName se musí shodovat s názvem použitým při přidávání prostředku databáze SQL Server do hostitelského projektu aplikace. Jinými slovy, když voláte AddDatabase a zadáte název database, je třeba použít stejný název při volání AddSqlServerClient. Další informace najdete v tématu Přidání SQL Server prostředků a prostředků databáze.

Potom můžete načíst instanci SqlConnection pomocí injektáže závislostí. Pokud například chcete načíst připojení z ukázkové služby:

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

Další informace o injektáži závislostí najdete v tématu .NET injektáž závislostí.

Přidat tagy SQL Serverclient s přiřazenými klíči

Mohou nastat situace, kdy chcete zaregistrovat více instancí SqlConnection s různými názvy připojení. Pokud chcete zaregistrovat klíčované klienty SQL Server, zavolejte metodu AddKeyedSqlServerClient:

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

Důležitý

Při použití služeb s klíči se očekává, že váš prostředek SQL Server nakonfiguroval dvě pojmenované databáze, jednu pro mainDb a druhou pro loggingDb.

Potom můžete načíst SqlConnection instance pomocí injektáže závislostí. Pokud například chcete načíst připojení z ukázkové služby:

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

Další informace o službách s klíči najdete viz injektáž závislostí: služby s klíči.

Konfigurace

Integrace .NET AspireSQL Server poskytuje několik možností konfigurace připojení na základě požadavků a konvencí projektu.

Použijte připojovací řetězec

Při použití připojovacího řetězce z oddílu konfigurace ConnectionStrings můžete při volání metody AddSqlServerClient zadat název připojovacího řetězce:

builder.AddSqlServerClient(connectionName: "sql");

Řetězec připojení se pak načte z oddílu konfigurace ConnectionStrings:

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

Další informace o formátování tohoto připojovacího řetězce naleznete v ConnectionString.

Použití zprostředkovatelů konfigurace

Integrace .NET AspireSQL Server podporuje Microsoft.Extensions.Configuration. Načte MicrosoftDataSqlClientSettings z konfigurace pomocí klíče Aspire:Microsoft:Data:SqlClient. Následující fragment kódu je příkladem souboru appsettings.json, který konfiguruje některé z možností:

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

Kompletní schéma integrace SQL ServerclientJSON najdete v části Aspire. Microsoft.Data.SqlClient/ConfigurationSchema.json.

Použití vložených delegátů

Můžete také předat delegáta Action<MicrosoftDataSqlClientSettings> configureSettings a nastavit některé nebo všechny možnosti přímo, například zakázat kontroly zdraví z kódu:

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

Client kontroly stavu integrace

Ve výchozím nastavení integrace .NET.NET Aspire umožňují kontroly stavu pro všechny služby. Další informace naleznete v tématu .NET.NET Aspire integrace přehled.

Integrace .NET AspireSQL Server:

Přidá kontrolu stavu, když je MicrosoftDataSqlClientSettings.DisableHealthChecksfalsea pokusí se připojit k SQL Server.
Integruje se s koncovým bodem HTTP /health, který stanovuje, že všechny registrované kontroly stavu musí být úspěšné, aby byla aplikace považována za připravenou k přijetí provozu.

Pozorovatelnost a telemetrie

.NET .NET Aspire integrace automaticky nastaví konfigurace protokolování, trasování a metrik, které se někdy označují jako pilíře pozorovatelnosti. Další informace o pozorovatelnosti a telemetrii integrace najdete v přehledu integrace .NET.NET Aspire. V závislosti na zálohovací službě můžou některé integrace podporovat pouze některé z těchto funkcí. Například některé integrace podporují protokolování a trasování, ale ne metriky. Funkce telemetrie je také možné zakázat pomocí technik uvedených v části Konfigurace.

Protokolování

Integrace .NET AspireSQL Server v současné době nemá ve výchozím nastavení povoleno protokolování kvůli omezením Microsoft.Data.SqlClient.

Trasování

Integrace .NET AspireaSQL Server generuje následující trasovací aktivity pomocí OpenTelemetry:

OpenTelemetry.Instrumentation.SqlClient

Metriky

Integrace .NET AspireSQL Server pomocí OpenTelemetryvygeneruje následující metriky:

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

Viz také

Azure SQL Database
SQL Server
ukázkové databázových kontejnerů .NET.NET Aspire
integrace .NET.NET Aspire
.NET Aspire GitHub úložiště

Sdílet prostřednictvím