Hızlı başlangıç: Microsoft.Data.SqlClient ile bağlantı kur ve sorgu yap

Bu hızlı başlangıçta, Microsoft.Data.SqlClient 7.1.1 ile bir .NET konsol uygulaması oluşturursunuz.

Boş bir klasörle, .NET SDK'sıyla ve bilgisayarınızdan ulaşabileceğiniz bir SQL Server veya Azure SQL veritabanı ile başlarsınız. Bir konsol uygulaması ile bitiriyorsunuz, bir tablo oluşturuyor, parametrelerle iki satır ekliyor ve onları geri okuyor.

Bu sırada, uygulama:

Kaynak kod yerine bağlantı dizesi'ini bir ortam değişkeninden okur.
Bir bağlantıyı eşzamansız olarak açar.
Veritabanına gönderdiği her değer için parametreler kullanır.
SQL hataları ve iptal işlemlerini yönetir.

Aynı veri erişimini bir web API'sine eklemek için bkz. Hızlı başlangıç: Bir ASP.NET Core uygulamasında Microsoft.Data.SqlClient kullanma Aynı tabloyu kullanıyor.

Prerequisites

.NET 10 SDK veya daha yeni desteklenen bir .NET SDK. SDK Windows, Linux ve macOS üzerinde çalışıyor. SDK ayrıca yalnızca Windows'ta çalışan ve .NET Framework 4.8.1 gerektiren .NET Framework sürümünü de oluşturur. Yeni geliştirme için .NET sürümünü kullanın.
Bir kod düzenleyici. Visual Studio, Visual Studio Code veya herhangi bir düzenleyiciyi .NET CLI ile birlikte kullanabilirsiniz. Bu makale .NET CLI kullanmaktadır.
Bağlanabileceğiniz bir veritabanı. Eğer bir tane yoksa, aşağıdaki seçenekleri kullanarak bir tane oluşturun.

SQL veritabanı oluşturma

Aşağıdaki platformlardan birinde bir SQL veritabanı oluşturun veya bağlanın:

Azure portalını kullanarak dakikalar içinde SQL veritabanı oluşturma

Veritabanı izinleri

Uygulama kendi tablosunu oluşturuyor, yani örnek veriye ihtiyacınız yok. Veritabanı kimliği, bağlanmak ve bir tablo oluşturmak, bir tabloya veri eklemek ve tablodan veri seçmek için izin gerektirir.

Microsoft Fabric'te SQL veritabanı için, sunucu ve veritabanı isimlerini SQL veritabanı öğesinden kopyalayın. SQL analitik uç noktasını kullanmayın. Kimliğin, bir çalışma alanı rolü veya öğe izniyle sağlanabilen Öğeyi okuma iznine sahip olması gerekir. Daha fazla bilgi için SQL veritabanında Doğrulama bölümünü inceleyebilirsiniz. SQL kimlik doğrulaması desteklenmiyor.

Azure SQL Veritabanı için, Microsoft Entra ID kimlik doğrulamasını ve veritabanı erişimini yapılandırın.

Boş bir klasörde şu komutları çalıştırın:

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

Konsol şablonu .NET Framework hedefleri sunmuyor. Boş bir klasörde projeyi oluşturun:

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

İçeriğini SqlClientQuickstart.csproj bu proje dosyasıyla değiştirin:

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

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

</Project>

Sonra paketleri ekleyin:

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

Uzantı paketi, sürücünün Microsoft Entra kimlik doğrulama modlarını sağlar, örneğin Active Directory Default. Uygulamanız yalnızca SQL kimlik doğrulama veya Windows tümleşik kimlik doğrulaması kullanıyorsa, Microsoft.Data.SqlClient.Extensions.Azure öğesini atlayabilirsiniz. Her iki paketi de kullandığınızda, versiyonlarını aynı tutun. Diğer kurulum seçenekleri için bkz. Microsoft.Data.SqlClient kurulumu, güncellenmesi ve dağıtımı.

Bağlantıyı yapılandırma

Veritabanınız için ortam değişkenini ayarlayın SQL_CONNECTION_STRING . Kaynak koduna parola, erişim belirteci veya üretim bağlantı dizesi koymayın.

Bu başlangıç noktalarından birini seçin ve yer tutucuları değiştirin.

Azure SQL veya Microsoft Entra ID ile Fabric'teki SQL veritabanı

Veritabanına erişimi olan bir Microsoft Entra kimliğiyle giriş yapın. Yerel geliştirme için, Azure CLI gibi bir geliştirici aracı kullanın:

az login

Azure SQL veritabanından veya Fabric'teki SQL veritabanı öğesinden tam sunucu ve veritabanı isimlerini kopyalayın. PowerShell için:

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

Bash için:

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

Azure'da barındırılan bir uygulama için, yönetilen kimliğine veritabanı erişimi verin ve ardından Authentication=Active Directory Managed Identity kullanın. Diğer seçenekler için bkz. Microsoft Entra kimlik doğrulaması ile Microsoft.Data.SqlClient.

SQL Server ile SQL doğrulama

SQL Server örneğiniz için sunucu, port, veritabanı ve giriş bilgilerini kullanın. Aşağıdaki örnek, güvenilir sertifikası olmayan yerel bir geliştirme örneği içindir. PowerShell için:

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

Bash için:

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 sunucu sertifikası doğrulamasını atlar. Sadece güvenilir sertifikası olmayan yerel bir geliştirme örneğiyle kullanın. Paylaşılan veya üretim SQL Server örnekleri için, istemcinin güvendiği bir sertifika yükleyin, bu sertifikadaki sunucu adını kullanın ve TrustServerCertificate=true öğesini kaldırın. Daha fazla bilgi için bkz. Microsoft.Data.SqlClient Şifreleme ve sertifika doğrulaması.

Eğer ortamınız Windows entegre kimlik doğrulaması veya Kerberos destekliyorsa, User ID ve Password ile Integrated Security=truedeğiştirin. Kurulum gereksinimleri için bkz. SQL Server ve Windows kimlik doğrulaması.

Kodu ekle

.NET
.NET Framework

öğesinin içeriğini Program.cs şu kodla değiştirin:

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

öğesinin içeriğini Program.cs şu kodla değiştirin:

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

Uygulamayı çalıştırma

Uygulamayı çalıştırın:

dotnet run

Uygulamayı ilk çalıştırdığınızda tablo boş ve çıktı şöyle görünüyor:

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)

Zaman damgalarınız farklı. Her sonraki denemede iki satır daha eklenir, böylece ID'ler son çalıştırmadaki son değerden devam eder.

Eğer uygulama bağlanamazsa, SQL hata numarasını, istemci bağlantı kimliğini, hata mesajını ve iç istisna mesajını yazdırır, ardından kod 3 ile çıkar. Yaygın hatalar için bkz. Sorun Giderme.

Kod nasıl çalışır?

OpenAsync, ExecuteNonQueryAsync, ExecuteScalarAsync, ExecuteReaderAsync ve ReadAsync hepsi aynı CancellationToken alır. Devam eden çalışmayı iptal etmek için Ctrl+C tuşlarına basın.
Insert komutu bir kez oluşturulur ve her mesaj için bir kez çalışır. Sadece parametre değeri değişir.
Parametre türleri ve boyutları tablo sütunlarıyla eşleşir. Parametreler, SQL metninden ayrı olarak değerler gönderir; bu da bu değerlerin komutu değiştirmesini engeller ve SQL Server'ın sorgu planlarını yeniden kullanmasına yardımcı olur.
OUTPUT INSERTED.Id yeni kimlik değerini döndürür, böylece ExecuteScalarAsync ikinci bir sorgu olmadan kimlik değerini döndürür.
await using komutları, okuyucuyu ve bağlantıyı, istisna olsa bile elden çıkarır. Bağlantının kapatılması, onu bağlantı havuzuna geri gönderir. .NET Framework sürümü using bloklar kullanır çünkü bu türler .NET Framework'te IAsyncDisposable uygulamadığı için.
SqlException.Number hatayı tespit eder ve ClientConnectionId istemci hatasını sunucu tarafı loglarıyla eşleştirmenize olanak tanır. Linux ve macOS'ta bağlantı hatalarında neden genellikle yalnızca InnerException içinde olur; örneğin genel error: 35 - An internal exception was caught’nin arkasında gizlenen bir sertifika doğrulama hatası olabilir.

Troubleshoot

