Aspire SQL Server Entity Framework Core samverkan

Inkluderar:Värdintegrering ingår Värdintegrering &–& integrering ingår integration

SQL Server är ett relationsdatabashanteringssystem som utvecklats av Microsoft. Med integreringen 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:s hosting-integration modellerar servern som SqlServerServerResource typen och databasen som SqlServerDatabaseResource typen. Om du vill komma åt dessa typer och API:er lägger du till 📦Aspire. Hosting.SqlServer NuGet-paketet i AppHost-projektet .

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 Ditt AppHost-projekt anropar du AddSqlServer för att lägga till och returnera en SQL Server resursbyggare. Länka ett anrop till den returnerade resursbyggaren till AddDatabase fö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>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

När Aspire lägger till en containeravbildning i AppHost, som du ser i föregående exempel med avbildningen mcr.microsoft.com/mssql/server, skapas en ny instans av SQL Server 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.

När du lägger till en databasresurs i appmodellen skapas databasen om den inte redan finns. Skapandet av databasen förlitar sig på AppHost-händelse-API:erna, särskilt ResourceReadyEvent. Med andra ord, när resursen sql är klar utlöses händelsen och databasresursen skapas.

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 AppHost körs lagras lösenordet i AppHosts hemliga arkiv. 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.

Lägga till SQL Server resurs med databasskript

När du lägger till ett SqlServerDatabaseResourceförlitar det sig som standard på följande SQL-skript för att skapa databasen:

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

Om du vill ändra standardskriptet kedjar du ett anrop till WithCreationScript metoden i databasresursverktyget:

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();

I föregående exempel skapas en databas med namnet app_db med en enda todos tabell. SQL-skriptet körs när databasresursen skapas. Skriptet skickas som en sträng till WithCreationScript metoden, som sedan körs i resursens SQL Server kontext.

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

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

builder.Build().Run();

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.

Lägg till SQL Server resurs med databindningsfäste

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

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

builder.Build().Run();

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. För mer information om databindningar, se dokumentationen: Bindningsmonteringar.

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

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

builder.Build().Run();

Mer information om hur du tillhandahåller parametrar finns i Externa parametrar.

Ansluta till databasresurser

Aspire När AppHost körs kan serverns databasresurser nås från externa verktyg, till exempel SQL Server Management Studio (SSMS) eller MSSQL för Visual Studio Code. Anslutningssträngen för databasresursen är tillgänglig i miljövariablerna för beroende resurser och nås med hjälp av Aspire instrumentpanelen: Fönstret Resursinformation . 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.

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 är igång och att en anslutning kan upprättas till den.

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

Client integrering

Kom igång med AspireSQL ServerEntity Framework Core-integreringen genom att installera 📦Aspire. Microsoft.EntityFrameworkCore.SqlServer NuGet-paket i det klientkrävande projektet, dvs. projektet för det program som använder SQL ServerEntity Framework Core-klienten.

dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer

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

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

Lägg till SQL Server databaskontext

I Program.cs-filen för ditt klientkrävande projekt, anropar du metoden AddSqlServerDbContext-tillägg på varje IHostApplicationBuilder för att registrera en DbContext för användning via beroendeinjektionscontainern. Metoden tar en parameter för anslutningsnamn.

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

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.

Förbättra en SQL Server databaskontext

Du kanske föredrar att använda entitetsramverkets standardmetod för att hämta en databaskontext och lägga till den i containern för beroendeinmatning:

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

Du har större flexibilitet när du skapar databaskontexten på det här sättet, till exempel:

• Du kan återanvända befintlig konfigurationskod för databaskontexten utan att skriva om den för Aspire.
• Du kan använda Entity Framework Core interceptorer för att ändra databasåtgärder.
• Du kan välja att inte använda Entity Framework Core kontextpooler, vilket kan fungera bättre under vissa omständigheter.

Om du använder den här metoden kan du förbättra databaskontexten med Aspire-style-återförsök, hälsokontroller, loggning och telemetrifunktioner genom att anropa EnrichSqlServerDbContext metoden:

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

Parametern settings är en instans av klassen MicrosoftEntityFrameworkCoreSqlServerSettings.

Konfiguration

Den 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

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. Json-konfigurationen 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:

Client hälsokontroller för integrering

Som standard Aspire har klientintegreringarhälsokontroller aktiverade för alla tjänster. På samma sätt möjliggör många Aspirehostingintegrationer även hälsokontrolländpunkter. Mer information finns i:

• .NET apphälsokontroller i C#
• Hälsokontroller i ASP.NET Core

Som standard hanterar 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

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 Aspire översikten över 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

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 AspireSQL ServerEntity Framework Core genererar följande spårningsaktiviteter med hjälp av OpenTelemetry:

• OpenTelemetry.Instrumentation.EntityFrameworkCore

Mätsystem

Integreringen 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

Se även

• Azure SQL Database-dokumentation
• Aspire Integrationer
• Aspire GitHub Repo