Szybki start: Użyj Microsoft. Data.SqlClient w aplikacji ASP.NET Core

W tym szybkim starcie budujesz minimalne API ASP.NET Core z Microsoft.Data.SqlClient 7.1.1.

Zaczynasz od pustego folderu, SDK .NET oraz bazy danych SQL Server lub Azure SQL, do której masz dostęp z komputera. Kończysz z webowym API, które dodaje wiadomość do tabeli i odczytuje ją z powrotem według ID.

Po drodze aplikacja:

  • Odczytuje swój parametry połączenia z konfiguracji ASP.NET Core. W przypadku lokalnego rozwoju wartość pochodzi z sekretów użytkownika, więc nie trafia do folderu projektu.
  • Rejestruje klasę danych za pomocą wstrzyknięcia zależności.
  • Otwiera i zamyka połączenie dla każdego żądania, co pozwala domyślnej puli połączeń ponownie użyć połączeń fizycznych.
  • Przekazuje CancellationToken żądania do każdego wywołania bazy danych.

Aplikacja korzysta z tej samej dbo.SqlClientQuickstart tabeli co Quickstart: Połącz się i wykonaj zapytanie za pomocą Microsoft.Data.SqlClient. Możesz najpierw zrobić którykolwiek z tych Quickstartów.

Prerequisites

Obecny ASP.NET Core działa na .NET, a nie na .NET Framework. Aby użyć sterownika z platformy .NET Framework, zobacz projekty programu .NET Framework.

Tożsamość bazy danych musi mieć uprawnienia do nawiązywania połączenia oraz do tworzenia tabeli, wstawiania do niej danych i wybierania z niej danych.

Tworzenie projektu

W pustym folderze wykonaj następujące polecenia:

dotnet new web --framework net10.0 --name SqlClientWebQuickstart
cd SqlClientWebQuickstart
dotnet add package Microsoft.Data.SqlClient --version 7.1.1
dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version 7.1.1
dotnet user-secrets init

dotnet user-secrets init dodaje UserSecretsId do pliku projektu. ASP.NET Core ładuje sekrety użytkownika tylko wtedy, gdy aplikacja działa w środowisku Development, co jest domyślne dla dotnet run.

Pakiet rozszerzenia zapewnia tryby uwierzytelniania sterownika Microsoft Entra. Jeśli Twoja aplikacja używa wyłącznie uwierzytelniania SQL, możesz pominąć Microsoft.Data.SqlClient.Extensions.Azure. Gdy używasz obu pakietów, utrzymuj te same wersje.

Konfiguruj połączenie

Zapisz parametry połączenia jako ConnectionStrings:Quickstart w user secrets. Sekrety użytkownika są przechowywane w Twoim profilu użytkownika, a nie w folderze projektu, więc nie są zatwierdzane do kontroli wersji. Nie wpisuj hasła ani produkcyjnych parametrów połączenia w appsettings.json.

Wybierz jeden z tych punktów wyjścia i zastąp symbole zastępcze. Polecenia dotnet user-secrets set używają pojedynczych cudzysłowów w programach PowerShell i Bash. W wierszu poleceń używaj podwójnych cudzysłowów, ponieważ wiersz poleceń przechowuje pojedyncze cudzysłowy jako część klucza i wartości.

Azure SQL z Microsoft Entra ID

Zaloguj się za pomocą tożsamości Microsoft Entra, która ma dostęp do bazy danych. Do lokalnego rozwoju korzystaj z narzędzia deweloperskiego, takiego jak Azure CLI:

az login

Następnie zapisz parametry połączenia. Skopiuj dokładnie takie same nazwy serwera i bazy danych z bazy danych Azure SQL. Ten sam parametry połączenia działa dla bazy danych SQL w Microsoft Fabric, gdy używasz nazw serwera i bazy danych z elementu bazy danych SQL, jak opisano w szybkim uruchomieniu konsoli.

dotnet user-secrets set 'ConnectionStrings:Quickstart' 'Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict;Connect Timeout=30'

