integracja .NET AspireSQL Server

Obejmuje: integrację hostingu — Client

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

Integracja hostingu modeluje serwer jako typ SQL Server i bazę danych jako typ SqlServerServerResource. Aby uzyskać dostęp do tych typów i interfejsów API, dodaj pakiet NuGet 📦Aspire.Hosting.SqlServer w projekcie hosta aplikacji .

.NET

dotnet add package Aspire.Hosting.SqlServer

PackageReference

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

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 otrzymać obiekt typu 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>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

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.

Podczas dodawania zasobu bazy danych do modelu aplikacji baza danych jest tworzona, jeśli jeszcze nie istnieje. Tworzenie bazy danych opiera się na interfejsach API do obsługi zdarzeń hosta aplikacji, w szczególności ResourceReadyEvent. Innymi słowy, gdy zasób sql jest gotowy, zostaje wywołane zdarzenie i tworzony jest zasób bazy danych.

Zasób SQL Server zawiera domyślne poświadczenia z usernamesa oraz losową wartość 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 SQL Server zasobu za pomocą skryptów bazy danych

Domyślnie, podczas dodawania SqlServerDatabaseResource, system opiera się na następującym skrypcie SQL w celu utworzenia bazy danych.

IF
(
    NOT EXISTS
    (
        SELECT 1
        FROM sys.databases
        WHERE name = @DatabaseName
    )
)
CREATE DATABASE [<QUOTED_DATABASE_NAME>];

Aby zmienić skrypt domyślny, dodaj wywołanie metody WithCreationScript do konstruktora zasobów bazy danych:

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
                 .WithLifetime(ContainerLifetime.Persistent);

var databaseName = "app-db";
var creationScript = $$"""
    IF DB_ID('{{databaseName}}') IS NULL
        CREATE DATABASE [{{databaseName}}];
    GO

    -- Use the database
    USE [{{databaseName}}];
    GO

    -- Create the todos table
    CREATE TABLE todos (
        id INT PRIMARY KEY IDENTITY(1,1),        -- Unique ID for each todo
        title VARCHAR(255) NOT NULL,             -- Short description of the task
        description TEXT,                        -- Optional detailed description
        is_completed BIT DEFAULT 0,              -- Completion status
        due_date DATE,                           -- Optional due date
        created_at DATETIME DEFAULT GETDATE()    -- Creation timestamp
    );
    GO

    """;

var db = sql.AddDatabase(databaseName)
            .WithCreationScript(creationScript);

builder.AddProject<Projects.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

W poprzednim przykładzie tworzona jest baza danych o nazwie app_db z jedną todos tabelą. Skrypt SQL jest wykonywany podczas tworzenia zasobu bazy danych. Skrypt jest przekazywany jako ciąg do WithCreationScript metody, która jest następnie wykonywana w kontekście SQL Server zasobu.

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.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

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.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

Ważny

Powiązania do danych mają ograniczoną funkcjonalność w porównaniu z woluminami, które zapewniają 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 wykorzystywane przez obraz kontenera, możesz przekazać te poświadczenia w formie parametrów. 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.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

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 poziomu narzędzi zewnętrznych, takich jak SQL Server Management Studio (SSMS) lub MSSQL dla Visual Studio Code. 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.

SQL Server Management Studio

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.

   

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

MSSQL dla Visual Studio Code

Aby nawiązać połączenie z zasobem bazy danych z programu MSSQL dla Visual Studio Code, wykonaj następujące kroki:

1. Otwórz rozszerzenie programu SQL SERVER.

2. Wybierz opcję Dodaj połączenie w obszarze POŁĄCZENIA.

   

3. Zmień typ danych wejściowych na Parametry połączenia i wklej parametry połączenia w polu parametry połączenia.

4. Wybierz i połącz z.

   

5. Po nawiązaniu połączenia możesz zobaczyć zasób bazy danych na aktywnej karcie i uruchamiać względem niego zapytania:

   

Aby uzyskać więcej informacji, zobacz MSSQL dotyczący Visual Studio Code.

Sprawdzanie stanu integracji hostingowej

Integracja hostowania SQL Server automatycznie dodaje kontrolę kondycji zasobu SQL Server. Sprawdzenie stanu weryfikuje, czy SQL Server jest uruchomione 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ą klienta .NET AspireSQL Server, zainstaluj 📦Aspire.Microsoft.Data.SqlClient pakiet NuGet w projekcie korzystającym z klienta, czyli projekcie aplikacji wykorzystującej klienta SQL Server. Integracja klienta SQL Server rejestruje wystąpienie SqlConnection, którego można użyć do interakcji z SQL Server.

.NET

dotnet add package Aspire.Microsoft.Data.SqlClient

PackageReference

<PackageReference Include="Aspire.Microsoft.Data.SqlClient"
                  Version="*" />

Dodaj klienta SQL Server

W pliku Program.cs projektu wykorzystującego klienta, wywołaj metodę rozszerzenia AddSqlServerClient na dowolnym IHostApplicationBuilder, aby zarejestrować SqlConnection do wykorzystania 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.

Dodaj klienta SQL Server z kluczem

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 za pomocą 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 klienta SQL ServerJSON, zobacz Aspire.Microsoft.Data.SqlClient/ConfigurationSchema.json.

Skorzystaj z delegatów inline

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 generuje następujące działania śledzenia przy użyciu OpenTelemetry:

• OpenTelemetry.Instrumentation.SqlClient

Wskaźniki

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ż

• Azure Baza danych SQL
• SQL Server
• .NET .NET Aspire próbne kontenery bazy danych
• .NET .NET Aspire integracje
• .NET Aspire GitHub repozytorium
• Azure SQL & SQL ServerAspire przykładów