Quickstart: Terhubung dan melakukan query dengan Microsoft.Data.SqlClient

Dalam quickstart ini, Anda membuat aplikasi konsol .NET 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 aplikasi konsol yang membuat tabel, menyisipkan dua baris dengan parameter, dan membacanya kembali.

Sepanjang perjalanan, aplikasi ini:

Membaca string koneksi-nya dari variabel lingkungan alih-alih kode sumber.
Membuka koneksi secara asinkron.
Menggunakan parameter untuk setiap nilai yang dikirimkannya ke database.
Menangani kesalahan SQL dan pembatalan.

Untuk membangun akses data yang sama ke dalam web API, lihat Quickstart: Use Microsoft. Data.SqlClient dalam aplikasi ASP.NET Core. Ini menggunakan tabel yang sama.

Prasyarat

.NET 10 SDK atau .NET SDK yang didukung versi lebih baru. SDK berjalan di Windows, Linux, dan macOS. SDK juga membangun versi .NET Framework dari contoh tersebut, yang hanya berjalan di Windows dan membutuhkan .NET Framework 4.8.1. Gunakan versi .NET untuk pengembangan baru.
Editor kode. Anda dapat menggunakan Visual Studio, Visual Studio Code, atau editor apa pun bersama dengan .NET CLI. Artikel ini menggunakan .NET CLI.
Sebuah database yang dapat Anda sambungkan. Jika Anda belum memilikinya, buat dengan menggunakan opsi berikut.

Membuat database SQL

Buat atau sambungkan ke database SQL di salah satu platform berikut:

Membuat database SQL dalam hitungan menit menggunakan portal Microsoft Azure

Izin akses basis data

Aplikasi membuat tabel sendiri, jadi Anda tidak perlu data contoh. Identitas database membutuhkan izin untuk terhubung dan membuat, menyisipkan, dan memilih dari sebuah tabel.

Untuk database SQL di Microsoft Fabric, salin nama server dan database dari item database SQL. Jangan gunakan endpoint SQL analytics. Identitas membutuhkan izin Baca item, yang dapat diberikan oleh peran workspace atau izin item. Untuk informasi lebih lanjut, lihat Autentikasi dalam database SQL. Autentikasi SQL tidak didukung.

Untuk Azure SQL Database, konfigurasikan autentikasi Microsoft Entra ID dan akses basis data.

Di folder kosong, jalankan perintah berikut:

dotnet new console --framework net10.0 --name SqlClientQuickstart
cd SqlClientQuickstart
dotnet add package Microsoft.Data.SqlClient --version 7.1.1
dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version 7.1.1

Template konsol tidak menawarkan target .NET Framework. Di folder kosong, buat proyek:

dotnet new console --framework net10.0 --name SqlClientQuickstart
cd SqlClientQuickstart

Ganti isi SqlClientQuickstart.csproj dengan file proyek ini:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net481</TargetFramework>
  </PropertyGroup>

</Project>

Kemudian tambahkan paket-paket tersebut:

dotnet add package Microsoft.Data.SqlClient --version 7.1.1
dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version 7.1.1

Paket ekstensi menyediakan mode otentikasi Microsoft Entra milik driver, seperti Direktori Aktif Default. Jika aplikasi Anda hanya menggunakan autentikasi SQL atau autentikasi terintegrasi Windows, Anda dapat menghilangkan Microsoft.Data.SqlClient.Extensions.Azure. Saat Anda menggunakan kedua paket, jaga versi mereka tetap sama. Untuk opsi instalasi lainnya, lihat Instal, perbarui, dan sebarkan Microsoft.Data.SqlClient.

Konfigurasikan koneksi

Atur SQL_CONNECTION_STRING variabel lingkungan untuk database Anda. Jangan masukkan password, access token, atau production string koneksi ke source code.

Pilih salah satu titik awal ini dan ganti placeholder-nya.

Azure SQL atau database SQL di Fabric 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

Salin nama server dan database yang persis dari database Azure SQL atau item database SQL di Fabric. Untuk PowerShell:

$env:SQL_CONNECTION_STRING = 'Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict;MultiSubnetFailover=true;Connect Timeout=30'

Untuk Bash:

export SQL_CONNECTION_STRING='Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict;MultiSubnetFailover=true;Connect Timeout=30'

Untuk aplikasi yang dihosting di Azure, berikan akses database identitas terkelolanya, lalu gunakan Authentication=Direktori Aktif Managed Identity. Untuk opsi lain, lihat autentikasi Microsoft Entra dengan Microsoft. Data.SqlClient.

SQL Server dengan autentikasi SQL

