Bir .NET uygulamasında Microsoft.Data.SqlClient kullanın

Bu hızlı başlangıçta, aşağıdaki bir .NET konsol uygulaması oluşturuyorsunuz:

Kaynak kodu yerine ortamdan bağlantı dizesi'i okur.
Bir bağlantıyı eşzamansız olarak açar.
Tablo mevcut değilse oluşturur.
Parametrizlenmiş komutla bir satır ekler.
Parametreli sorgu içeren satırları okur.
SQL ve iptal hatalarını yönetir.

Örnek, güncel kararlı sürüm olan Microsoft.Data.SqlClient 7.0.3'ü kullanır.

Prerequisites

.NET 10 SDK veya daha sonra desteklenen .NET SDK'ya ihtiyacınız var.

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

Hızlı başlat kendi tablosunu oluşturuyor, bu yüzden örnek veri gerekmiyor. 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.

Projeyi oluşturma

Şu komutları çalıştırın:

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

Uzantı paketi, sürücü tarafından sağlanan Microsoft Entra ID kimlik doğrulama modları sağlar. Yalnızca Windows tümleşik kimlik doğrulaması veya SQL kimlik doğrulaması kullanan bir uygulama Microsoft.Data.SqlClient.Extensions.Azure öğesini atlayabilir.

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.

Fabric SQL veya Azure SQL şifresiz kimlik doğrulama ile

Microsoft Entra ID'de veritabanına erişimi olan bir kimlikle giriş yapın. Yerel geliştirme için, Azure CLI gibi bir geliştirici aracı kullanın:

az login

Fabric'teki SQL veritabanı öğesinden veya Azure SQL veritabanından tam sunucu ve veritabanı adlarını 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 ve Azure SQL'e bağlanan bir uygulama için, yönetilen kimliğine veritabanı erişimi verin ve ardından Authentication=Active Directory Managed Identity kullanın. Diğer Microsoft Entra ID seçenekleri için bkz. Microsoft Entra ID doğrulama.

TCP üzerinden SQL Server

Sunucu, port, veritabanı ve oturum açma bilgilerini mevcut SQL Server'ınızdan veya izlediğiniz kurulum kılavuzundan alın. Aşağıdaki SQL kimlik doğrulama örneği yerel geliştirme konteyneri 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.

Ortam Windows tümleşik kimlik doğrulamasını veya Kerberos'u destekliyorsa, Password ve Integrated Security=true yerine User ID kullanın. Kurulum gereksinimleri için bkz. SQL Server doğrulaması.

Uygulama kodunu ekleme

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

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

Parametre türleri ve boyutları tablo sütunlarıyla eşleşir. Parametreler, SQL metninden ayrı değerler gönderir, bu da bu değerlerin komut sözdizimi değişmesini engeller ve SQL Server'ın sorgu planlarını yeniden kullanmasına yardımcı olur.

await using bir istisna oluşsa bile okuyucuyu ve bağlantıyı serbest bırakır. Bağlantıyı ortadan kaldırmak, uygulamanın ömrü boyunca bir bağlantıyı açık tutmak yerine fiziksel bağlantıyı bağlantı havuzuna geri döndürür.

Uygulamayı çalıştırma

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

dotnet run

Uygulama, eklediği satırı yazdırır:

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

Her veritabanında kimlik değeri ve zaman damgası farklılık gösterir.

Bağlantı başarısız olursa, hata çıktısından SQL hata numarası ve istemci bağlantı kimliğini kullanın. Sunucu ve veritabanı adlarını, ağ erişimini, veritabanı izinlerini, kimlik doğrulama kurulumunu ve sertifika yapılandırmasını kontrol edin. Azure SQL veya canlı bağlantısına, bağlantı sorunlarına genel bir çözüm olarak TrustServerCertificate=true eklemeyin.

Deseni bir uygulamada kullanın

Örneği API, servis, masaüstü uygulaması veya arka plan çalışanına taşırken bu 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?

Last updated on 2026-09-21