Hata veya belirti	Denetlenecek şeyler	Daha fazla bilgi
`The certificate chain was issued by an authority that is not trusted`Windows'ta. Linux ve macOS'ta, `error: 35 - An internal exception was caught`, `UntrustedRoot` ile `Certificate failed chain validation` iç istisnası tarafından izlenir.	Sunucu sertifikası istemci tarafından güvenilir bulunmuyor ya da bağlantı dizesi'deki sunucu adı sertifikayla eşleşmiyor. Güvenilir bir sertifika yükleyin. Yalnızca yerel geliştirme ortamıyla `TrustServerCertificate=true` kullanın.	Microsoft'ta şifreleme ve sertifika doğrulaması. Data.SqlClient
`SQL error 18456` ile `Login failed for user`	Kullanıcı adı, şifre veya veritabanı adı yanlış ya da girişin veritabanına erişimi yok. Microsoft Entra ID için, kimliğin veritabanı kullanıcısı olarak eklendiğinden emin olun.	SqlClient sorun giderme kılavuzu
`A network-related or instance-specific error occurred` ile `error: 26`, `error: 40`, veya `The wait operation timed out`. Linux ve macOS'ta, bir zaman aşımı `SQL error 258` ile `error: 35`gösterilir, ardından iç istisna `The connection attempt timed out`gelir.	Sunucu adı veya portu yanlış, sunucu uzak TCP bağlantılarını kabul etmiyor ya da bir güvenlik duvarı portu engelliyor. Azure SQL için, sunucu firewall kurallarına bak.	SqlClient sorun giderme kılavuzu
`System.ArgumentException: Cannot find an authentication provider for 'ActiveDirectoryDefault'`	Bağlantı dizesi `Active Directory` kimlik doğrulama modunu kullanır, ancak proje `Microsoft.Data.SqlClient.Extensions.Azure` başvurusuna sahip değil. Paketi aynı sürümle ekle.`Microsoft.Data.SqlClient`	Microsoft Entra doğrulaması 7.0'da bir uzantı paketine taşınıyor
`CS0234: The type or namespace name 'Data' does not exist in the namespace 'Microsoft'`	Proje, `Microsoft.Data.SqlClient` paketine referans vermiyor. Proje dosyasını içeren klasörden `dotnet add package` komutunu çalıştırın.	Microsoft.Data.SqlClient'ı yükleyin, güncelleyin ve dağıtın
Geçişli bir paket için raporları geri yükleyin `NU1902` veya `NU1903`	Sürücünün bağımlı olduğu bir paketin yayımlanmış bir uyarısı vardır.	Bilinen zafiyetli paketler rapor edildiğinde yapılan işlemler

Kaynakları temizle

Tablo, uygulama çıktıktan sonra veritabanınızda kalır. Aynı tabloyu kullanan ASP.NET Core hızlı başlangıcıyla devam etmeyi planlamıyorsanız, herhangi bir sorgu aracıyla silin:

DROP TABLE IF EXISTS dbo.SqlClientQuickstart;

Sonra proje klasörünü sil. PowerShell için ana klasörden:

Remove-Item -Recurse -Force SqlClientQuickstart

Bash için:

rm -rf SqlClientQuickstart

Ortam değişkenini temizleyin ki bağlantı dizesi shell oturumunuzda kalmasın. PowerShell için Remove-Item Env:\SQL_CONNECTION_STRING komutunu çalıştırın. Bash için unset SQL_CONNECTION_STRING komutunu çalıştırın.

Deseni bir uygulamada kullanın

Örneği API, servis, masaüstü uygulaması veya arka plan çalışanına taşırken şu sınırları koruyun:

Bağlantı bilgilerini uygulamanın yapılandırma sistemi üzerinden yükleyin.
Kısa bir iş birimi için bir bağlantı açın, ardından kapatın.
CancellationToken öğesini open, command ve reader çağrılarından geçirin.
İşleme göre komut zaman aşımlarını ayarlayın.
SQL ifadesi dışından gelen her değer için parametreler kullanın.
Kimlik bilgilerini veya erişim belirteçlerini günlüğe kaydetmeden, SqlException.Number ve ClientConnectionId öğelerini günlüğe kaydedin.
Yalnızca geçici hatalar için ve yalnızca işlemi yinelemenin güvenli olduğu durumlarda yeniden deneme ekleyin.

Sonraki Adımlar

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Son güncelleştirme: 2026-10-23

Hızlı başlangıç: Microsoft.Data.SqlClient ile bağlantı kur ve sorgu yap

Prerequisites

SQL veritabanı oluşturma

Veritabanı izinleri

Projeyi oluşturma

Bağlantıyı yapılandırma

Azure SQL veya Microsoft Entra ID ile Fabric'teki SQL veritabanı

SQL Server ile SQL doğrulama

Kodu ekle

Uygulamayı çalıştırma

Kod nasıl çalışır?

Troubleshoot

Kaynakları temizle

Deseni bir uygulamada kullanın

Sonraki Adımlar

Geri Bildirim

Ek kaynaklar