integracja .NET AspireSQL ServerEntity Framework Core

Artykuł
01/23/2025

obejmuje:integrację hostingu oraz Client integrację

SQL Server to system zarządzania relacyjnymi bazami danych opracowany przez firmę Microsoft. Integracja .NET AspireSQL ServerEntity Framework Core umożliwia łączenie się z istniejącymi wystąpieniami SQL Server lub tworzenie nowych wystąpień z .NET przy użyciu obrazu kontenera mcr.microsoft.com/mssql/server.

Integracja hostingu

SQL Server hostowanie modeli integracji serwera jako typu SqlServerServerResource i bazy danych jako typu SqlServerDatabaseResource. Aby uzyskać dostęp do tych typów i interfejsów API, dodaj 📦Aspire.Hosting.SqlServer pakiet NuGet do projektu hosta aplikacji .

.NET interfejsu wiersza polecenia
PackageReference

dotnet add package Aspire.Hosting.SqlServer

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

Aby uzyskać więcej informacji, zobacz dotnet add package lub Zarządzaj zależnościami pakietów w .NET aplikacjach.

Dodawanie zasobu SQL Server i zasobu bazy danych

W projekcie hosta aplikacji wywołaj AddSqlServer, aby dodać i zwrócić konstruktor zasobów SQL Server. Połącz wywołanie zwróconego konstruktora zasobów do AddDatabaseaby dodać zasób bazy danych 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...

Notatka

Kontener SQL Server działa wolno, więc najlepiej użyć trwałego okresu istnienia, aby uniknąć niepotrzebnych ponownych uruchomień. Aby uzyskać więcej informacji, zobacz okres istnienia zasobu kontenera.

Gdy .NET.NET Aspire dodaje obraz kontenera do hosta aplikacji, jak pokazano w poprzednim przykładzie z obrazem mcr.microsoft.com/mssql/server, tworzy nowe wystąpienie SQL Server na komputerze lokalnym. Odwołanie do konstruktora zasobów SQL Server (zmiennej sql) służy do dodawania bazy danych. Baza danych nosi nazwę database, a następnie jest dodawana do ExampleProject. Zasób SQL Server zawiera poświadczenia domyślne z usernamesa i losową password wygenerowaną przy użyciu metody CreateDefaultPasswordParameter.

Po uruchomieniu hosta aplikacji hasło jest przechowywane w sekretnym repozytorium hosta aplikacji. Jest on dodawany do sekcji Parameters, na przykład:

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

Nazwa parametru jest sql-password, ale naprawdę wystarczy sformatować nazwę zasobu z sufiksem -password. Aby uzyskać więcej informacji, zobacz Bezpieczne przechowywanie tajnych informacji aplikacji podczas tworzenia w ASP.NET Core oraz Dodaj zasób SQL Server z parametrami.

Metoda WithReference konfiguruje połączenie w ExampleProject o nazwie database.

Napiwek

Jeśli wolisz nawiązać połączenie z istniejącym SQL Server, wywołaj AddConnectionString zamiast tego. Aby uzyskać więcej informacji, zobacz Dokumentacja istniejących zasobów.

Dodawanie zasobu SQL Server z woluminem danych

Aby dodać wolumin danych do zasobu SQL Server, wywołaj metodę WithDataVolume w zasobie 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...

Wolumin danych służy do przechowywania SQL Server danych poza okresem życia kontenera. Wolumin danych jest instalowany w ścieżce /var/opt/mssql w kontenerze SQL Server, a gdy nie podano parametru name, nazwa jest generowana losowo. Aby uzyskać więcej informacji na temat woluminów danych i szczegółów na temat tego, dlaczego są preferowane w przypadku instalacji wiązania, zobacz Docker dokumentacji: woluminy.

Ostrzeżenie

Hasło jest przechowywane w woluminie danych. W przypadku korzystania z woluminu danych i zmiany hasła nie będzie działać, dopóki wolumin nie zostanie usunięty.

Dodaj zasób SQL Server z montowaniem powiązania danych

Aby dodać powiązanie danych z zasobem SQL Server, użyj metody 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...

Ważny

Instalacje powiązane danych mają ograniczoną funkcjonalność w porównaniu z woluminami , co zapewnia lepszą wydajność, przenośność i bezpieczeństwo, co czyni je bardziej odpowiednimi dla środowisk produkcyjnych. Jednak montowanie wiązania umożliwia bezpośredni dostęp i modyfikację plików w systemie hosta, co jest idealne do rozwoju i testowania, gdzie potrzebne są zmiany w czasie rzeczywistym.

Wiązania danych polegają na systemie plików maszyny hosta, aby utrwalić dane SQL Server między ponownymi uruchomieniami kontenera. Punkt montowania danych jest zamontowany w C:\SqlServer\Data na Windowsie (lub /SqlServer/Data na Unix) na ścieżce na maszynie hosta w kontenerze SQL Server. Aby uzyskać więcej informacji na temat instalacji powiązań danych, zobacz Docker docs: Bind mounts.

Dodawanie zasobu SQL Server z parametrami

Jeśli chcesz bezpośrednio podać hasło używane przez obraz kontenera, możesz podać te informacje uwierzytelniające jako parametry. Rozważmy następujący przykład alternatywny:

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

Aby uzyskać więcej informacji na temat udostępniania parametrów, zobacz Parametry zewnętrzne.

Łączenie z zasobami bazy danych

Po uruchomieniu hosta aplikacji .NET.NET Aspire można uzyskać dostęp do zasobów bazy danych serwera z narzędzi zewnętrznych, takich jak SQL Server Management Studio (SSMS) lub Azure Data Studio. Łańcuch połączenia dla zasobu bazy danych jest dostępny w zmiennych środowiskowych zasobów zależnych i można go uzyskać za pośrednictwem tablicy .NET.NET Aspire: Szczegóły zasobu. Zmienna środowiskowa nosi nazwę ConnectionStrings__{name}, gdzie {name} jest nazwą zasobu bazy danych, w tym przykładzie jest to database. Użyj parametrów połączenia, aby nawiązać połączenie z zasobem bazy danych z narzędzi zewnętrznych. Załóżmy, że masz bazę danych o nazwie todos z jedną tabelą dbo.Todos.

SQL Server Management Studio
Azure Data Studio

Aby nawiązać połączenie z zasobem bazy danych z programu SQL Server Management Studio, wykonaj następujące kroki:

Otwórz program SSMS.
W oknie dialogowym Połącz z Server wybierz kartę Dodatkowe parametry połączenia.
Wklej parametry połączenia w polu Dodatkowe parametry połączenia i wybierz pozycję Połącz.
Jeśli masz połączenie, możesz zobaczyć zasób bazy danych w eksploratorze obiektów :

Aby uzyskać więcej informacji, zobacz SQL Server Management Studio: Nawiązywanie połączenia z serwerem.

Sprawdzanie poprawności integracji hostingu

Integracja hostowania SQL Server automatycznie dodaje kontrolę kondycji zasobu SQL Server. Kontrola stanu sprawdza, czy SQL Server jest uruchomiona i czy można nawiązać z nim połączenie.

Integracja hostingu opiera się na pakiecie NuGet 📦 AspNetCore.HealthChecks.SqlServer.

Client integracja

Aby rozpocząć pracę z integracją .NET AspireSQL ServerEntity Framework Core, zainstaluj 📦Aspire.Microsoft.EntityFrameworkCore.SqlServer pakiet NuGet w projekcie korzystającym z klienta, czyli projekt aplikacji używającej klienta SQL ServerEntity Framework Core.

.NET interfejs wiersza poleceń
PackageReference

dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer

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

Aby uzyskać więcej informacji, zobacz dotnet add package lub Zarządzaj zależnościami pakietów w .NET aplikacjach.

Dodaj kontekst bazy danych SQL Server

W pliku Program.cs projektu wykorzystującego klienta wywołaj metodę rozszerzenia AddSqlServerDbContext na dowolnym IHostApplicationBuilder, aby za pomocą kontenera wstrzykiwania zależności zarejestrować DbContext do użycia. Metoda przyjmuje parametr nazwy połączenia.

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

Napiwek

Parametr connectionName musi być zgodny z nazwą używaną podczas dodawania zasobu bazy danych SQL Server w projekcie hosta aplikacji. Innymi słowy podczas wywoływania AddDatabase i podania nazwy database tej samej nazwy należy użyć podczas wywoływania AddSqlServerDbContext. Aby uzyskać więcej informacji, zobacz Dodawanie zasobu SQL Server i zasobu bazy danych.

Aby pobrać obiekt ExampleDbContext z usługi:

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

Aby uzyskać więcej informacji na temat wstrzykiwania zależności, zapoznaj się z .NET wstrzykiwanie zależności.

Dodaj kontekst bazy danych SQL Server z wzbogaceniem

Aby wzbogacić DbContext o dodatkowe usługi, takie jak automatyczne ponawianie prób, kontrole kondycji, rejestrowanie i telemetria, wywołaj metodę EnrichSqlServerDbContext:

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

Parametr settings jest wystąpieniem klasy MicrosoftEntityFrameworkCoreSqlServerSettings.

Konfiguracja

Integracja .NET AspireSQL ServerEntity Framework Core zapewnia wiele metod konfiguracji i opcji spełniających wymagania i konwencje projektu.

Używanie parametrów połączenia

W przypadku używania parametrów połączenia z sekcji konfiguracji ConnectionStrings należy podać nazwę parametrów połączenia podczas wywoływania builder.AddSqlServerDbContext<TContext>():

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

Parametry połączenia są pobierane z sekcji konfiguracji ConnectionStrings:

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

