integratie van .NET AspireSQL ServerEntity Framework Core

2025-04-17

Inclusief: —&— Client integratie

SQL Server is een relationeel databasebeheersysteem dat is ontwikkeld door Microsoft. Met de .NET AspireSQL ServerEntity Framework Core-integratie kunt u verbinding maken met bestaande SQL Server exemplaren of nieuwe exemplaren maken vanuit .NET met de containerafbeelding mcr.microsoft.com/mssql/server.

Hostingintegratie

De SQL Server-hostingintegratiemodellen modelleren de server als het SqlServerServerResource-type en de database als het SqlServerDatabaseResource-type. Als u toegang wilt krijgen tot deze typen en API's, voegt u het 📦Aspire.Hosting.SqlServer NuGet-pakket toe in het app-hostproject.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.SqlServer

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

Zie dotnet pakket toevoegen of Pakketafhankelijkheden beheren in .NET toepassingenvoor meer informatie.

SQL Server resource en databaseresource toevoegen

In uw app-hostproject roept u AddSqlServer aan om een SQL Server-resourcebouwer toe te voegen en te retourneren. Koppel een oproep aan de geretourneerde resourcebouwer bij AddDatabaseom de SQL Server databaseresource toe te voegen.

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
                 .WithLifetime(ContainerLifetime.Persistent);

var db = sql.AddDatabase("database");

builder.AddProject<Projects.ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

// After adding all resources, run the app...

builder.Build().Run();

Notitie

De SQL Server container start traag op, dus is het het beste om een persistente-levensduur te gebruiken om onnodige herstarts te voorkomen. Zie Levensduur van containerresourcesvoor meer informatie.

Wanneer .NET.NET Aspire een containerinstallatiekopie toevoegt aan de app-host, zoals wordt weergegeven in het vorige voorbeeld met de mcr.microsoft.com/mssql/server-installatiekopie, wordt er een nieuw SQL Server exemplaar op uw lokale computer gemaakt. Een verwijzing naar de SQL Server resourcebouwer (de sql variabele) wordt gebruikt om een database toe te voegen. De database heeft de naam database en wordt vervolgens toegevoegd aan de ExampleProject.

Wanneer u een databaseresource toevoegt aan het app-model, wordt de database gemaakt als deze nog niet bestaat. Het maken van de database is afhankelijk van de gebeurtenis-API's van de app-host, met name ResourceReadyEvent. Met andere woorden, wanneer de sql resource gereed is, wordt de gebeurtenis getriggerd en wordt de databasebron aangemaakt.

De SQL Server-resource bevat standaardreferenties met een username van sa en een willekeurige password gegenereerd met behulp van de methode CreateDefaultPasswordParameter.

Wanneer de app-host wordt uitgevoerd, wordt het wachtwoord opgeslagen in de geheime opslagplaats van de app-host. Deze wordt toegevoegd aan de sectie Parameters, bijvoorbeeld:

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

De naam van de parameter is sql-password, maar eigenlijk is het alleen het opmaken van de resourcenaam met een -password achtervoegsel. Voor meer informatie, zie Veilige opslag van app-geheimen in ontwikkeling in ASP.NET Core en SQL Server resource toevoegen met parameters.

De methode WithReference configureert een verbinding in de ExampleProject met de naam database.

Aanbeveling

Als u liever verbinding wilt maken met een bestaande SQL Server, roept u in plaats daarvan AddConnectionString aan. Zie voor meer informatie Bestaande bronnen.

Een resource SQL Server toevoegen met databasescripts

Wanneer u een SqlServerDatabaseResourcetoevoegt, is het standaard afhankelijk van het volgende SQL-script om de database te maken:

IF
(
    NOT EXISTS
    (
        SELECT 1
        FROM sys.databases
        WHERE name = @DatabaseName
    )
)
CREATE DATABASE [<QUOTED_DATABASE_NAME>];

Als u het standaardscript wilt wijzigen, koppelt u een aanroep aan de WithCreationScript methode in de opbouwfunctie voor databaseresources:

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
                 .WithLifetime(ContainerLifetime.Persistent);

var databaseName = "app-db";
var creationScript = $$"""
    IF DB_ID('{{databaseName}}') IS NULL
        CREATE DATABASE [{{databaseName}}];
    GO

    -- Use the database
    USE [{{databaseName}}];
    GO

    -- Create the todos table
    CREATE TABLE todos (
        id INT PRIMARY KEY IDENTITY(1,1),        -- Unique ID for each todo
        title VARCHAR(255) NOT NULL,             -- Short description of the task
        description TEXT,                        -- Optional detailed description
        is_completed BIT DEFAULT 0,              -- Completion status
        due_date DATE,                           -- Optional due date
        created_at DATETIME DEFAULT GETDATE()    -- Creation timestamp
    );
    GO

    """;

