.NET Aspire SQL Server Entity Framework Core integration

Artikel
12/18/2024

omfattar:Hostingintegrering och Client integrering

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

Värdtjänstintegration

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

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.SqlServer

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

För mer information, se dotnet add package eller Hantera paketberoenden i .NET applikationer.

Lägg till resursen SQL Server och databasresursen

I värdprojektet för appen anropar du AddSqlServer för att lägga till och returnera en resursbyggare för SQL Server. Länka ett anrop till 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 tar lång tid att starta SQL Server-containern, så det är bäst att använda en varaktig livstid för att undvika onödiga omstarter. Mer information finns i containerresursens livslängd.

När .NET.NET Aspire lägger till en containerbild i appvärden, som visas i föregående exempel med mcr.microsoft.com/mssql/server-bilden, skapar det en ny SQL Server-instans på din lokala dator. 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 förråd. 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å /var/opt/mssql-sökvägen i containern SQL Server och när name-parametern inte anges genereras namnet slumpmässigt. Mer information om datavolymer och detaljer om varför de föredras framför bindmonteringarfinns i dokumentationen Docker: 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 databindningsmontering till den SQL Server resursen anropar du metoden 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...

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.

Databindningsmonteringar förlitar sig på värddatorns filsystem för att bevara SQL Server data mellan 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-apparnas värd körs kan server:s databasresurserna nås via externa verktyg, till exempel SQL Server Management Studio (SSMS) eller Azure Data Studio. Anslutningssträngen för databasresursen är tillgänglig i miljövariablerna för beroende resurser och nås genom instrumentpanelen .NET.NET Aspire: Resursinformation-fönstret. 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.

Drift av hälsokontroller för integration

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.

Värdintegrering förlitar sig på 📦 AspNetCore.HealthChecks.SqlServer NuGet-paketet.

Client integrering

Kom igång med .NET AspireSQL ServerEntity Framework Core-integreringen genom att installera 📦Aspire. Microsoft.EntityFrameworkCore.SqlServer NuGet-paketet i projektet client-consuming, dvs. projektet för programmet som använder SQL ServerEntity Framework Coreclient.

.NET CLI
PackageReference

dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer

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

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

Lägg till SQL Server databaskontext

I den Program.cs-filen för ditt client-konsumerande projekt anropar du metoden för AddSqlServerDbContext-tillägg på alla IHostApplicationBuilder för att registrera en DbContext för användning via containern för beroendeinjektion. Metoden tar en parameter för anslutningsnamn.

builder.AddSqlServerDbContext<ExampleDbContext>(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 AddSqlServerDbContext. För mer information, se Lägg till SQL Server resurs och databasresurs.

Så här hämtar du ExampleDbContext objekt från en tjänst:

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

Mer information om beroendeinmatning finns i .NET beroendeinmatning.

Lägg till SQL Server databaskontext med berikning

Om du vill utöka DbContext med ytterligare tjänster, till exempel automatiska återförsök, hälsokontroller, loggning och telemetri, anropar du metoden EnrichSqlServerDbContext:

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

Parametern settings är en instans av klassen MicrosoftEntityFrameworkCoreSqlServerSettings.

Konfiguration

Den .NET AspireSQL ServerEntity Framework Core integreringen innehåller flera konfigurationsmetoder och alternativ för att uppfylla kraven och konventionerna i ditt projekt.

Använda anslutningssträng

När du använder en anslutningssträng från ConnectionStrings konfigurationsavsnittet anger du namnet på anslutningssträngen när du anropar builder.AddSqlServerDbContext<TContext>():

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

Anslutningssträngen hämtas från avsnittet ConnectionStrings konfiguration:

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

EnrichSqlServerDbContext använder inte ConnectionStrings-konfigurationsavsnittet eftersom det förväntar sig att en DbContext registreras vid den tidpunkt då den anropas.

Mer information finns i ConnectionString.

Använda konfigurationsprovidrar

.NET Aspire SQL Server Entity Framework Core-integreringen stöder Microsoft.Extensions.Configuration. Den läser in MicrosoftEntityFrameworkCoreSqlServerSettings från konfigurationsfiler som appsettings.json med hjälp av Aspire:Microsoft:EntityFrameworkCore:SqlServer-nyckeln. Om du har konfigurerat konfigurationerna i avsnittet Aspire:Microsoft:EntityFrameworkCore:SqlServer kan du bara anropa metoden utan att skicka någon parameter.

Följande är ett exempel på en appsettings.json fil som konfigurerar några av de tillgängliga alternativen:

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

Använd infogade konfigurationer

Du kan också använda Action<MicrosoftEntityFrameworkCoreSqlServerSettings>-delegaten för att konfigurera vissa eller alla alternativ direkt, till exempel för att inaktivera mätvärden:

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

Konfigurera flera DbContext-anslutningar

Om du vill registrera fler än en DbContext med en annan konfiguration kan du använda $"Aspire.Microsoft.EntityFrameworkCore.SqlServer:{typeof(TContext).Name}" namn på konfigurationsavsnittet. Konfigurationen json skulle se ut så här:

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

Om du sedan anropar AddSqlServerDbContext-metoden med parametern AnotherDbContext typ läser du in inställningarna från Aspire:Microsoft:EntityFrameworkCore:SqlServer:AnotherDbContext avsnittet.

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

Konfigurationsalternativ

Här är de konfigurerbara alternativen med motsvarande standardvärden:

Namn	Beskrivning
`ConnectionString`	Anslutningssträngen för att ansluta till databasen SQL Server.
`DbContextPooling`	Ett booleskt värde som anger om db-kontexten ska poolas eller skapas explicit varje gång den begärs
`MaxRetryCount`	Det maximala antalet återförsök. Standardvärdet är 6, ange det till 0 för att inaktivera återförsöksmekanismen.
`DisableHealthChecks`	Ett booleskt värde som anger om databasens hälsokontroll är inaktiverad eller inte.
`DisableTracing`	Ett booleskt värde som anger om OpenTelemetry spårning är inaktiverad eller inte.
`DisableMetrics`	Ett booleskt värde som anger om OpenTelemetry mått är inaktiverade eller inte.
`Timeout`	Tiden i sekunder för att vänta innan kommandot körs.

Hälsokontroller

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

Som standard hanterar .NET Aspire Sql ServerEntity Framework Core-integrering följande:

Lägger till DbContextHealthCheck, som anropar EF Core:s metod CanConnectAsync. Namnet på hälsokontrollen är samma som typen TContext.
Integrerar med HTTP-slutpunkt /health, som föreskriver att alla registrerade hälsokontroller måste godkännas för att appen ska anses vara redo att ta emot 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

.NET Aspire SQL Server Entity Framework Core-integreringen använder följande loggkategorier:

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

Spårning

Integreringen .NET AspireSQL ServerEntity Framework Core genererar följande spårningsaktiviteter med hjälp av OpenTelemetry:

OpenTelemetry.Instrumentation.EntityFrameworkCore

Mätsystem

Integreringen .NET AspireSQL ServerEntity Framework Core genererar följande mått med hjälp av OpenTelemetry:

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

Dela via