Gunakan server, port, database, dan login untuk instance SQL Server Anda. Contoh berikut adalah untuk instance pengembangan lokal yang tidak memiliki sertifikat terpercaya. Untuk PowerShell:

$env:SQL_CONNECTION_STRING = 'Server=tcp:<server>,1433;Database=<database>;User ID=<user-id>;Password=<password>;Encrypt=true;TrustServerCertificate=true;Connect Timeout=30'

Untuk Bash:

export SQL_CONNECTION_STRING='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 ini hanya dengan instance pengembangan lokal yang tidak memiliki sertifikat tepercaya. Untuk instance SQL Server bersama atau produksi, instal sertifikat yang dipercaya klien, gunakan nama server pada sertifikat tersebut, dan hapus TrustServerCertificate=true. Untuk informasi selengkapnya, lihat Enkripsi dan validasi sertifikat di Microsoft.Data.SqlClient.

Jika lingkungan Anda mendukung autentikasi terintegrasi Windows atau Kerberos, ganti User ID dan Password dengan Integrated Security=true. Untuk persyaratan pengaturan, lihat SQL Server dan autentikasi Windows.

Menambahkan kode

.NET
kerangka kerja .NET

Ganti isi Program.cs dengan kode ini:

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

string? connectionString =
    Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING");

if (string.IsNullOrWhiteSpace(connectionString))
{
    Console.Error.WriteLine(
        "Set the SQL_CONNECTION_STRING environment variable.");
    return 1;
}

using var cancellation = new CancellationTokenSource();
Console.CancelKeyPress += (_, eventArgs) =>
{
    eventArgs.Cancel = true;
    cancellation.Cancel();
};

