Condividi tramite

integrazione di .NET AspireSQL Server

  • Articolo

Include:integrazione dell'hosting e Client integrazione

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

Integrazione dell'hosting

L'integrazione di hosting SQL Server modella il server come tipo SqlServerServerResource e il database come tipo 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

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

Aggiungere la risorsa SQL Server e la risorsa di database

Chiamare AddSqlServer nel progetto host dell'app per aggiungere e restituire un generatore di risorse SQL Server. Collegare una chiamata al costruttore della risorsa restituita a AddDatabaseper aggiungere la risorsa di 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...

Nota

L'avvio del contenitore SQL Server è lento, quindi è consigliabile usare una durata permanente per evitare riavvii non necessari. Per ulteriori informazioni, vedere la durata della vita delle risorse del contenitore.

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.

Suggerimento

Se preferisci connetterti a un SQL Serveresistente, chiama AddConnectionString. Per altre informazioni, vedere Fare riferimento alle risorse esistenti.

Aggiungi risorsa SQL Server con 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 è montato sul percorso /var/opt/mssql nel contenitore SQL Server e, quando non viene specificato un parametro name, il nome viene generato casualmente. Per altre informazioni sui volumi di dati e sui motivi per cui sono preferiti rispetto a associare i montaggi, vedere la documentazione Docker: Volumi.

Avvertimento

La password viene archiviata nel volume di dati. Quando si usa un volume di dati e se la password viene modificata, non funzionerà fino a quando non si elimina il volume.

Aggiungere SQL Server risorsa con il montaggio dell'associazione 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...

Importante

I bind dei dati hanno funzionalità limitate rispetto ai volumi , che offrono prestazioni, portabilità e sicurezza migliori, rendendoli più adatti per gli ambienti di produzione. Tuttavia, i montaggi di associazione consentono l'accesso diretto e la modifica diretta dei file nel sistema host, ideale per lo sviluppo e il test in cui sono necessarie modifiche in tempo reale.

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. L'associazione dati viene montata al C:\SqlServer\Data su Windows (o al percorso /SqlServer/Data su Unix) nel computer 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.NET Aspire, è possibile accedere da strumenti esterni alle risorse del database del server, 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: 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.

Per connettersi alla risorsa di database da SQL Server Management Studio, seguire questa procedura:

  1. Aprire SSMS.

  2. Nella finestra di dialogo Connetti a Server, selezionare la scheda Parametri di Connessione Aggiuntivi.

  3. Incolla la stringa di connessione nel campo parametri di connessione aggiuntivi e seleziona Connetti.

    SQL Server Management Studio: collegarsi alla finestra di dialogo Server.

  4. Se sei connesso, è possibile visualizzare la risorsa di database nel Esplora oggetti:

    SQL Server Management Studio: connesso al database.

Per altre informazioni, vedere SQL Server Management Studio: Connettersi a un server.

Verifica dell'integrità delle integrazioni di hosting

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

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

integrazione Client

Per iniziare a usare l'integrazione client .NET AspireSQL Server, installare il 📦Aspire. Microsoft.Data.SqlClient pacchetto NuGet nel progetto che utilizza il client, ovvero il progetto per l'applicazione che usa il client SQL Server. L'integrazione client SQL Server registra un'istanza di SqlConnection che è possibile usare per interagire con SQL Server.

dotnet add package Aspire.Microsoft.Data.SqlClient

Aggiungere SQL Server client

Nel file Program.cs del progetto che usa il client chiamare il metodo di estensione AddSqlServerClient in qualsiasi IHostApplicationBuilder per registrare un SqlConnection da usare tramite il contenitore di inserimento delle dipendenze. Il metodo accetta un parametro del nome di connessione.

builder.AddSqlServerClient(connectionName: "database");

Suggerimento

Il parametro connectionName deve corrispondere al nome usato quando si aggiunge la risorsa di database SQL Server nel progetto host dell'app. In altre parole, quando si chiama AddDatabase e si specifica un nome di database lo stesso nome deve essere usato quando si chiama AddSqlServerClient. Per altre informazioni, vedere Aggiungere SQL Server risorsa e risorsa di database.

È quindi possibile recuperare l'istanza di SqlConnection usando l'iniezione delle dipendenze. Ad esempio, per recuperare la connessione da un servizio di esempio:

public class ExampleService(SqlConnection connection)
{
    // Use connection...
}