var db = sql.AddDatabase(databaseName)
            .WithCreationScript(creationScript);

builder.AddProject<Projects.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

// After adding all resources, run the app...

builder.Build().Run();

In het voorgaande voorbeeld wordt een database gemaakt met een naam app_db met één todos tabel. Het SQL-script wordt uitgevoerd wanneer de databaseresource wordt gemaakt. Het script wordt doorgegeven als een tekenreeks aan de WithCreationScript methode, die vervolgens wordt uitgevoerd in de context van de SQL Server resource.

SQL Server resource toevoegen met gegevensvolume

Als u een gegevensvolume wilt toevoegen aan de SQL Server-resource, roept u de methode WithDataVolume aan voor de SQL Server resource:

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
                 .WithDataVolume();

var db = sql.AddDatabase("database");

builder.AddProject<Projects.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

// After adding all resources, run the app...

builder.Build().Run();

Het gegevensvolume wordt gebruikt om de SQL Server gegevens buiten de levenscyclus van de container te behouden. Het gegevensvolume wordt gekoppeld aan het /var/opt/mssql pad in de SQL Server container en wanneer er geen name parameter wordt opgegeven, wordt de naam willekeurig gegenereerd. Raadpleeg de voor meer informatie over gegevensvolumes en redenen waarom ze de voorkeur hebben boven Docker.

Waarschuwing

Het wachtwoord wordt opgeslagen in het gegevensvolume. Wanneer u een gegevensvolume gebruikt en als het wachtwoord wordt gewijzigd, werkt het pas als u het volume verwijdert.

SQL Server resource toevoegen met data-bind koppeling

Als u een koppeling voor gegevensbinding wilt toevoegen aan de SQL Server-resource, roept u de WithDataBindMount methode aan:

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
                 .WithDataBindMount(source: @"C:\SqlServer\Data");

var db = sql.AddDatabase("database");

builder.AddProject<Projects.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

// After adding all resources, run the app...

builder.Build().Run();

Belangrijk

Data bind mounts hebben beperkte functionaliteit vergeleken met volumes, die betere prestaties, draagbaarheid en beveiliging bieden, waardoor ze geschikter zijn voor productieomgevingen. Bind-mounts bieden echter directe toegang en aanpassing van bestanden op het hostsysteem, ideaal voor ontwikkeling en testen waar realtime wijzigingen nodig zijn.

Databindings zijn afhankelijk van het bestandssysteem van de hostmachine om de SQL Server gegevens te behouden bij het opnieuw opstarten van de container. De koppeling voor gegevensbinding wordt gekoppeld aan de C:\SqlServer\Data in Windows (of /SqlServer/Data op Unix) op de hostcomputer in de SQL Server container. Zie Docker docs: Bindingskoppelingenvoor meer informatie over koppelingskoppelingen voor gegevens.

SQL Server resource toevoegen met parameters

Wanneer u expliciet het wachtwoord wilt verstrekken dat wordt gebruikt door de containerafbeelding, kunt u deze inloggegevens als parameters opgeven. Bekijk het volgende alternatieve voorbeeld:

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.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

// After adding all resources, run the app...

builder.Build().Run();

Zie Externe parametersvoor meer informatie over het opgeven van parameters.

Verbinding maken met databasebronnen

Wanneer de .NET.NET Aspire-app-host wordt uitgevoerd, kunnen de databasebronnen van de server worden geopend vanuit externe hulpprogramma's, zoals SQL Server Management Studio (SSMS) of MSSQL voor Visual Studio Code. De verbindingsreeks voor de databaseresource is beschikbaar in de omgevingsvariabelen van afhankelijke resources en wordt geopend via het .NET.NET Aspire dashboard: Resourcedetails deelvenster. De omgevingsvariabele heet ConnectionStrings__{name} waar {name} de naam van de databaseresource is, in dit voorbeeld is deze database. Gebruik de verbindingsreeks om verbinding te maken met de databaseresource vanuit externe hulpprogramma's. Stel dat u een database hebt met de naam todos met één dbo.Todos tabel.

SQL Server Management Studio
MSSQL voor Visual Studio Code

Voer de volgende stappen uit om vanuit SQL Server Management Studio verbinding te maken met de databaseresource:

Open SQL Server Management Studio.
Selecteer in het dialoogvenster Verbinding maken met Server het tabblad Aanvullende verbindingsparameters.
Plak de verbindingsreeks in het veld Aanvullende verbindingsparameters en selecteer Verbinding maken.
Als u verbinding hebt, ziet u de databaseresource in de Objectverkenner:

Zie SQL Server Management Studio: Verbinding maken met een servervoor meer informatie.

Gezondheidscontroles voor hostingintegratie

De SQL Server hostingintegratie voegt automatisch een statuscontrole toe voor de SQL Server resource. De gezondheidscontrole controleert of de SQL Server draait en of er een verbinding tot stand kan worden gebracht.

De hostingintegratie is afhankelijk van het 📦 AspNetCore.HealthChecks.SqlServer NuGet-pakket.

integratie Client

Installeer de .NET AspireSQL Serverom aan de slag te gaan met de Entity Framework Core📦Aspire-integratie. Microsoft.EntityFrameworkCore.SqlServer NuGet-pakket in het clientgebruikte project, namelijk het project voor de toepassing die gebruikmaakt van de SQL ServerEntity Framework Core-client.

.NET CLI
PackageReference

dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer

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

Zie dotnet pakket toevoegen of Pakketafhankelijkheden beheren in .NET toepassingenvoor meer informatie.

SQL Server databasecontext toevoegen

Roep in het Program.cs bestand van het clientgebruikte project de AddSqlServerDbContext-extensiemethode aan op een IHostApplicationBuilder om een DbContext te registreren voor gebruik via de container voor afhankelijkheidsinjectie. De methode gebruikt een verbindingsnaamparameter.

builder.AddSqlServerDbContext<ExampleDbContext>(connectionName: "database");

Aanbeveling

De parameter connectionName moet overeenkomen met de naam die wordt gebruikt bij het toevoegen van de SQL Server databaseresource in het app-hostproject. Met andere woorden, wanneer u AddDatabase aanroept en een naam opgeeft van database diezelfde naam moet worden gebruikt bij het aanroepen van AddSqlServerDbContext. Voor meer informatie, zie SQL Server resource en databaseresourcetoevoegen.

Ga als volgende te werk om ExampleDbContext object op te halen uit een service:

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

Voor meer informatie over afhankelijkheidsinjectie, zie .NET afhankelijkheidsinjectie.

Een SQL Server-databasecontext verrijken

U kunt liever de standaard Entity Framework-methode gebruiken om een databasecontext te verkrijgen en deze toe te voegen aan de container voor afhankelijkheidsinjectie:

builder.Services.AddDbContext<ExampleDbContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("database")
        ?? throw new InvalidOperationException("Connection string 'database' not found.")));

Notitie

De naam van de verbindingsreeks die u doorgeeft aan de GetConnectionString-methode, moet overeenkomen met de naam die wordt gebruikt bij het toevoegen van de SQL Server-resource in het hostproject van de app. Voor meer informatie, zie SQL Server resource en databaseresourcetoevoegen.

U hebt meer flexibiliteit wanneer u de databasecontext op deze manier maakt, bijvoorbeeld:

U kunt bestaande configuratiecode opnieuw gebruiken voor de databasecontext zonder deze opnieuw te schrijven voor .NET.NET Aspire.
U kunt Entity Framework Core interceptors gebruiken om databasebewerkingen te wijzigen.
U kunt ervoor kiezen om Entity Framework Core contextpooling niet te gebruiken, wat in sommige omstandigheden beter kan presteren.

Als u deze methode gebruikt, kunt u de databasecontext verbeteren met .NET.NET Aspire-stijl retries, statuscontroles, logging en telemetriefuncties door de methode EnrichSqlServerDbContext aan te roepen.

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

De parameter settings is een exemplaar van de klasse MicrosoftEntityFrameworkCoreSqlServerSettings.

Configuratie

De .NET AspireSQL ServerEntity Framework Core-integratie biedt meerdere configuratiemethoden en opties om te voldoen aan de vereisten en conventies van uw project.

Verbindingsreeks gebruiken

Wanneer u een verbindingsreeks uit de sectie ConnectionStrings configuratie gebruikt, geeft u de naam van de verbindingsreeks op bij het aanroepen van builder.AddSqlServerDbContext<TContext>():

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

De verbindingsreeks wordt opgehaald uit de ConnectionStrings configuratiesectie:

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

De EnrichSqlServerDbContext maakt geen gebruik van de ConnectionStrings configuratiesectie, omdat er een DbContext wordt verwacht die moet worden geregistreerd op het punt dat deze wordt aangeroepen.

Zie de ConnectionStringvoor meer informatie.

Configuratieproviders gebruiken