Te parametry połączenia nie zawierają wpisu tajnego. Active Directory Default używa lokalnie logowania dewelopera. Gdy wdrażasz do Azure App Service lub Azure Container Apps, przyznaj zarządzanej tożsamości aplikacji dostęp do bazy danych, zmień wartość na Authentication=Active Directory Managed Identity i ustaw ją w konfiguracji hosta jako ConnectionStrings__Quickstart. Inne opcje można znaleźć w artykule Microsoft Entra authentication with Microsoft. Data.SqlClient.

Lokalny SQL Server z uwierzytelnianiem SQL

Zapisz parametry połączenia dla lokalnej instancji deweloperskiej, która nie posiada zaufanego certyfikatu. Używaj pojedynczych cudzysłowów, aby zapobiec rozwijaniu znaku $ w haśle przez PowerShell i Bash.

dotnet user-secrets set 'ConnectionStrings:Quickstart' 'Server=tcp:<server>,1433;Database=<database>;User ID=<user-id>;Password=<password>;Encrypt=true;TrustServerCertificate=true;Connect Timeout=30'

Caution

TrustServerCertificate=true pomija walidację certyfikatów serwera. Używaj go tylko z lokalną instancją deweloperską. W przypadku współdzielonych lub produkcyjnych instancji SQL Server zainstaluj certyfikat, któremu klient ufa, i usuń TrustServerCertificate=true. Aby uzyskać więcej informacji, zapoznaj się z Encryption and certificate validation in Microsoft.Data.SqlClient.

Dodawanie kodu

Zastąp zawartość Program.cs tego kodu następującym kodem:

using System.Data;
using Microsoft.Data.SqlClient;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<MessageStore>();

var app = builder.Build();

await app.Services.GetRequiredService<MessageStore>()
    .EnsureTableAsync(app.Lifetime.ApplicationStopping);

app.MapPost("/messages", async (
    NewMessage input, MessageStore store, CancellationToken cancellationToken) =>
{
    if (string.IsNullOrWhiteSpace(input.Text) || input.Text.Length > 200)
    {
        return Results.BadRequest("Text must be 1 to 200 characters.");
    }

    Message message = await store.AddAsync(input.Text, cancellationToken);
    return Results.Created($"/messages/{message.Id}", message);
});

app.MapGet("/messages/{id:int}", async (
    int id, MessageStore store, CancellationToken cancellationToken) =>
    await store.GetAsync(id, cancellationToken) is Message message
        ? Results.Ok(message)
        : Results.NotFound());

app.Run();

record NewMessage(string Text);

record Message(int Id, string Text, DateTimeOffset CreatedAt);

sealed class MessageStore(IConfiguration configuration)
{
    private readonly string _connectionString =
        configuration.GetConnectionString("Quickstart")
        ?? throw new InvalidOperationException(
            "Set the ConnectionStrings:Quickstart configuration value.");

    public async Task EnsureTableAsync(CancellationToken cancellationToken)
    {
        const string sql = """
            IF OBJECT_ID(N'dbo.SqlClientQuickstart', N'U') IS NULL
            BEGIN
                CREATE TABLE dbo.SqlClientQuickstart
                (
                    Id int IDENTITY(1, 1) PRIMARY KEY,
                    Message nvarchar(200) NOT NULL,
                    CreatedAt datetimeoffset NOT NULL
                        CONSTRAINT DF_SqlClientQuickstart_CreatedAt
                        DEFAULT sysdatetimeoffset()
                );
            END;
            """;

        await using var connection = new SqlConnection(_connectionString);
        await connection.OpenAsync(cancellationToken);
        await using var command =
            new SqlCommand(sql, connection) { CommandTimeout = 30 };
        await command.ExecuteNonQueryAsync(cancellationToken);
    }

    public async Task<Message> AddAsync(
        string text, CancellationToken cancellationToken)
    {
        const string sql = """
            INSERT INTO dbo.SqlClientQuickstart (Message)
            OUTPUT INSERTED.Id, INSERTED.Message, INSERTED.CreatedAt
            VALUES (@message);
            """;

        await using var connection = new SqlConnection(_connectionString);
        await connection.OpenAsync(cancellationToken);
        await using var command =
            new SqlCommand(sql, connection) { CommandTimeout = 30 };
        command.Parameters.Add("@message", SqlDbType.NVarChar, 200).Value = text;

        await using SqlDataReader reader =
            await command.ExecuteReaderAsync(cancellationToken);
        await reader.ReadAsync(cancellationToken);
        return new Message(
            reader.GetInt32(0), reader.GetString(1), reader.GetDateTimeOffset(2));
    }