Per ulteriori informazioni sull'iniezione di dipendenze, vedere .NET iniezione di dipendenze.

Aggiungere un client con chiave SQL Server

In alcuni casi potrebbe essere necessario registrare più istanze di SqlConnection con nomi di connessione diversi. Per registrare i client SQL Server con chiave, chiamare il metodo AddKeyedSqlServerClient:

builder.AddKeyedSqlServerClient(name: "mainDb");
builder.AddKeyedSqlServerClient(name: "loggingDb");

Importante

Quando si usano i servizi con chiave, è previsto che la risorsa SQL Server sia configurata con due database denominati, uno per il mainDb e uno per l'loggingDb.

È quindi possibile recuperare le istanze di SqlConnection attraverso l'iniezione delle dipendenze. Ad esempio, per recuperare la connessione da un servizio di esempio:

public class ExampleService(
    [FromKeyedServices("mainDb")] SqlConnection mainDbConnection,
    [FromKeyedServices("loggingDb")] SqlConnection loggingDbConnection)
{
    // Use connections...
}

Per altre informazioni sui servizi con chiave, vedere .NET inserimento delle dipendenze: Servizi con chiave.

Configurazione

L'integrazione .NET AspireSQL Server offre più opzioni per configurare la connessione in base ai requisiti e alle convenzioni del progetto.

Usare una stringa di connessione

Quando si usa una stringa di connessione dalla sezione di configurazione ConnectionStrings, è possibile specificare il nome della stringa di connessione quando si chiama il metodo AddSqlServerClient:

builder.AddSqlServerClient(connectionName: "sql");

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

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

Per altre informazioni su come formattare questa stringa di connessione, vedere ConnectionString.

Usare i provider di configurazione

L'integrazione .NET AspireSQL Server supporta Microsoft.Extensions.Configuration. Carica il MicrosoftDataSqlClientSettings dalla configurazione usando la chiave Aspire:Microsoft:Data:SqlClient. Il frammento di codice seguente è un esempio di un file appsettings.json che configura alcune delle opzioni:

{
  "Aspire": {
    "Microsoft": {
      "Data": {
        "SqlClient": {
          "ConnectionString": "YOUR_CONNECTIONSTRING",
          "DisableHealthChecks": false,
          "DisableMetrics": true
        }
      }
    }
  }
}

Per lo schema completo JSON di integrazione client SQL Server, vedere Aspire. Microsoft.Data.SqlClient/ConfigurationSchema.json.

Usare delegati inline

È anche possibile passare il delegato Action<MicrosoftDataSqlClientSettings> configureSettings per configurare alcune o tutte le opzioni inline, ad esempio per disabilitare i controlli di integrità dal codice:

builder.AddSqlServerClient(
    "database",
    static settings => settings.DisableHealthChecks = true);

Client controlli di integrità dell'integrazione

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

Integrazione .NET AspireSQL Server:

  • Aggiunge il controllo di integrità quando MicrosoftDataSqlClientSettings.DisableHealthChecks è false, che tenta di connettersi al SQL Server.
  • Si integra con l'endpoint HTTP /health, che richiede che tutti i controlli di integrità registrati siano superati perché l'app sia considerata pronta per accettare traffico.

Osservabilità e telemetria

.NET .NET Aspire le integrazioni impostano automaticamente le configurazioni di registrazione, tracciamento 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 Server attualmente non attiva i log di default a causa delle limitazioni del Microsoft.Data.SqlClient.

Tracciamento

L'integrazione .NET AspireSQL Server emette le seguenti attività di tracciamento usando OpenTelemetry:

  • OpenTelemetry.Instrumentation.SqlClient

Metriche

L'integrazione .NET AspireSQL Server genererà le metriche seguenti usando OpenTelemetry:

  • Microsoft.Data.SqlClient.EventSource
    • active-hard-connections
    • hard-connects
    • hard-disconnects
    • active-soft-connects
    • soft-connects
    • soft-disconnects
    • number-of-non-pooled-connections
    • number-of-pooled-connections
    • number-of-active-connection-pool-groups
    • number-of-inactive-connection-pool-groups
    • number-of-active-connection-pools
    • number-of-inactive-connection-pools
    • number-of-active-connections
    • number-of-free-connections
    • number-of-stasis-connections
    • number-of-reclaimed-connections

Vedere anche