Udostępnij za pośrednictwem

integracja .NET AspireSQL Server

  • Artykuł

obejmuje:integrację hostingu i Client integrację

SQL Server to system zarządzania relacyjnymi bazami danych opracowany przez firmę Microsoft. Integracja .NET AspireSQL Server 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

Model integracji hostingu SQL Server przedstawia server jako typ SqlServerServerResource, a bazę danych jako typ SqlServerDatabaseResource. Aby uzyskać dostęp do tych typów i interfejsów API, dodaj pakiet NuGet 📦Aspire.Hosting.SqlServer w projekcie hosta aplikacji .

dotnet add package Aspire.Hosting.SqlServer

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

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 z AddDatabase, aby 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, na komputerze lokalnym tworzy się nowe wystąpienie SQL Server. Referencja do twojego konstruktora zasobów SQL Server (zmiennej sql) jest używana 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 magazynie tajnym 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 danych aplikacji w trakcie tworzenia w ASP.NET Core oraz Dodanie zasobu 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 odnośnik do 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...

Wolumen danych jest używany do przechowywania danych SQL Server poza cyklem życia jego 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 i szczegóły dotyczące tego, dlaczego są preferowane nad instalacjami wiązań, zobacz dokumentację Docker: 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 wykorzystaniem montowania powiązania danych

Aby dodać powiązanie montowania danych do zasobu SQL Server, wywołaj metodę 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 wiązania umożliwiają 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.

Punkty montowania powiązań danych polegają na systemie plików maszyny hosta w celu utrwalania danych SQL Server podczas ponownych uruchomień kontenera. Powiązanie danych jest zamontowane na ścieżce C:\SqlServer\Data w systemie Windows (lub /SqlServer/Data w Unix) na maszynie hosta w kontenerze SQL Server. Aby uzyskać więcej informacji na temat powiązań montowania danych, zapoznaj się z dokumentacją Docker: Bind mounts.

Dodawanie zasobu SQL Server z parametrami

Jeśli chcesz jawnie podać hasło używane przez obraz kontenera, możesz podać te poświadczenia 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 Aspire można uzyskać dostęp do zasobów bazy danych serverz narzędzi zewnętrznych, takich jak SQL Server Management Studio (SSMS) lub Azure Data Studio. Parametry połączenia w zasobie bazy danych są dostępne w zmiennych środowiskowych zasobów zależnych i można je uzyskać za pośrednictwem pulpitu nawigacyjnego .NET.NET Aspire, w sekcji 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 ciągu połączenia, aby połączyć się z zasobem bazy danych za pomocą narzędzi zewnętrznych. Załóżmy, że masz bazę danych o nazwie todos z jedną tabelą dbo.Todos.

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

  1. Otwórz program SSMS.

  2. W oknie dialogowym Połącz z Server wybierz kartę Dodatkowe Parametry Połączenia.

  3. Wklej ciąg połączenia w polu Dodatkowe parametry połączenia i wybierz Połącz.

    SQL Server Management Studio: Okno dialogowe połączenia z Server.

  4. Jeśli masz połączenie, możesz zobaczyć zasób bazy danych w eksploratorze obiektów :

    SQL Server Management Studio: połączono z bazą danych.

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

Sprawdzanie stanu integracji hostingowej

Integracja hostowania SQL Server automatycznie dodaje kontrolę kondycji zasobu SQL Server. Kontrola kondycji 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.

integracja Client

Aby rozpocząć pracę z integracją .NET AspireSQL Serverclient, zainstaluj 📦Aspire. Microsoft.Data.SqlClient pakiet NuGet w projekcie korzystającym z client, czyli projektu dla aplikacji korzystającej z SQL Serverclient. Integracja SQL Serverclient rejestruje wystąpienie SqlConnection, którego można użyć do interakcji z SQL Server.

dotnet add package Aspire.Microsoft.Data.SqlClient

Dodaj SQL Serverclient

