Gunakan Microsoft. Data.SqlClient dalam aplikasi .NET

Dalam quickstart ini, Anda membuat aplikasi konsol .NET yang:

• Membaca string koneksi-nya dari lingkungan alih-alih kode sumber.
• Membuka koneksi secara asinkron.
• Membuat tabel jika tabel tersebut tidak ada.
• Menyisipkan baris dengan perintah yang diparameterkan.
• Membaca baris dengan kueri yang diparameterkan.
• Menangani kesalahan SQL dan pembatalan.

Contoh menggunakan Microsoft. Data.SqlClient 7.0.3, rilis stabil saat ini.

Prasyarat

Anda membutuhkan .NET 10 SDK atau .NET SDK yang didukung lebih baru.

Membuat database SQL

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

Azure SQL Database

Membuat database SQL dalam hitungan menit menggunakan portal Microsoft Azure

Database SQL di Fabric

Memuat data sampel AdventureWorks di database SQL Anda di Microsoft Fabric

Microsoft SQL Server

Menginstal SQL Server dari Wizard Instalasi

Database sampel AdventureWorks

Kontainer SQL Server

Membuat kontainer SQL Server di Docker

Membuat kontainer SQL Server dengan sqlcmd

Membuat kontainer SQL Server dengan ekstensi MSSQL untuk VS Code

Quickstart membuat tabel sendiri, jadi data sampel tidak diperlukan. 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.

Membuat proyek

Jalankan perintah ini:

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

Paket ekstensi menyediakan mode otentikasi Microsoft Entra ID yang disediakan oleh driver. Aplikasi yang hanya menggunakan autentikasi terintegrasi Windows atau autentikasi SQL dapat menghilangkan Microsoft.Data.SqlClient.Extensions.Azure.

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.

Fabric SQL atau Azure SQL dengan autentikasi tanpa kata sandi

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

az login

Salin nama server dan database yang tepat dari item database SQL di Fabric atau database Azure SQL. 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 dan terhubung ke Azure SQL, berikan akses database identitas terkelolanya, lalu gunakan Authentication=Direktori Aktif Managed Identity. Untuk opsi Microsoft Entra ID lainnya, lihat autentikasi Microsoft Entra ID.

SQL Server melalui TCP

Gunakan server, port, database, dan login dari SQL Server yang sudah ada atau panduan pengaturan yang Anda ikuti. Contoh autentikasi SQL berikut adalah untuk kontainer pengembangan lokal. 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.

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

Menambahkan kode aplikasi

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

    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);
        """;

    int insertedId;
    using (var insertCommand =
        new SqlCommand(insertSql, connection) { CommandTimeout = 30 })
    {
        insertCommand.Parameters.Add(
            new SqlParameter("@message", SqlDbType.NVarChar, 200)
            {
                Value = "Hello from Microsoft.Data.SqlClient"
            });

        object? result =
            await insertCommand.ExecuteScalarAsync(cancellation.Token);
        insertedId = Convert.ToInt32(result);
    }

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

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

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

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

    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);
    return 3;
}

Jenis dan ukuran parameter sesuai dengan kolom tabel. Parameter mengirim nilai secara terpisah dari teks SQL, yang mencegah nilai-nilai tersebut mengubah sintaks perintah dan membantu SQL Server menggunakan kembali rencana query.

await using melepaskan reader dan koneksi bahkan saat terjadi pengecualian. Menutup koneksi akan mengembalikan koneksi fisiknya ke kumpulan koneksi alih-alih membiarkan satu koneksi tetap terbuka selama masa aktif aplikasi.

Jalankan aplikasi

Jalankan aplikasi:

dotnet run

Aplikasi mencetak baris yang disisipkannya:

1: Hello from Microsoft.Data.SqlClient at <timestamp>

Nilai identitas dan timestamp berbeda di setiap database.

Jika koneksi gagal, gunakan nomor kesalahan SQL dan ID koneksi klien dari output kesalahan. Periksa nama server dan database, akses jaringan, izin database, pengaturan otentikasi, dan konfigurasi sertifikat. Jangan tambahkan TrustServerCertificate=true ke koneksi Azure SQL atau produksi sebagai perbaikan koneksi umum.

Gunakan pola dalam aplikasi

Pertahankan batasan berikut 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

• Pilih dan buat string koneksi.
• Konfigurasikan perilaku koneksi.
• Kelola siklus hidup koneksi.
• Gunakan pooling koneksi SQL Server.
• Konfigurasikan logika percobaan ulang.
• Gunakan perintah dan parameter.