integrazione di .NET AspireSQL ServerEntity Framework Core

Include:integrazione dell'hosting e Client integrazione

SQL Server è un sistema di gestione di database relazionale sviluppato da Microsoft. L'integrazione .NET AspireSQL ServerEntity Framework Core ti consente di connetterti alle istanze esistenti di SQL Server o di creare nuove istanze da .NET utilizzando l'immagine del contenitore mcr.microsoft.com/mssql/server.

Integrazione dell'hosting

Il SQL Server che ospita l'integrazione modella il server come tipo di SqlServerServerResource e il database come tipo di SqlServerDatabaseResource. Per accedere a questi tipi e API, aggiungere il pacchetto NuGet 📦Aspire.Hosting.SqlServer nel progetto host dell'app .

dotnet add package Aspire.Hosting.SqlServer

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

Per altre informazioni, vedere dotnet add package o gestire le dipendenze dei pacchetti nelle applicazioni .NET.

Aggiungere la risorsa SQL Server e la risorsa di database

Nel progetto host dell'app chiamare AddSqlServer per aggiungere e restituire un generatore di risorse SQL Server. Collega una chiamata al builder di risorse restituito a AddDatabaseper aggiungere la risorsa del database 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...

Quando .NET.NET Aspire aggiunge un'immagine del contenitore all'host dell'app, come illustrato nell'esempio precedente con l'immagine mcr.microsoft.com/mssql/server, crea una nuova istanza SQL Server nel computer locale. Per aggiungere un database viene usato un riferimento al generatore di risorse SQL Server (la variabile sql). Il database viene denominato database e quindi aggiunto al ExampleProject. La risorsa SQL Server include le credenziali predefinite con un username di sa e un password casuale generato usando il metodo CreateDefaultPasswordParameter.

Quando viene eseguito l'host dell'app, la password viene archiviata nell'archivio dei segreti dell'host dell'app. Viene aggiunto alla sezione Parameters, ad esempio:

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

Il nome del parametro è sql-password, ma in realtà è sufficiente formattare il nome della risorsa con un suffisso -password. Per altre informazioni, vedere Archiviazione sicura dei segreti dell'app in fase di sviluppo in ASP.NET Core e Aggiungere una risorsa SQL Server con parametri.

Il metodo WithReference configura una connessione nel ExampleProject denominato database.

Aggiungere la risorsa SQL Server con il volume di dati

Per aggiungere un volume di dati alla risorsa SQL Server, chiamare il metodo WithDataVolume nella risorsa 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...

Il volume di dati viene usato per rendere persistenti i dati SQL Server all'esterno del ciclo di vita del contenitore. Il volume di dati viene montato nel percorso /var/opt/mssql all'interno del contenitore SQL Server e, quando un parametro name non è fornito, il nome viene generato in modo casuale. Per ulteriori informazioni sui volumi di dati e sui motivi per cui sono preferiti rispetto ai mount bind, consulta la documentazione Docker: Volumi.

Aggiungere la risorsa SQL Server con il bind mount dei dati

Per aggiungere un montaggio dell'associazione dati alla risorsa SQL Server, chiamare il metodo 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...

I montaggi di associazione dati si basano sul file system del computer host per rendere persistenti i dati SQL Server tra i riavvii del contenitore. Il data bind mount è montato al percorso C:\SqlServer\Data su Windows (o su /SqlServer/Data nel percorso Unix) sulla macchina host nel contenitore SQL Server. Per altre informazioni sui montaggi di associazione dati, vedere Docker docs: Bind mounts.

Aggiungere SQL Server risorsa con parametri

Quando si vuole specificare in modo esplicito la password usata dall'immagine del contenitore, è possibile specificare queste credenziali come parametri. Si consideri l'esempio alternativo seguente:

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...

Per altre informazioni sulla fornitura di parametri, vedere Parametri esterni.

Connettersi alle risorse del database

Quando viene eseguito l'host dell'app .NET Aspire, è possibile accedere alle risorse di database dell'serverda strumenti esterni, ad esempio SQL Server Management Studio (SSMS) o Azure Data Studio. La stringa di connessione per la risorsa di database è disponibile nelle variabili di ambiente delle risorse dipendenti ed è accessibile tramite il dashboard .NET.NET Aspire: nel riquadro "Dettagli della risorsa". La variabile di ambiente è denominata ConnectionStrings__{name} dove {name} è il nome della risorsa di database, in questo esempio è database. Usare la stringa di connessione per connettersi alla risorsa di database da strumenti esterni. Si supponga di avere un database denominato todos con una singola tabella dbo.Todos.

Hosting dei controlli di integrità dell'integrazione

L'integrazione dell'hosting SQL Server aggiunge automaticamente un controllo dello stato di integrità per la risorsa SQL Server. Il controllo di integrità verifica che il SQL Server sia in funzionamento e che sia possibile stabilire una connessione.

L'integrazione dell'hosting si basa sul pacchetto NuGet 📦 AspNetCore.HealthChecks.SqlServer.

Client integrazione

Per iniziare a usare l'integrazione di .NET AspireSQL ServerEntity Framework Core, installare il 📦Aspire.Microsoft.EntityFrameworkCore.SqlServer pacchetto NuGet nel progetto client-consuming, cioè il progetto per l'applicazione che usa il SQL ServerEntity Framework Coreclient.

dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer

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

Per altre informazioni, vedere dotnet add package o Manage package dependencies in .NET applications.

Aggiungere il contesto del database SQL Server

Nel file Program.cs del progetto in cui si consuma client, chiamate il metodo di estensione AddSqlServerDbContext su qualsiasi IHostApplicationBuilder per registrare un DbContext da usare tramite il contenitore per l'inserimento delle dipendenze. Il metodo accetta un parametro del nome di connessione.

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

Per recuperare l'oggetto ExampleDbContext da un servizio:

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

Per altre informazioni sull'iniezione delle dipendenze, vedere .NET iniezione delle dipendenze.

Aggiungi il contesto del database SQL Server con arricchimento

Per arricchire il DbContext con servizi aggiuntivi, ad esempio tentativi automatici, controlli di integrità, registrazione e telemetria, chiamare il metodo EnrichSqlServerDbContext:

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

Il parametro settings è un'istanza della classe MicrosoftEntityFrameworkCoreSqlServerSettings.

Configurazione

L'integrazione .NET AspireSQL ServerEntity Framework Core offre più approcci di configurazione e opzioni per soddisfare i requisiti e le convenzioni del progetto.

Usare la stringa di connessione

Quando si usa una stringa di connessione dalla sezione di configurazione ConnectionStrings, si specifica il nome della stringa di connessione quando si chiama builder.AddSqlServerDbContext<TContext>():

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

La stringa di connessione viene recuperata dalla sezione di configurazione ConnectionStrings:

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

Il EnrichSqlServerDbContext non userà la sezione di configurazione ConnectionStrings perché prevede che un DbContext venga registrato nel momento in cui viene chiamato.

Per altre informazioni, vedere ConnectionString.

Usare i provider di configurazione

L'integrazione .NET AspireSQL ServerEntity Framework Core supporta Microsoft.Extensions.Configuration. Carica il MicrosoftEntityFrameworkCoreSqlServerSettings dai file di configurazione, ad esempio appsettings.json, utilizzando la chiave Aspire:Microsoft:EntityFrameworkCore:SqlServer. Se sono state configurate le configurazioni nella sezione Aspire:Microsoft:EntityFrameworkCore:SqlServer, è sufficiente chiamare il metodo senza passare alcun parametro.

Di seguito è riportato un esempio di file appsettings.json che configura alcune delle opzioni disponibili:

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

Utilizzare configurazioni inline

È inoltre possibile passare il delegato Action<MicrosoftEntityFrameworkCoreSqlServerSettings> per configurare alcune o tutte le opzioni direttamente nel codice, ad esempio per disattivare le metriche.

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

Configurare le connessioni multiple di DbContext

Se si desidera registrare più DbContext con una configurazione diversa, è possibile usare il nome della sezione di configurazione $"Aspire.Microsoft.EntityFrameworkCore.SqlServer:{typeof(TContext).Name}". La configurazione json sarà simile alla seguente:

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

Se si chiama il metodo AddSqlServerDbContext con parametro di tipo AnotherDbContext, verranno caricate le impostazioni dalla sezione Aspire:Microsoft:EntityFrameworkCore:SqlServer:AnotherDbContext.

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

Opzioni di configurazione

Ecco le opzioni configurabili con i valori predefiniti corrispondenti:

Controlli di salute

Per impostazione predefinita, le integrazioni di .NET.NET Aspire abilitano verifiche di integrità per tutti i servizi. Per altre informazioni, vedere panoramica delle integrazioni .NET.NET Aspire.

Per impostazione predefinita, l'integrazione .NET Aspire Sql ServerEntity Framework Core gestisce le operazioni seguenti:

• Aggiunge il DbContextHealthCheck, che chiama il metodo CanConnectAsync di EF Core. Il nome del controllo della salute è il nome del tipo TContext.
• Si integra con l'endpoint HTTP /health, che specifica che tutti i controlli di integrità registrati devono essere superati affinché l'app sia considerata pronta ad accettare traffico.

Osservabilità e telemetria

.NET .NET Aspire le integrazioni configurano automaticamente configurazioni di registrazione, traccia e metriche, talvolta note come i pilastri dell'osservabilità. Per altre informazioni sull'osservabilità e la telemetria dell'integrazione, vedere panoramica delle integrazioni .NET.NET Aspire. A seconda del servizio di backup, alcune integrazioni possono supportare solo alcune di queste funzionalità. Ad esempio, alcune integrazioni supportano la registrazione e la traccia, ma non le metriche. Le funzionalità di telemetria possono essere disabilitate anche usando le tecniche presentate nella sezione Configurazione .

Registrazione

L'integrazione .NET AspireSQL ServerEntity Framework Core usa le categorie di log seguenti:

• 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

Tracciamento

L'integrazione .NET AspireSQL ServerEntity Framework Core genererà le seguenti attività di tracciamento usando OpenTelemetry:

• "OpenTelemetry.Instrumentation.EntityFrameworkCore"

Metriche

L'integrazione .NET AspireSQL ServerEntity Framework Core genererà le metriche seguenti usando 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

Vedere anche

• Azure documentazione del database SQL
• .NET .NET Aspire integrazioni
• .NET Aspire GitHub repo