W pliku Program.cs projektu korzystającego z clientwywołaj metodę rozszerzenia AddSqlServerClient na dowolnym IHostApplicationBuilder, aby zarejestrować SqlConnection do użycia za pośrednictwem kontenera wstrzykiwania zależności. Metoda przyjmuje parametr nazwy połączenia.

builder.AddSqlServerClient(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 należy użyć tej samej nazwy podczas wywoływania AddSqlServerClient. Aby uzyskać więcej informacji, zobacz Dodaj zasób SQL Server i zasób bazy danych.

Następnie można pobrać wystąpienie SqlConnection używając wstrzykiwania zależności. Aby na przykład pobrać połączenie z przykładowej usługi:

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

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

Zakodowane SQL Serverclient

Mogą wystąpić sytuacje, w których chcesz zarejestrować wiele wystąpień SqlConnection z różnymi nazwami połączeń. Aby zarejestrować klientów kluczowych SQL Server, wywołaj metodę AddKeyedSqlServerClient.

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

Ważny

W przypadku korzystania z usług kluczowych oczekuje się, że zasób SQL Server skonfigurował dwie nazwane bazy danych, jedną dla mainDb i jedną dla loggingDb.

Następnie można pobrać instancje SqlConnection przy użyciu wstrzykiwania zależności. Aby na przykład pobrać połączenie z przykładowej usługi:

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

Aby uzyskać więcej informacji na temat usług kluczowych, zobacz .NET wstrzykiwanie zależności: usługi kluczowe.

Konfiguracja

Integracja .NET AspireSQL Server udostępnia wiele opcji konfigurowania połączenia na podstawie wymagań i konwencji projektu.

Używanie parametrów połączenia

W przypadku używania parametrów połączenia z sekcji konfiguracji ConnectionStrings podczas wywoływania metody AddSqlServerClient można podać nazwę parametrów połączenia:

builder.AddSqlServerClient(connectionName: "sql");

Następnie parametry połączenia są pobierane z sekcji konfiguracji ConnectionStrings:

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

Aby uzyskać więcej informacji na temat formatowania tych parametrów połączenia, zobacz ConnectionString.

Korzystanie z dostawców konfiguracji

Integracja .NET AspireSQL Server obsługuje Microsoft.Extensions.Configuration. Ładuje MicrosoftDataSqlClientSettings z konfiguracji przy użyciu klucza Aspire:Microsoft:Data:SqlClient. Poniższy fragment kodu to przykład pliku appsettings.json, który konfiguruje niektóre opcje:

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

Aby uzyskać pełny schemat integracji SQL ServerclientJSON, zobacz Aspire. Microsoft.Data.SqlClient/ConfigurationSchema.json.

Używanie delegatów wbudowanych

Możesz również przekazać delegata Action<MicrosoftDataSqlClientSettings> configureSettings, aby skonfigurować niektóre lub wszystkie opcje wbudowane, na przykład w celu wyłączenia kontroli kondycji z kodu:

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

Client kontrole stanu integracji

Domyślnie .NET.NET Aspire integracje pozwalają na monitorowanie kondycji dla wszystkich usług. Aby uzyskać więcej informacji, zobacz omówienie integracji .NET.NET Aspire.

Integracja .NET AspireSQL Server:

  • Dodaje sprawdzenie stanu, gdy MicrosoftDataSqlClientSettings.DisableHealthChecks jest false, i podejmowana jest próba nawiązania połączenia z SQL Server.
  • Integruje się z punktem końcowym HTTP /health, który określa, że wszystkie zarejestrowane kontrole kondycji muszą przejść, aby aplikacja mogła zostać 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 .

Prace leśne

Integracja .NET AspireSQL Server obecnie nie włącza rejestrowania domyślnie z powodu ograniczeń Microsoft.Data.SqlClient.

Śledzenie

Integracja .NET AspireSQL Server emituje następujące działania śledzenia przy użyciu OpenTelemetry:

  • OpenTelemetry.Instrumentation.SqlClient

Metryki

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

Zobacz też