De .NET AspireSQL ServerEntity Framework Core-integratie ondersteunt Microsoft.Extensions.Configuration. Het laadt de MicrosoftEntityFrameworkCoreSqlServerSettings uit configuratiebestanden zoals appsettings.json met behulp van de Aspire:Microsoft:EntityFrameworkCore:SqlServer sleutel. Als u uw configuraties in de sectie Aspire:Microsoft:EntityFrameworkCore:SqlServer hebt ingesteld, kunt u de methode gewoon aanroepen zonder een parameter door te geven.

Hier volgt een voorbeeld van een appsettings.json-bestand waarmee een aantal van de beschikbare opties wordt geconfigureerd:

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

Inlineconfiguraties gebruiken

U kunt de Action<MicrosoftEntityFrameworkCoreSqlServerSettings> delegate ook doorgeven om bepaalde of alle opties in-line in te stellen, bijvoorbeeld om de metrische functies uit te schakelen.

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

Meerdere DbContext-verbindingen configureren

Als u meer dan één DbContext met een andere configuratie wilt registreren, kunt u $"Aspire.Microsoft.EntityFrameworkCore.SqlServer:{typeof(TContext).Name}" configuratiesectienaam gebruiken. De json-configuratie ziet er als volgt uit:

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

Als u vervolgens de methode AddSqlServerDbContext aanroept met AnotherDbContext typeparameter, worden de instellingen vanuit Aspire:Microsoft:EntityFrameworkCore:SqlServer:AnotherDbContext sectie geladen.

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

Configuratieopties

Dit zijn de configureerbare opties met bijbehorende standaardwaarden:

Naam	Beschrijving
`ConnectionString`	De verbindingsreeks van de SQL Server-database waarmee verbinding moet worden gemaakt.
`DbContextPooling`	Een Booleaanse waarde die aangeeft of de db-context wordt gegroepeerd of expliciet wordt gemaakt telkens wanneer deze wordt aangevraagd
`MaxRetryCount`	Het maximum aantal nieuwe pogingen. De standaardwaarde is 6. Stel deze in op 0 om het mechanisme voor opnieuw proberen uit te schakelen.
`DisableHealthChecks`	Een Booleaanse waarde die aangeeft of de databasestatuscontrole is uitgeschakeld of niet.
`DisableTracing`	Een booleaanse waarde die aangeeft of de OpenTelemetry tracering is uitgeschakeld of niet.
`DisableMetrics`	Een Booleaanse waarde die aangeeft of de OpenTelemetry metrische gegevens zijn uitgeschakeld of niet.
`Timeout`	De tijd in seconden om te wachten totdat de opdracht is uitgevoerd.

Gezondheidscontroles voor Client-integratie

.NET .NET Aspire clientintegraties hebben standaard gezondheidscontroles ingeschakeld voor alle diensten. Evenzo, schakelen veel .NET.NET Aspirehostingintegraties ook eindpunten voor gezondheidscontrole in. Zie voor meer informatie:

De integratie van .NET Aspire Sql ServerEntity Framework Core verwerkt standaard het volgende:

Hiermee wordt de DbContextHealthChecktoegevoegd, waarmee de EF Core methode van CanConnectAsyncwordt aangeroepen. De naam van de gezondheidscontrole is de naam van het TContext type.
Integreert met het /health HTTP-eindpunt, waarbij alle geregistreerde gezondheidcontroles moeten slagen voordat de app als gereed kan worden beschouwd om verkeer te accepteren.

Waarneembaarheid en telemetrie

.NET .NET Aspire integraties stellen automatisch configuraties voor logboekregistratie, tracering en metrieken in, die ook wel bekend staan als de pijlers van observability. Zie .NET.NET Aspire overzicht van integratieintegratiesvoor meer informatie over de waarneembaarheid en telemetrie van integraties. Afhankelijk van de back-upservice ondersteunen sommige integraties mogelijk slechts enkele van deze functies. Sommige integraties ondersteunen bijvoorbeeld logboekregistratie en tracering, maar geen metrische gegevens. Telemetriefuncties kunnen ook worden uitgeschakeld met behulp van de technieken die worden weergegeven in de sectie Configuratie.

Loggen

De .NET AspireSQL ServerEntity Framework Core-integratie maakt gebruik van de volgende logboekcategorieën:

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

Traceren

De integratie van .NET AspireSQL ServerEntity Framework Core verzendt de volgende traceringsactiviteiten met behulp van OpenTelemetry:

"OpenTelemetry. Instrumentation.EntityFrameworkCore"

Statistieken

De integratie van .NET AspireSQL ServerEntity Framework Core verzendt de volgende metrische gegevens met behulp van 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