    public async Task<Message?> GetAsync(
        int id, CancellationToken cancellationToken)
    {
        const string sql = """
            SELECT Id, Message, CreatedAt
            FROM dbo.SqlClientQuickstart
            WHERE Id = @id;
            """;

        await using var connection = new SqlConnection(_connectionString);
        await connection.OpenAsync(cancellationToken);
        await using var command =
            new SqlCommand(sql, connection) { CommandTimeout = 30 };
        command.Parameters.Add("@id", SqlDbType.Int).Value = id;

        await using SqlDataReader reader =
            await command.ExecuteReaderAsync(cancellationToken);
        return await reader.ReadAsync(cancellationToken)
            ? new Message(
                reader.GetInt32(0), reader.GetString(1), reader.GetDateTimeOffset(2))
            : null;
    }
}

Uruchom aplikację

Uruchom aplikację na stałym porcie:

dotnet run --urls http://localhost:5000

Przy starcie aplikacja tworzy tabelę, jeśli nie istnieje. Gdy aplikacja jest gotowa, wyjście zawiera następujące linie:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5000
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development

Jeśli aplikacja nie może dotrzeć do bazy danych, zatrzymuje się przy starcie z komunikatem SqlException. Aby poznać najczęstsze przyczyny, zobacz Rozwiązywanie problemów.

Wywołaj API

Zostaw aplikację włączoną i otwórz drugi terminal. Dodaj wiadomość z żądaniem POST, a następnie odczytaj ją z powrotem według ID za pomocą żądania GET. Jeśli tabela już ma wiersze, na przykład z szybkiego startu konsoli, zamień 1 w żądaniu GET na id, które zwraca Twoje żądanie POST.

Dla PowerShell:

Invoke-RestMethod -Method Post -Uri http://localhost:5000/messages -ContentType application/json -Body (@{ text = 'Hello from ASP.NET Core' } | ConvertTo-Json)
Invoke-RestMethod http://localhost:5000/messages/1

PowerShell formatuje każdą odpowiedź JSON jako tabelę. Pierwszy wiersz to 201 Created odpowiedź na żądanie POST, a drugi wiersz to odpowiedź GET:

id text                    createdAt
-- ----                    ---------
 1 Hello from ASP.NET Core 2026-10-21T00:04:43.3588978+00:00
 1 Hello from ASP.NET Core 2026-10-21T00:04:43.3588978+00:00

Windows PowerShell 5.1 pokazuje createdAt jako ciąg znaków zwracany przez interfejs API. PowerShell 7 konwertuje go na datę w czasie lokalnym, na przykład 10/20/2026 7:04:43 PM.

W Windows PowerShell curl jest aliasem polecenia Invoke-WebRequest, które nie akceptuje opcji curl. Użyj poleceń PowerShell lub uruchom curl.exe z wiersza poleceń.

W wierszu polecenia:

curl -X POST http://localhost:5000/messages -H "Content-Type: application/json" -d "{\"text\":\"Hello from ASP.NET Core\"}"
curl http://localhost:5000/messages/1

Wiersz poleceń nie traktuje pojedynczych cudzysłowów jako znaków cytowania, więc treść JSON używa podwójnych cudzysłowów poprzedzonych ukośnikami odwrotnymi. Każde polecenie drukuje odpowiedź JSON:

{"id":1,"text":"Hello from ASP.NET Core","createdAt":"2026-10-21T00:05:15.4936763+00:00"}
{"id":1,"text":"Hello from ASP.NET Core","createdAt":"2026-10-21T00:05:15.4936763+00:00"}

Dla Bash:

curl -X POST http://localhost:5000/messages -H "Content-Type: application/json" -d '{"text":"Hello from ASP.NET Core"}'
curl http://localhost:5000/messages/1

{"id":1,"text":"Hello from ASP.NET Core","createdAt":"2026-10-20T20:44:17.8634925+00:00"}
{"id":1,"text":"Hello from ASP.NET Core","createdAt":"2026-10-20T20:44:17.8634925+00:00"}

Twoje identyfikatory i znaczniki czasowe się różnią. Jeśli najpierw uruchomiłeś krótki przewodnik w konsoli, identyfikatory są kontynuowane po wierszach z tego przewodnika. Żądanie identyfikatora, który nie istnieje, zwraca 404 Not Found. Pusta wiadomość powoduje zwrócenie 400 Bad Request.

Naciśnij Ctrl+C w pierwszym terminalu, aby zatrzymać aplikację.

Jak działa kod

  • Aplikacja rejestruje MessageStore jako singleton. Zawiera tylko parametry połączenia, który odczytuje z IConfiguration tylko raz. Nie utrzymuje żadnego połączenia.
  • Każda metoda tworzy połączenie SqlConnection, otwiera je, wykonuje jedno polecenie i zamyka je za pomocą await using. Zwolnienie zwraca fizyczne połączenie do puli połączeń, a następne żądanie ponownie je używa. Pula połączeń jest domyślnie włączona, więc nie musisz jej konfigurować. Opcje dostrajania znajdziesz w artykule SQL Server connection pooling with Microsoft. Data.SqlClient.
  • ASP.NET Core wiąże parametr CancellationToken z danym żądaniem. Jeśli klient się rozłączy, token anuluje otwarcie, polecenie i odczyt.
  • Parametry @message i @id odpowiadają typom i rozmiarom kolumn. API weryfikuje długość wiadomości, zanim wyśle wartość do bazy danych.
  • OUTPUT INSERTED.Id, INSERTED.Message, INSERTED.CreatedAt zwraca wstawiony wiersz, w tym wygenerowany przez serwer ID i znacznik czasu, bez drugiego zapytania.
  • W innych środowiskach ASP.NET Core odczytuje ten sam ConnectionStrings:Quickstart klucz ze zmiennych środowiskowych, takich jak ConnectionStrings__Quickstart, lub z innego dostawcy konfiguracji, takiego jak Azure Key Vault.

Troubleshoot

Błąd lub objaw Co należy sprawdzić? Więcej informacji
Set the ConnectionStrings:Quickstart configuration value. Aplikacja nie znalazła parametru połączenia. Uruchom dotnet user-secrets list w folderze projektu i sprawdź, czy aplikacja działa w środowisku Development. Bezpieczne przechowywanie tajnych danych aplikacji w środowisku deweloperskim w ASP.NET Core
System.ArgumentException: Cannot find an authentication provider for 'ActiveDirectoryDefault' przy uruchamianiu Ciąg parametrów połączenia używa trybu uwierzytelniania Active Directory, ale projekt nie zawiera odwołania do Microsoft.Data.SqlClient.Extensions.Azure. Dodaj pakiet z tą samą wersją co Microsoft.Data.SqlClient. Uwierzytelnianie Microsoft Entra przechodzi do pakietu rozszerzeniowego w wersji 7.0
SqlException przy uruchamianiu Aplikacja nie mogła się połączyć ani utworzyć tabeli. Numer błędu wskazuje przyczynę, na przykład 18456 oznacza nieudane logowanie. Rozwiązywanie problemów w przewodniku Szybki start konsoli
415 Unsupported Media Type Żądanie nie ustawia Content-Type: application/json. Krótkie informacje o minimalnych interfejsach API
Cannot bind parameter 'Headers' Uruchomiłeś polecenie curl w programie Windows PowerShell, gdzie curl uruchamia Invoke-WebRequest. Użyj poleceń programu PowerShell w sekcji Call the API. Invoke-RestMethod
''' is an invalid start of a value Uruchomiłeś komendę Bash curl w wierszu poleceń, która wysyła pojedyncze apostrofy jako część ciała. Użyj poleceń wiersza poleceń w sekcji Call the API. Wywołaj API

Uprzątnij zasoby

Usuń tabelę za pomocą dowolnego narzędzia do zapytań:

DROP TABLE IF EXISTS dbo.SqlClientQuickstart;

Usuń zapisany parametry połączenia. Z folderu projektu uruchom:

dotnet user-secrets clear

Następnie usuń folder projektu. Z folderu nadrzędnego wykonaj następujące polecenie w PowerShell:

Remove-Item -Recurse -Force SqlClientWebQuickstart

Dla Bash:

rm -rf SqlClientWebQuickstart

Następne kroki

  • Ostatnia aktualizacja o