integratie van .NET AspireSQL ServerEntity Framework Core

Artikel
12/18/2024

omvat:hosting-integratie en 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 modellt 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>()
       .WithReference(db)
       .WaitFor(db);

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

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. 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 het geheime archief 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.

Fooi

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

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.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

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

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 Docker documentatie: Volumesvoor meer informatie over gegevensvolumes en redenen waarom ze de voorkeur hebben boven koppelingen.

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.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

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

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.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

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

Zie Externe parametersvoor meer informatie over het opgeven van parameters.

Verbinding maken met databasebronnen

Wanneer de .NET Aspire app-host wordt uitgevoerd, kunnen de databasebronnen van de serverworden geopend vanuit externe hulpprogramma's, zoals SQL Server Management Studio (SSMS) of Azure Data Studio. 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
Azure Data Studio

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 van Client

Installeer de 📦Aspireom aan de slag te gaan met de .NET AspireSQL ServerEntity Framework Core-integratie. Microsoft.EntityFrameworkCore.SqlServer NuGet-pakket in het clientverbruikende project, dat wil gezegd het project voor de toepassing die gebruikmaakt van de SQL ServerEntity Framework Coreclient.

.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 uw clientverbruikende project de AddSqlServerDbContext-extensiemethode aan op elke IHostApplicationBuilder om een DbContext te registreren voor gebruik via de container voor afhankelijkheidsinjectie. De methode gebruikt een verbindingsnaamparameter.

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

Tip

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.

SQL Server databasecontext toevoegen met verrijking

Als u de DbContext wilt verrijken met aanvullende services, zoals automatische nieuwe pogingen, statuscontroles, logboekregistratie en telemetrie, roept u de methode EnrichSqlServerDbContext aan:

builder.EnrichSqlServerDbContext<ExampleDbContext>(
    connectionName: "database",
    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 configuratie van de json 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

Alle .NET.NET Aspire-integraties schakelen standaard -statuscontroles in voor alle services. Zie .NET.NET Aspire overzicht van integratiesvoor meer informatie.

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

Hiermee wordt de DbContextHealthChecktoegevoegd, waarmee de CanConnectAsync methode van EF Corewordt 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

Delen via