try
{
    await using var connection = new SqlConnection(connectionString);
    await connection.OpenAsync(cancellation.Token);

    const string createTableSql = """
        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 createCommand =
        new SqlCommand(createTableSql, connection) { CommandTimeout = 30 })
    {
        await createCommand.ExecuteNonQueryAsync(cancellation.Token);
    }

    const string insertSql = """
        INSERT INTO dbo.SqlClientQuickstart (Message)
        OUTPUT INSERTED.Id
        VALUES (@message);
        """;

    string[] messages =
    [
        "Hello from Microsoft.Data.SqlClient",
        "Parameters keep values out of the SQL text"
    ];

    int firstId = 0;
    await using (var insertCommand =
        new SqlCommand(insertSql, connection) { CommandTimeout = 30 })
    {
        SqlParameter messageParameter =
            insertCommand.Parameters.Add("@message", SqlDbType.NVarChar, 200);

        foreach (string message in messages)
        {
            messageParameter.Value = message;
            int id = (int)(await insertCommand.ExecuteScalarAsync(
                cancellation.Token))!;
            Console.WriteLine($"Inserted row {id}.");
            firstId = firstId == 0 ? id : firstId;
        }
    }

    const string querySql = """
        SELECT Id, Message, CreatedAt
        FROM dbo.SqlClientQuickstart
        WHERE Id >= @firstId
        ORDER BY Id;
        """;

    await using var queryCommand =
        new SqlCommand(querySql, connection) { CommandTimeout = 30 };
    queryCommand.Parameters.Add("@firstId", SqlDbType.Int).Value = firstId;

    await using SqlDataReader reader =
        await queryCommand.ExecuteReaderAsync(cancellation.Token);

    while (await reader.ReadAsync(cancellation.Token))
    {
        Console.WriteLine(
            $"{reader.GetInt32(0)}: {reader.GetString(1)} " +
            $"(created {reader.GetDateTimeOffset(2):u})");
    }

    return 0;
}
catch (OperationCanceledException)
{
    Console.Error.WriteLine("The operation was canceled.");
    return 2;
}
catch (SqlException ex)
{
    Console.Error.WriteLine(
        $"SQL error {ex.Number}, connection {ex.ClientConnectionId}: " +
        ex.Message);
    if (ex.InnerException is not null)
    {
        Console.Error.WriteLine(ex.InnerException.Message);
    }
    return 3;
}

Ganti isi Program.cs dengan kode ini:

using System;
using System.Data;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Data.SqlClient;

class Program
{
    static async Task<int> Main()
    {
        string connectionString =
            Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING");

        if (string.IsNullOrWhiteSpace(connectionString))
        {
            Console.Error.WriteLine(
                "Set the SQL_CONNECTION_STRING environment variable.");
            return 1;
        }

        using (var cancellation = new CancellationTokenSource())
        {
            Console.CancelKeyPress += (sender, eventArgs) =>
            {
                eventArgs.Cancel = true;
                cancellation.Cancel();
            };

            try
            {
                await RunAsync(connectionString, cancellation.Token);
                return 0;
            }
            catch (OperationCanceledException)
            {
                Console.Error.WriteLine("The operation was canceled.");
                return 2;
            }
            catch (SqlException ex)
            {
                Console.Error.WriteLine(
                    $"SQL error {ex.Number}, connection {ex.ClientConnectionId}: " +
                    ex.Message);
                if (ex.InnerException != null)
                {
                    Console.Error.WriteLine(ex.InnerException.Message);
                }
                return 3;
            }
        }
    }

    static async Task RunAsync(string connectionString, CancellationToken token)
    {
        using (var connection = new SqlConnection(connectionString))
        {
            await connection.OpenAsync(token);

            const string createTableSql = @"
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;";

            using (var createCommand =
                new SqlCommand(createTableSql, connection) { CommandTimeout = 30 })
            {
                await createCommand.ExecuteNonQueryAsync(token);
            }

            const string insertSql = @"
INSERT INTO dbo.SqlClientQuickstart (Message)
OUTPUT INSERTED.Id
VALUES (@message);";

            string[] messages =
            {
                "Hello from Microsoft.Data.SqlClient",
                "Parameters keep values out of the SQL text"
            };

            int firstId = 0;
            using (var insertCommand =
                new SqlCommand(insertSql, connection) { CommandTimeout = 30 })
            {
                SqlParameter messageParameter =
                    insertCommand.Parameters.Add("@message", SqlDbType.NVarChar, 200);

                foreach (string message in messages)
                {
                    messageParameter.Value = message;
                    int id = (int)await insertCommand.ExecuteScalarAsync(token);
                    Console.WriteLine($"Inserted row {id}.");
                    firstId = firstId == 0 ? id : firstId;
                }
            }

            const string querySql = @"
SELECT Id, Message, CreatedAt
FROM dbo.SqlClientQuickstart
WHERE Id >= @firstId
ORDER BY Id;";

            using (var queryCommand =
                new SqlCommand(querySql, connection) { CommandTimeout = 30 })
            {
                queryCommand.Parameters.Add("@firstId", SqlDbType.Int).Value = firstId;

                using (SqlDataReader reader =
                    await queryCommand.ExecuteReaderAsync(token))
                {
                    while (await reader.ReadAsync(token))
                    {
                        Console.WriteLine(
                            $"{reader.GetInt32(0)}: {reader.GetString(1)} " +
                            $"(created {reader.GetDateTimeOffset(2):u})");
                    }
                }
            }
        }
    }
}

Menjalankan aplikasi

Jalankan aplikasi:

dotnet run

Saat pertama kali Anda menjalankan aplikasi, tabel kosong dan outputnya terlihat seperti ini:

Inserted row 1.
Inserted row 2.
1: Hello from Microsoft.Data.SqlClient (created 2026-10-20 20:56:10Z)
2: Parameters keep values out of the SQL text (created 2026-10-20 20:56:10Z)

Stempel waktu Anda berbeda. Setiap run berikutnya menambah dua baris lagi, sehingga ID berlanjut dari run sebelumnya.

Jika aplikasi tidak bisa terhubung, aplikasi mencetak nomor error SQL, ID koneksi klien, pesan error, dan pesan exception internal, lalu keluar dengan kode 3. Untuk kesalahan umum, lihat Pemecahan Masalah.

Cara kerja kode

OpenAsync, ReadAsync, CancellationToken, ExecuteReaderAsync, dan ExecuteScalarAsync semua menerima nilai yang sama ExecuteNonQueryAsync. Tekan Ctrl+C untuk membatalkan pekerjaan yang sedang berjalan.
Perintah sisipkan dibuat sekali dan berjalan sekali untuk setiap pesan. Hanya nilai parameter yang berubah.
Jenis dan ukuran parameter sesuai dengan kolom tabel. Parameter mengirim nilai secara terpisah dari teks SQL, yang mencegah nilai-nilai tersebut mengubah perintah dan membantu SQL Server menggunakan kembali rencana eksekusi kueri.
OUTPUT INSERTED.Id mengembalikan nilai identitas baru, sehingga ExecuteScalarAsync mengembalikan ID tanpa kueri kedua.
await using Membuang perintah, pembaca, dan koneksi, bahkan ketika terjadi pengecualian. Melepas koneksi akan mengembalikannya ke pool koneksi. Versi .NET Framework menggunakan blok using, karena tipe-tipe ini tidak mengimplementasikan IAsyncDisposable pada .NET Framework.
SqlException.Number mengidentifikasi kesalahan, dan ClientConnectionId memungkinkan Anda mencocokkan kegagalan klien dengan log sisi server. Untuk kegagalan koneksi di Linux dan macOS, penyebabnya sering kali hanya terlihat di InnerException, seperti kegagalan validasi sertifikat di balik generik error: 35 - An internal exception was caught.

Troubleshoot

Kesalahan atau gejala	Apa yang harus diperiksa	Informasi selengkapnya
`The certificate chain was issued by an authority that is not trusted`di Windows. Pada Linux dan macOS, `error: 35 - An internal exception was caught`, diikuti oleh pengecualian dalam `Certificate failed chain validation` dengan `UntrustedRoot`.	Sertifikat server tidak dipercaya oleh klien, atau nama server dalam string koneksi tidak cocok dengan sertifikat. Instal sertifikat tepercaya. Gunakan `TrustServerCertificate=true` hanya dengan instance pengembangan lokal.	Enkripsi dan validasi sertifikat di Microsoft. Data.SqlClient
`SQL error 18456` dengan `Login failed for user`	Nama pengguna, kata sandi, atau nama database salah, atau login tidak memiliki akses ke database. Untuk Microsoft Entra ID, periksa apakah identitas telah ditambahkan sebagai pengguna database.	Panduan pemecahan masalah SqlClient
`A network-related or instance-specific error occurred` dengan `error: 26`, `error: 40`, atau `The wait operation timed out`. Pada Linux dan macOS, timeout menampilkan `SQL error 258` dengan `error: 35`, diikuti oleh pengecualian dalam `The connection attempt timed out`.	Nama server atau port salah, server tidak menerima koneksi TCP jarak jauh, atau firewall memblokir port tersebut. Untuk Azure SQL, periksa aturan firewall server.	Panduan pemecahan masalah SqlClient
`System.ArgumentException: Cannot find an authentication provider for 'ActiveDirectoryDefault'`	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
`CS0234: The type or namespace name 'Data' does not exist in the namespace 'Microsoft'`	Proyek ini tidak merujuk pada paket tersebut `Microsoft.Data.SqlClient` . Jalankan `dotnet add package` perintah dari folder yang berisi file proyek.	Instal, perbarui, dan sebarkan Microsoft. Data.SqlClient
Pulihkan laporan `NU1902` atau `NU1903` untuk paket dependensi transitif	Paket yang menjadi sandaran driver memiliki peringatan yang dipublikasikan.	Tindakan ketika paket dengan kerentanan yang diketahui dilaporkan

Membersihkan sumber daya

Tabel tetap berada di database Anda setelah aplikasi ditutup. Jika Anda tidak berencana melanjutkan dengan ASP.NET Core quickstart, yang menggunakan tabel yang sama, hapus dengan alat query apa pun:

DROP TABLE IF EXISTS dbo.SqlClientQuickstart;

Kemudian hapus folder proyek. Dari folder induk, untuk PowerShell:

Remove-Item -Recurse -Force SqlClientQuickstart

Untuk Bash:

rm -rf SqlClientQuickstart

Hapus variabel lingkungan agar string koneksi tidak tetap berada di sesi shell Anda. Untuk PowerShell, jalankan Remove-Item Env:\SQL_CONNECTION_STRING. Untuk Bash, jalankan unset SQL_CONNECTION_STRING.

Gunakan pola dalam aplikasi

Pertahankan batasan ini saat Anda memindahkan sampel ke API, layanan, aplikasi desktop, atau pekerja latar belakang:

Muat informasi koneksi melalui sistem konfigurasi aplikasi.
Buka satu koneksi untuk unit kerja singkat, lalu tutup koneksi tersebut.
Teruskan CancellationToken ke pemanggilan open, command, dan reader.
Atur batas waktu perintah berdasarkan operasi.
Gunakan parameter untuk setiap nilai yang berasal dari luar pernyataan SQL.
Log SqlException.Number dan ClientConnectionId tanpa mencatat kredensial atau token akses.
Tambahkan percobaan ulang hanya untuk kegagalan sementara dan hanya ketika pengulangan operasi aman.

Langkah berikutnya

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-10-23

Quickstart: Terhubung dan melakukan query dengan Microsoft.Data.SqlClient

Prasyarat

Membuat database SQL

Izin akses basis data

Membuat proyek

Konfigurasikan koneksi

Azure SQL atau database SQL di Fabric dengan Microsoft Entra ID

SQL Server dengan autentikasi SQL

Menambahkan kode

Menjalankan aplikasi

Cara kerja kode

Troubleshoot

Membersihkan sumber daya

Gunakan pola dalam aplikasi

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: