Quickstart: Gunakan Microsoft. Data.SqlClient dalam aplikasi ASP.NET Core

Dalam quickstart ini, Anda akan membuat API minimal ASP.NET Core dengan Microsoft.Data.SqlClient 7.1.1.

Anda memulai dengan folder kosong, .NET SDK, dan database SQL Server atau Azure SQL yang dapat Anda akses dari komputer Anda. Anda menyelesaikan dengan API web yang menambahkan pesan ke tabel dan membacanya kembali berdasarkan ID.

Sepanjang perjalanan, aplikasi ini:

  • Membaca string koneksi-nya dari konfigurasi ASP.NET Core. Untuk pengembangan lokal, nilainya berasal dari user secrets, jadi tidak masuk ke folder proyek Anda.
  • Mendaftarkan kelas data dengan injeksi ketergantungan.
  • Membuka dan menutup koneksi untuk setiap permintaan, yang memungkinkan pool koneksi default menggunakan kembali koneksi fisik.
  • Meneruskan CancellationToken milik permintaan ke setiap panggilan database.

Aplikasi ini menggunakan tabel yang sama dbo.SqlClientQuickstart seperti pada Quickstart: Connect and query with Microsoft.Data.SqlClient. Kamu bisa melakukan salah satu dari dua quickstart terlebih dahulu.

Prerequisites

ASP.NET Core saat ini berjalan di .NET, bukan di .NET Framework. Untuk menggunakan driver dari .NET Framework, lihat proyek .NET Framework.

Identitas database membutuhkan izin untuk terhubung dan membuat, menyisipkan, dan memilih dari sebuah tabel.

Membuat proyek

Di folder kosong, jalankan perintah berikut:

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 menambahkan UserSecretsId ke file proyek. ASP.NET Core hanya memuat rahasia pengguna ketika aplikasi berjalan di lingkungan Development, yang merupakan default untuk dotnet run.

Paket ekstensi menyediakan mode otentikasi Microsoft Entra milik driver. Jika aplikasi Anda hanya menggunakan autentikasi SQL, Anda dapat menghilangkan .Microsoft.Data.SqlClient.Extensions.Azure Saat Anda menggunakan kedua paket, jaga versi mereka tetap sama.

Konfigurasikan koneksi

Simpan string koneksi sebagai ConnectionStrings:Quickstart di user secrets. Rahasia pengguna disimpan di profil pengguna Anda, bukan di folder proyek, jadi tidak dikomit ke kontrol versi. Jangan masukkan password atau production string koneksi di appsettings.json.

Pilih salah satu titik awal ini dan ganti placeholder-nya. Perintah dotnet user-secrets set menggunakan tanda kutip tunggal untuk PowerShell dan Bash. Di Command Prompt, gunakan tanda kutip ganda sebagai gantinya, karena Command Prompt menyimpan tanda kutip tunggal sebagai bagian dari kunci dan nilai.

Azure SQL dengan Microsoft Entra ID

Masuk dengan identitas Microsoft Entra yang memiliki akses ke database. Untuk pengembangan lokal, gunakan alat pengembang seperti Azure CLI:

az login

Kemudian simpan string koneksi. Salin nama server dan database yang tepat dari database Azure SQL. string koneksi yang sama berfungsi untuk database SQL di Microsoft Fabric ketika Anda menggunakan nama server dan database dari item database SQL, seperti yang dijelaskan dalam quickstart konsol.

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

String koneksi ini tidak mengandung rahasia. Direktori Aktif Default menggunakan sign-in developer Anda secara lokal. Saat Anda menerapkan ke Azure App Service atau Azure Container Apps, berikan akses database kepada identitas terkelola aplikasi tersebut, ubah nilainya menjadi Authentication=Direktori Aktif Managed Identity, dan tetapkan nilainya di konfigurasi host sebagai ConnectionStrings__Quickstart. Untuk opsi lain, lihat autentikasi Microsoft Entra dengan Microsoft.Data.SqlClient.

SQL Server Lokal dengan autentikasi SQL

Simpan string koneksi untuk instance pengembangan lokal yang tidak memiliki sertifikat tepercaya. Gunakan tanda kutip tunggal untuk mencegah PowerShell dan Bash memperluas karakter $ dalam kata sandi.

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 melewati validasi sertifikat server. Gunakan hanya pada instance pengembangan lokal. Untuk instance SQL Server bersama atau produksi, instal sertifikat yang dipercaya klien dan hapusTrustServerCertificate=true. Untuk informasi selengkapnya, lihat Enkripsi dan validasi sertifikat di Microsoft.Data.SqlClient.

Menambahkan kode

Ganti isi Program.cs dengan kode ini:

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;
    }
}

Menjalankan aplikasi

Mulai aplikasi di port tetap:

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

Saat startup, aplikasi membuat tabel jika tabel tersebut tidak ada. Ketika aplikasi siap, output mencakup baris-baris berikut:

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

Jika aplikasi tidak bisa mengakses database, aplikasi berhenti saat startup dengan sebuah SqlException. Untuk penyebab umum, lihat Pemecahan Masalah.

Memanggil API

Biarkan aplikasi berjalan dan buka terminal kedua. Tambahkan pesan dengan permintaan POST, lalu baca kembali dengan ID dengan permintaan GET. Jika tabel sudah memiliki baris, seperti dari quickstart konsol, ganti 1 di permintaan GET dengan nilai id yang dikembalikan oleh permintaan POST Anda.

Untuk 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 memformatkan setiap respons JSON sebagai tabel. Baris pertama adalah 201 Created respons terhadap permintaan POST, dan baris kedua adalah respons 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 menampilkan createdAt sebagai string yang dikembalikan API. PowerShell 7 mengubahnya menjadi tanggal dan waktu dalam waktu lokal, seperti 10/20/2026 7:04:43 PM.

Di Windows PowerShell, curl adalah alias untuk Invoke-WebRequest, yang tidak menerima opsi curl. Gunakan perintah PowerShell, atau jalankan curl.exe dari Command Prompt.

Untuk Command Prompt:

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

Command Prompt tidak memperlakukan tanda kutip tunggal sebagai karakter tanda kutip, sehingga body JSON menggunakan tanda kutip ganda yang di-escape dengan garis miring terbalik. Setiap perintah mencetak respons 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"}

Untuk 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"}

ID dan timestamp Anda berbeda. Jika Anda menjalankan quickstart konsol terlebih dahulu, ID akan melanjutkan penomoran dari baris-baris di quickstart tersebut. Permintaan ID yang tidak ada akan mengembalikan 404 Not Found. Pesan kosong mengembalikan 400 Bad Request.

Tekan Ctrl+C di terminal pertama untuk menghentikan aplikasi.

Cara kerja kode

  • Aplikasi ini mendaftarkan MessageStore sebagai singleton. Ini hanya menyimpan string koneksi, yang dibacanya dari IConfiguration satu kali. Itu tidak dapat mempertahankan koneksi.
  • Setiap metode membuat sebuah SqlConnection, membukanya, menjalankan satu perintah, dan membuangnya dengan await using. Menutup mengembalikan koneksi fisik ke pool koneksi, dan permintaan berikutnya menggunakannya kembali. Connection pooling sudah aktif secara default, jadi Anda tidak perlu mengonfigurasinya. Untuk opsi penyetelan, lihat SQL Server connection pooling dengan Microsoft.Data.SqlClient.
  • ASP.NET Core mengikat CancellationToken parameter tersebut ke permintaan. Jika klien terputus, token membatalkan operasi pembukaan, perintah, dan pembacaan.
  • Parameter @message dan @id sesuai dengan tipe dan ukuran kolom. API memeriksa panjang pesan sebelum mengirim nilai ke database.
  • OUTPUT INSERTED.Id, INSERTED.Message, INSERTED.CreatedAt mengembalikan baris yang dimasukkan, termasuk ID dan timestamp yang dihasilkan server, tanpa kueri kedua.
  • Di lingkungan lain, ASP.NET Core membaca kunci yang sama ConnectionStrings:Quickstart dari variabel lingkungan, seperti ConnectionStrings__Quickstart, atau dari penyedia konfigurasi lain, seperti Azure Key Vault.

Troubleshoot

Kesalahan atau gejala Apa yang harus diperiksa Informasi selengkapnya
Set the ConnectionStrings:Quickstart configuration value. Aplikasi tidak menemukan string koneksi. Jalankan dotnet user-secrets list di folder proyek, dan periksa apakah aplikasi berjalan di lingkungan Development. penyimpanan rahasia aplikasi yang aman dalam pengembangan di ASP.NET Core
System.ArgumentException: Cannot find an authentication provider for 'ActiveDirectoryDefault' saat startup string koneksi menggunakan mode autentikasi Direktori Aktif, tetapi proyek tidak merujuk Microsoft.Data.SqlClient.Extensions.Azure. Tambahkan paket dengan versi yang sama dengan Microsoft.Data.SqlClient. Autentikasi Microsoft Entra dipindahkan ke paket ekstensi di 7.0
SqlException saat startup Aplikasi tidak bisa terhubung atau membuat tabel tersebut. Nomor error mengidentifikasi penyebabnya, seperti 18456 untuk login yang gagal. Memecahkan masalah di panduan memulai cepat konsol
415 Unsupported Media Type Permintaan tidak menetapkan Content-Type: application/json. Referensi cepat API minimal
Cannot bind parameter 'Headers' Anda menjalankan perintah curl di Windows PowerShell, yang dalam hal ini menjalankan curlInvoke-WebRequest. Gunakan perintah PowerShell dalam Call the API. Invoke-RestMethod
''' is an invalid start of a value Anda menjalankan perintah Bash curl di Command Prompt, yang mengirimkan tanda kutip tunggal sebagai bagian dari isi permintaan. Gunakan perintah Command Prompt di Call the API. Panggil API

Membersihkan sumber daya

Hapus tabel dengan alat query apa pun:

DROP TABLE IF EXISTS dbo.SqlClientQuickstart;

Hapus string koneksi yang tersimpan. Dari folder proyek, jalankan:

dotnet user-secrets clear

Kemudian hapus folder proyek. Dari folder induk, jalankan perintah berikut di PowerShell:

Remove-Item -Recurse -Force SqlClientWebQuickstart

Untuk Bash:

rm -rf SqlClientWebQuickstart

Langkah berikutnya

  • Terakhir diperbarui pada