EnrichSqlServerDbContext nie będzie korzystać z sekcji konfiguracji ConnectionStrings, ponieważ oczekuje ona zarejestrowania DbContext w momencie jego wywołania.

Aby uzyskać więcej informacji, zobacz ConnectionString.

Korzystanie z dostawców konfiguracji

Integracja .NET AspireSQL ServerEntity Framework Core obsługuje Microsoft.Extensions.Configuration. Ładuje MicrosoftEntityFrameworkCoreSqlServerSettings z plików konfiguracji, takich jak appsettings.json przy użyciu klucza Aspire:Microsoft:EntityFrameworkCore:SqlServer. Jeśli konfiguracje zostały skonfigurowane w sekcji Aspire:Microsoft:EntityFrameworkCore:SqlServer, możesz wywołać metodę bez przekazywania żadnego parametru.

Poniżej przedstawiono przykład pliku appsettings.json, który konfiguruje niektóre z dostępnych opcji:

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

Korzystanie z wbudowanych konfiguracji

Możesz również przekazać delegata Action<MicrosoftEntityFrameworkCoreSqlServerSettings>, aby skonfigurować niektóre lub wszystkie opcje wbudowane, na przykład aby wyłączyć metryki:

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

Konfigurowanie wielu połączeń DbContext

Jeśli chcesz zarejestrować więcej niż jedną DbContext w innej konfiguracji, możesz użyć nazwy sekcji konfiguracji $"Aspire.Microsoft.EntityFrameworkCore.SqlServer:{typeof(TContext).Name}". Konfiguracja json wygląda następująco:

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

Następnie wywołanie metody AddSqlServerDbContext przy użyciu parametru typu AnotherDbContext spowoduje załadowanie ustawień z sekcji Aspire:Microsoft:EntityFrameworkCore:SqlServer:AnotherDbContext.

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

Opcje konfiguracji

Poniżej przedstawiono opcje konfigurowalne z odpowiednimi wartościami domyślnymi:

Nazwa	Opis
`ConnectionString`	Parametry połączenia bazy danych SQL Server do nawiązania połączenia.
`DbContextPooling`	Wartość logiczna wskazująca, czy kontekst bazy danych będzie przechowywany w puli, czy jawnie tworzony przy każdym żądaniu.
`MaxRetryCount`	Maksymalna liczba ponownych prób. Wartość domyślna to 6, ustaw ją na 0, aby wyłączyć mechanizm ponawiania prób.
`DisableHealthChecks`	Wartość logiczna wskazująca, czy sprawdzanie kondycji bazy danych jest wyłączone, czy nie.
`DisableTracing`	Wartość logiczna wskazująca, czy śledzenie OpenTelemetry jest wyłączone, czy nie.
`DisableMetrics`	Wartość logiczna wskazująca, czy metryki OpenTelemetry są wyłączone, czy nie.
`Timeout`	Czas w sekundach oczekiwania na wykonanie polecenia.

Kontrole kondycji

Domyślne .NET.NET Aspire integracje włączają sprawdzanie kondycji dla wszystkich usług. Aby uzyskać więcej informacji, zobacz omówienie integracji .NET.NET Aspire.

Domyślnie integracja .NET Aspire Sql ServerEntity Framework Core obsługuje następujące elementy:

Dodaje DbContextHealthCheck, który wywołuje metodę CanConnectAsyncEF Core. Nazwa sprawdzania kondycji to nazwa typu TContext.
Integruje się z punktem końcowym HTTP /health, który określa, że wszystkie zarejestrowane testy kondycji muszą zostać pomyślnie wykonane, aby aplikacja została uznana za gotową do przyjmowania ruchu.

Obserwowanie i telemetria

.NET .NET Aspire integracje automatycznie konfigurują rejestrowanie, śledzenie i metryki, które są czasami nazywane filarami obserwowalności. Aby uzyskać więcej informacji na temat możliwości obserwacji integracji i telemetrii, zobacz omówienie integracji .NET.NET Aspire. W zależności od usługi pomocniczej niektóre integracje mogą obsługiwać tylko niektóre z tych funkcji. Na przykład niektóre integracje obsługują rejestrowanie i śledzenie, ale nie metryki. Funkcje telemetrii można również wyłączyć przy użyciu technik przedstawionych w sekcji konfiguracji .

Rejestrowanie

Integracja .NET AspireSQL ServerEntity Framework Core używa następujących kategorii dzienników:

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

Śledzenie

Integracja .NET AspireSQL ServerEntity Framework Core spowoduje emitowanie następujących działań śledzenia przy użyciu OpenTelemetry:

"OpenTelemetry.Instrumentation.EntityFrameworkCore"

Metryki

Integracja .NET AspireSQL ServerEntity Framework Core będzie emitować następujące metryki przy użyciu 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

Udostępnij za pośrednictwem