Číst v angličtině

Sdílet prostřednictvím

integrace .NET AspireSQL Server

  • Článek

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í

SQL Server hostování integrace 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 .

dotnet add package Aspire.Hosting.SqlServer

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.

Tip

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.

Upozorně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

Po spuštění hostitele aplikace je možné k databázovým prostředkům serveru 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.

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

  1. Otevřete SSMS.

  2. V dialogovém okně Připojení k Server vyberte kartu Další připojovací parametry.

  3. Vložte připojovací řetězec do pole Další parametry připojení a vyberte Připojit.

    SQL Server Management Studio: Připojte se k dialogu Server.

  4. Pokud jste připojení, zobrazí se prostředek databáze v průzkumníku objektů :

    SQL Server Management Studio: Připojeno k databázi.

Další informace najdete v tématu SQL Server Management Studio: Připojení k serveru.

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í klienta .NET AspireSQL Server, nainstalujte 📦Aspire. Microsoft.Data.SqlClient balíček NuGet v projektu, který využívá klienta, tj. projekt aplikace, která používá klienta SQL Server. Integrace klienta SQL Server registruje instanci SqlConnection, kterou můžete použít k interakci s SQL Server.

dotnet add package Aspire.Microsoft.Data.SqlClient

Přidejte klienta SQL Server

V souboru Program.cs projektu klienta zavolejte rozšiřující metodu AddSqlServerClient pro libovolný IHostApplicationBuilder a zaregistrujte SqlConnection pro použití prostřednictvím kontejneru pro vkládání závislostí. Metoda přebírá parametr názvu připojení.

builder.AddSqlServerClient(connectionName: "database");

Tip

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 klíčového klienta SQL Server

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 klienta SQL ServerJSON naleznete v AspireMicrosoft.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é