integrace .NET AspireSQL ServerEntity Framework Core

Článek
01/22/2025

zahrnuje:hostitelská integrace a integrace Client

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

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 balíček NuGet 📦Aspire.Hostování.SqlServer v 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 Manage package dependencies in .NET applications.

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

V projektu hostitele aplikace zavolejte AddSqlServer, abyste přidali a vrátili generátor prostředků SQL Server. Zřetězte volání vráceného tvůrce prostředků k AddDatabasea poté přidejte SQL Server jako databázový prostředek.

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 Doba životnosti prostředku 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 tvůrce 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ě vygenerovaný password 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 viz Odkaz na existující zdroje.

Přidání SQL Server prostředku s datovým svazkem

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 objemech dat a podrobnosti o tom, proč jsou preferovány před připojeními typu bind , najdete v dokumentaci Docker: Svazky.

Varování

Heslo je uloženo v datovém svazku. Při použití datového svazku a pokud se heslo změní, nebude fungovat, dokud svazek neodstraníte.

Přidání prostředku SQL Server s připojeným datovým propojením

Pokud chcete přidat datovou vazbu 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í. Připojení vazby však umožňují přímý přístup a úpravy souborů v hostitelském systému, které jsou ideální pro vývoj a testování, kde jsou potřebné 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é připojení je namontováno v umístění C:\SqlServer\Data v systému Windows (nebo /SqlServer/Data na 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. Připojovací řetězec pro databázový prostředek je k dispozici v proměnných prostředí využívaných závislými prostředky a je přístupný přes řídicí panel .NET.NET Aspire: Podrobnosti o prostředku podokno. 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řipojit k Server vyberte kartu Další parametry připojení.
Vložte připojovací řetězec do pole Další parametry připojení a vyberte Připojit.
Pokud jste připojeni, prostředek databáze se zobrazí v průzkumníku objektů :

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 je SQL Server v provozu a že je možné se k němu připojit.

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

integrace Client

Pokud chcete začít s integrací .NET AspireSQL ServerEntity Framework Core, nainstalujte 📦Aspire. Microsoft.EntityFrameworkCore.SqlServer balíček NuGet v projektu, který využívá klienta, tj. projekt aplikace, která používá klienta SQL ServerEntity Framework Core.

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

dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer

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

Další informace viz dotnet add package nebo Správa závislostí balíčků v .NET aplikacích.

Přidání kontextu databáze SQL Server

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

builder.AddSqlServerDbContext<ExampleDbContext>(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 poskytnete jméno database, mělo by být toto jméno použito i při volání AddSqlServerDbContext. Další informace najdete v tématu Přidání prostředku SQL Server a prostředku databáze.

Načtení ExampleDbContext objektu ze služby:

public class ExampleService(ExampleDbContext context)
{
    // Use context...
}

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

Přidejte kontext databáze SQL Server s obohacením

Pokud chcete rozšířit DbContext dalšími službami, jako jsou automatické opakování, kontroly stavu, protokolování a telemetrie, zavolejte metodu EnrichSqlServerDbContext:

builder.EnrichSqlServerDbContext<ExampleDbContext>(
    connectionName: "database",
    configureSettings: settings =>
    {
        settings.DisableRetry = false;
        settings.CommandTimeout = 30 // seconds
    });

Parametr settings je instance třídy MicrosoftEntityFrameworkCoreSqlServerSettings.

Konfigurace

Integrace .NET AspireSQL ServerEntity Framework Core poskytuje několik přístupů a možností konfigurace pro splnění 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 zadáte název připojovacího řetězce při volání builder.AddSqlServerDbContext<TContext>():

builder.AddSqlServerDbContext<ExampleDbContext>("sql");

Řetězec připojení je načten z oddílu konfigurace ConnectionStrings:

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

EnrichSqlServerDbContext nepoužije konfigurační sekci ConnectionStrings, protože očekává, že DbContext bude zaregistrován při svém vyvolání.

Další informace naleznete v části ConnectionString.

Použití zprostředkovatelů konfigurace

Integrace .NET AspireSQL ServerEntity Framework Core podporuje Microsoft.Extensions.Configuration. Načte MicrosoftEntityFrameworkCoreSqlServerSettings z konfiguračních souborů, jako je appsettings.json, pomocí klíče Aspire:Microsoft:EntityFrameworkCore:SqlServer. Pokud jste nastavili konfigurace v oddílu Aspire:Microsoft:EntityFrameworkCore:SqlServer, stačí volat metodu bez předání jakéhokoli parametru.

Následuje příklad souboru appsettings.json, který konfiguruje některé z dostupných možností:

{
  "Aspire": {
    "Microsoft": {
      "EntityFrameworkCore": {
        "SqlServer": {
          "ConnectionString": "YOUR_CONNECTIONSTRING",
          "DbContextPooling": true,
          "DisableHealthChecks": true,
          "DisableTracing": true,
          "DisableMetrics": false
        }
      }
    }
  }
}

Použijte vložené konfigurace

Můžete také předat delegáta Action<MicrosoftEntityFrameworkCoreSqlServerSettings> k nastavení některých nebo všech možností přímo, například vypnout metriky:

builder.AddSqlServerDbContext<YourDbContext>(
    "sql",
    static settings =>
        settings.DisableMetrics = true);

Konfigurace více připojení DbContext

Pokud chcete zaregistrovat více než jeden DbContext s různými konfiguracemi, můžete použít název sekce konfigurace $"Aspire.Microsoft.EntityFrameworkCore.SqlServer:{typeof(TContext).Name}". Konfigurace json by vypadala takto:

{
  "Aspire": {
    "Microsoft": {
      "EntityFrameworkCore": {
          "SqlServer": {
            "ConnectionString": "YOUR_CONNECTIONSTRING",
            "DbContextPooling": true,
            "DisableHealthChecks": true,
            "DisableTracing": true,
            "DisableMetrics": false,
          "AnotherDbContext": {
            "ConnectionString": "AnotherDbContext_CONNECTIONSTRING",
            "DisableTracing": false
          }
        }
      }
    }
  }
}

Volání metody AddSqlServerDbContext s parametrem typu AnotherDbContext by pak načetlo nastavení z oddílu Aspire:Microsoft:EntityFrameworkCore:SqlServer:AnotherDbContext.

builder.AddSqlServerDbContext<AnotherDbContext>("another-sql");

Možnosti konfigurace

Tady jsou konfigurovatelné možnosti s odpovídajícími výchozími hodnotami:

Jméno	Popis
`ConnectionString`	Připojovací řetězec SQL Server databáze, ke které se chcete připojit.
`DbContextPooling`	Logická hodnota, která určuje, zda bude kontext databáze používán v poolingu nebo explicitně vytvářen při každém vyžádání.
`MaxRetryCount`	Maximální počet opakovaných pokusů. Výchozí hodnota je 6, nastavte ji na hodnotu 0 a zakažte mechanismus opakování.
`DisableHealthChecks`	Logická hodnota, která označuje, jestli je kontrola stavu databáze zakázaná nebo ne.
`DisableTracing`	Logická hodnota označující, jestli je trasování OpenTelemetry zakázané nebo ne.
`DisableMetrics`	Logická hodnota označující, jestli jsou metriky OpenTelemetry zakázané nebo ne.
`Timeout`	Doba v sekundách čekání na spuštění příkazu.

Kontroly stavu

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

Integrace .NET Aspire Sql ServerEntity Framework Core ve výchozím nastavení zpracovává následující:

Přidá DbContextHealthCheck, který volá metodu CanConnectAsync od EF Core. Název kontroly stavu odpovídá názvu typu TContext.
Integruje se s koncovým bodem /health HTTP, který určuje, že všechny registrované kontroly stavu musí projít, aby aplikace byla považována za připravenou přijímat provoz.

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 ServerEntity Framework Core používá následující kategorie protokolů:

Microsoft.EntityFrameworkCore.ChangeTracking
Microsoft.EntityFrameworkCore.Database.Command
Microsoft.EntityFrameworkCore.Database.Connection
Microsoft.EntityFrameworkCore.Database.Transaction
Microsoft.EntityFrameworkCore.Infrastructure
Microsoft.EntityFrameworkCore.Migrations
Microsoft.EntityFrameworkCore.Model
Microsoft.EntityFrameworkCore.Model.Validation
Microsoft.EntityFrameworkCore.Query
Microsoft.EntityFrameworkCore.Update

Trasování

Integrace .NET AspireSQL ServerEntity Framework Core pomocí OpenTelemetryvygeneruje následující aktivity trasování:

"OpenTelemetry.Instrumentation.EntityFrameworkCore"

Metriky

Integrace .NET AspireSQL ServerEntity Framework Core pomocí OpenTelemetryvygeneruje následující metriky:

Microsoft.EntityFrameworkCore:
- ec_Microsoft_EntityFrameworkCore_active_db_contexts
- ec_Microsoft_EntityFrameworkCore_total_queries
- ec_Microsoft_EntityFrameworkCore_queries_per_second
- ec_Microsoft_EntityFrameworkCore_total_save_changes
- ec_Microsoft_EntityFrameworkCore_save_changes_per_second
- ec_Microsoft_EntityFrameworkCore_compiled_query_cache_hit_rate
- ec_Microsoft_Entity_total_execution_strategy_operation_failures
- ec_Microsoft_E_execution_strategy_operation_failures_per_second
- ec_Microsoft_EntityFramew_total_optimistic_concurrency_failures
- ec_Microsoft_EntityF_optimistic_concurrency_failures_per_second

Sdílet prostřednictvím