Microsoft. Data.SqlClient for SQL Server

ADO.NET indirin

Microsoft.Data.SqlClient, SQL Server, Azure SQL Veritabanı, Azure SQL Yönetilen Örneği, Azure Synapse Analytics ve Microsoft Fabric’teki SQL veritabanı için desteklenen .NET veri sağlayıcısıdır. Bir NuGet paketi olarak dağıtılır, .NET çalışma zamanından bağımsız olarak geliştirilir ve yeni geliştirmelerde System.Data.SqlClient yerine geçer. Bağlantıları açmak, komutları çalıştırmak, sonuçları işlemek, işlemleri yönetmek, verileri toplu yüklemek ve .NET uygulamalarından SQL Server'a özgü özellikleri kullanmak için kullanın.

Başlangıç noktanızı seçin

Azure SQL için üretim temeli

Bu snippet'i, üretim odaklı bir Azure SQL veri erişim yolu için bir başlangıç noktası olarak kullanın. Sunucu ve veritabanı adlarını IConfiguration içinden okur; bu nedenle değerler, konağın bağladığı yapılandırma sağlayıcılarından (appsettings.json, ortam değişkenleri, Azure Uygulama Yapılandırması, Key Vault destekli ayarlar vb.) gelir. Yapılandırma; Taşıma Katmanı Güvenliği'ni (TLS), yönetilen kimliği, boştaki bağlantılara dayanıklılığı, yapılandırılabilir yeniden deneme mantığı (CRL) aracılığıyla ilk bağlantı için yeniden denemeyi ve yapılandırılmış günlüklemeyi, sorgu sırasında ortaya çıkan geçici hatalar için komut düzeyinde yeniden denemeyi ve yük devretme grubunun hızlı kurtarılmasını bir araya getirir.

Daha yüksek güvenlik ve ortamlar arasında yapılandırmayı desteklemek için bağlantı bilgilerini kodunuzun dışında tutun. Üretimde, bağlantı bilgilerini uygulamanızın yapılandırma sisteminde saklayın ve hassas değerler için Azure Key Vault'u kullanın. Daha fazla bilgi için bkz. Bağlantı bilgilerini koruma.

Bu makaledeki C# snippeti kısalık için direktifleri ve sınıf ambalajlarını çıkarır using .

public static void QuerySalesWithResilience(IConfiguration config, ILogger logger)
{
    string server = config["Sql:Server"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Server'.");
    string database = config["Sql:Database"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Database'.");

    var builder = new SqlConnectionStringBuilder
    {
        DataSource = server,
        InitialCatalog = database,
        Authentication = SqlAuthenticationMethod.ActiveDirectoryManagedIdentity,
        Encrypt = SqlConnectionEncryptOption.Strict, // TDS 8.0 encryption (SqlClient 5.0 and later versions; server must support it)
        ConnectTimeout = 30,                         // per-attempt connect timeout in seconds
        // Idle connection resiliency: reconnect a dropped idle connection after Open() succeeded.
        // This is separate from the initial-connect retry provider defined next.
        ConnectRetryCount = 3,
        ConnectRetryInterval = 10,
        MultiSubnetFailover = true,                  // recommended for TCP endpoints; enables parallel connect
        // ApplicationIntent = ApplicationIntent.ReadOnly, // uncomment to route to a readable secondary
    };

    // Retry the initial Open() on transient failures with exponential backoff and jitter.
    // TransientErrors is null, so the provider uses the driver's built-in transient error list.
    var openRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 5,
            DeltaTime = TimeSpan.FromSeconds(3),
            MaxTimeInterval = TimeSpan.FromSeconds(60),
        });
    openRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL connection to {Server}/{Database} (attempt {Attempt}) after {Delay}",
            server, database, args.RetryCount, args.Delay);
    };

    // Retry commands that hit deadlocks, lock timeouts, or common Azure SQL transient errors
    // mid-query on an established connection. Only attach this provider to commands whose
    // effect is safe to repeat.
    var commandRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 4,
            DeltaTime = TimeSpan.FromSeconds(5),
            MaxTimeInterval = TimeSpan.FromSeconds(30),
            // Deadlock victim, lock-request timeout, and common Azure SQL transient errors.
            TransientErrors = new[] { 1205, 1222, 10928, 10929, 40197, 40501, 40613, 49918 },
        });
    commandRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL command (attempt {Attempt}) after {Delay}",
            args.RetryCount, args.Delay);
    };

    try
    {
        using var connection = new SqlConnection(builder.ConnectionString)
        {
            RetryLogicProvider = openRetry,
        };
        connection.Open();

        using var command = new SqlCommand(
            "SELECT TOP (100) SalesOrderId, OrderDate, TotalDue FROM Sales.SalesOrderHeader ORDER BY OrderDate DESC",
            connection)
        {
            RetryLogicProvider = commandRetry,
            CommandTimeout = 30,
        };

        using var reader = command.ExecuteReader();
        while (reader.Read())
        {
            logger.LogInformation(
                "Order {SalesOrderId} placed {OrderDate:d} total ${TotalDue:N2}",
                reader.GetInt32(0), reader.GetDateTime(1), reader.GetDecimal(2));
        }
    }
    catch (SqlException ex)
    {
        logger.LogError(
            ex,
            "Query against {Server}/{Database} failed after retries (SQL error {ErrorNumber})",
            server, database, ex.Number);
        throw;
    }
}

Bu kod parçacığı, Microsoft Entra kimlik doğrulaması için yapılandırılmış herhangi bir SQL Database Engine uç noktasını hedefler: Azure SQL Veritabanı, Azure SQL Yönetilen Örneği, Microsoft Fabric'teki SQL veritabanı ve Azure Sanal Makineler üzerinde çalışan veya Azure Arc tarafından etkinleştirilen SQL Server 2022 ve sonraki sürümleri.

Encrypt = SqlConnectionEncryptOption.Strict TDS 8.0 şifrelemesini seçer. Bunun için Microsoft.Data.SqlClient 5.0 ve sonraki sürümler ile TDS 8.0'ı destekleyen bir sunucu gerekir (SQL Server 2022 ve sonraki sürümler, Azure SQL Veritabanı, Azure SQL Yönetilen Örneği ve Microsoft Fabric'teki SQL veritabanı). Eski sunuculara bağlandığınızda SqlConnectionEncryptOption.Mandatory kullanın.

ConnectRetryCount ve ConnectRetryIntervalboşta bağlantı dayanıklılığını etkinleştirin: başarılı olduktan Open() sonra, sürücü bir sonraki komutta düşürülen boşta bağlantıyı şeffaf şekilde yeniden bağlar. Başlangıçtaki Open() yeniden denemezler. İlk bağlantı yeniden denemeleri, SqlConnection.RetryLogicProvider için atanan openRetry sağlayıcısından gelir. Bu iki özellik tamamlayıcıdır.

Her sağlayıcıdaki Retrying olayı, her yeniden deneme girişiminden önce tetiklenir ve yeniden deneme sayısını, bir sonraki girişimden önceki gecikmeyi ve o ana kadar gözlemlenen özel durumları içerir. Bunu, yeniden deneme döngüsünü canlı ortamda görünür tutmak için ILogger veya telemetri işlem hattınıza yönlendirin.

Hedef Azure SQL Veritabanı, Azure SQL Yönetilen Örneği, Microsoft Fabric'te SQL veritabanı, kullanılabilirlik grubu dinleyicisi veya failover kümesi örneği olduğunda ayarlanırMultiSubnetFailover = true. Çözümlenen tüm IP adreslerine paralel olarak TCP bağlantıları kurmayı deneyen ve başarılı olan ilkini kullanan bir paralel bağlantı kod yolu seçer; böylece aksi takdirde bu bağlantı girişimlerini geciktirebilecek, IP adreslerini tek tek dolaşan yavaş sıralı süreçten kaçınılır. Tek IP'li hedeflerde ayar güvenlidir. MultiSubnetFailover adlandırılmış bir örneğine, TCP dışında bir protokol üzerinden veya 64'ten fazla IP adresiyle yapılandırılmış bir instance'a bağlandığınızda desteklenmez. Ayrıca veritabanı yansıtma ile de kullanılamaz, çünkü bu SQL Server'ın tüm desteklenen sürümlerinde kullanımdan kaldırılmıştır. Bunun yerine Always On kullanılabilirlik gruplarını kullanın. Daha fazla bilgi için Yüksek erişilebilirlik ve felaket kurtarma ve Şeffaf Ağ IP Çözümlemesini devre dışı bırakma konularına bakın.

Hedef, otomatik duraklatma etkinleştirilmiş Azure SQL Veritabanı sunucusuz katmanı ise, ConnectTimeout değerini en az 60 saniyeye yükseltin. Otomatik olarak duraklatılan bir veritabanı, ilk Open() sırasında yeniden etkinleşir ve veritabanı yeniden etkinleşirken bu ilk Open(), 40613 hatasıyla başarısız olabilir. 40613 hatası yerleşik geçici hata listesinde olduğundan, openRetry bunu yeniden dener. İstemci tarafındaki zaman aşımları, -2 hatası olarak görünür; bu hata o listede yer almadığından, openRetry, sürdürme işleminin ortasında zaman aşımına uğrayan bir Open() kurtaramaz. Bireysel bağlantı girişimi özgeçmişi kapsayacak kadar uzun olmalıdır. Daha fazla bilgi için bkz. Otomatik duraklatma ve otomatik devam.

Komut düzeyinde yeniden deneme, her komut için çağıranın vereceği bir karardır. commandRetry öğesini SqlCommand.RetryLogicProvider öğesine yalnızca komutun yeniden yürütülmesi güvenliyse ekleyin: okumalar, doğal anahtarla korunan MERGE, saklı yordam üzerinden yapılan ekleme/güncelleme işlemleri ve diğer idempotent işlemler. Yerleşik komut sağlayıcısı, bir işlem aktifken yeniden denemeyi atlar, bu yüzden çoklu ifadeli işlemler, işlemi yeniden açabilen uygulama koduyla yeniden denenmelidir. TransientErrors ayarını yapmak, sürücünün yerleşik hata listesinin yerine geçer; bunun yerine yerleşik temel listeyi genişletmek için SqlConfigurableRetryFactory.BaselineTransientErrors kullanın (Microsoft.Data.SqlClient 7.0 ve sonrası).

Bu yapılandırmanın her bölümü hakkında daha fazla bilgi için bkz:

Temel özellikler

  • Modern .NET desteği: Mevcut .NET ve .NET Framework sürümlerinde çalışır. Versiyon başına açıklama için bkz. Destek yaşam döngüsü.
  • Varsayılan olarak şifrelenmiş: TLS ile şifrelenmiş bağlantılar varsayılan Encrypt=true olarak kullanılır. Microsoft.Data.SqlClient 5.0 ve sonraki sürümlerde TDS 8.0 şifrelemesi için Encrypt=Strict ayarlayın.
  • Microsoft Entra ID kimlik doğrulaması: Yönetilen kimlik, hizmet sorumlusu, etkileşimli, tümleşik, varsayılan kimlik bilgisi zinciri ve erişim belirteci akışları ile parolasız bağlantılar.
  • Kerberos ve NTLM: şirket içi Active Directory ve eski senaryolar için tümleşik Windows kimlik doğrulaması.
  • Always Encrypted: Hassas sütunlar için istemci tarafı şifreleme; yerinde işlemler için isteğe bağlı güvenli enklavlarla.
  • Toplu kopyalama: SqlBulkCopy ile yüksek hacimli ekleme işlemleri.
  • Bağlantı dayanıklılığı: Dahili bağlantı yeniden denemeleri (ConnectRetryCount ve ConnectRetryInterval) ile bağlantılar ve komutlar için isteğe bağlı yapılandırılabilir yeniden deneme mantığı.
  • Zengin SQL Server veri türleri: datetimeoffset, sql_variant, JSON, vektör, mekansal, XML ve tablo değerli parametreler.
  • Teşhis: Olay kaynağı takibi, tanı sayacları, sağlayıcı istatistikleri ve özel bir sorun giderme rehberi.

Get started

Makale Description
SqlClient sürücüsünü kullanmaya başlama Bir proje kurun, veritabanı oluşturun, bağlantı kurun, sorgulayın ve bağlantı dayanıklılığı ekleyin.
SqlClient sürücüsüne genel bakış Microsoft.Data.SqlClient'in ADO.NET içindeki yerini öğrenin.
Microsoft'u indir. Data.SqlClient NuGet paketini yükleyin ve kaynak sürümlerini bulun.
Destek yaşam döngüsü Desteklenen sürücü sürümlerini ve destek tarihlerini gözden geçirin.
Microsoft. Data.SqlClient namespace System.Data.SqlClient'tan geçiş yapın ve isim alanı farklarını inceleyin.

Yapılandırma ve bağlanma

Makale Description
Bir veri kaynağına bağlanın SQL Server ve Azure SQL bağlantılarını aç ve yönet.
Bağlantı dizeleri Sunucu, veritabanı, kimlik doğrulama, şifreleme ve bağlantı davranışını yapılandırın.
Şifreleme ve sertifika doğrulaması Şifreli bağlantıları ve sunucu sertifikası doğrulamasını yapılandırın.
SQL Server bağlantı havuzu Fiziksel bağlantıları verimli şekilde yeniden kullanın.
Bağlantı etkinlikleri Bağlantı durumuna ve bilgilendirici mesajlara yanıt verin.

Doğrulama ve güvence

Makale Description
SQL Server güvenliği Kimlik doğrulama, yetkilendirme ve uygulama güvenliği rehberliğini gözden geçirin.
Microsoft Entra kimlik doğrulama Yönetilen kimlik, hizmet prensibi, şifre ve etkileşimli akışlarla bağlantı kurun.
Bağlantı bilgilerini koruma Kimlik bilgilerini ve bağlantı ayarlarını uygulama kodundan uzak tutun.
Her Zaman Şifreli Hassas sütun değerlerini veritabanı sisteminden koruyun.
Her Zaman Şifreli ile güvenli enklavlar Güvenli bir enclave ile şifrelenmiş verilerde zengin işlemler yürütün.

Veri alma ve güncelleme

Makale Description
Komutlar ve parametreler Parametreli SQL ifadeleri ve saklanan prosedürleri çalıştırın.
Veri Adaptörleri (DataAdapters) ve Veri Okuyucular (DataReaders) Sonuç kümelerini akışla veya bağlantısız veri yapılarını doldurun.
İşlemler ve eşzamanlılık Yerel ve dağıtık işlemler ile eşzamanlılık kontrolleri kullanın.
Veritabanı şema bilgisini alın Şema koleksiyonlarını ve kısıtlamalarını keşfedin.
Toptan kopyalama işlemleri Büyük veri setlerini verimli şekilde yükleyin.SqlBulkCopy
Tablo değerli parametreler Parametrizlenmiş bir ifade veya saklanan prosedüre birden fazla satır gönderin.
Asenkron programlama Asenkron bağlantı, komut ve veri işlemleri kullanın.
Birden Çok Etkin Sonuç Kümesi (MARS) Birden fazla toplu işlemi tek bir bağlantıda iç içe yürütün.

Veri türleri

Makale Description
ADO.NET veri tipi eşlemeleri Ortak dil çalışma zamanı tiplerini sağlayıcı ve SQL Server tiplerine eşleyin.
SQL Server veri türleri SQL Server'a özgü değerler ve System.Data.SqlTypes türlerle çalışın.
JSON verileri SQL Server json veri tipini gönderin ve alın.
Vektör verileri Vektör değerlerini gönderip alın.
XML veri XML değerlerini okuyun, yazın ve parametreleştirin.
İkili ve büyük değerli veriler İkili, FILESTREAM ve büyük değerli verilerin akışını sağlama ve güncelleme.

Güvenilirlik ve tanı

Makale Description
Yapılandırılabilir yeniden deneme mantığı Sınırlı politikalarla geçici bağlantı ve komut hatalarını tekrar deneyin.
Yüksek kullanılabilirlik ve olağanüstü durum kurtarma Erişilebilirlik grubu dinleyicileri ve failover ortaklarıyla bağlantı kurun.
Tanı sayacları Aktif bağlantıları, havuzlu bağlantıları ve diğer sürücü metriklerini izleyin.
Olay kaynağı izlemeyi etkinleştir Teşhis için ayrıntılı sürücü olaylarını kaydet.
Veri izleme ADO.NET işlemlerini ve veri erişimini takip edin.
SqlClient sorun giderme kılavuzu Yaygın bağlantı ve sürücü sorunlarını teşhis edin.
Sorgu bildirimleri Sorgu sonuçları değiştiğinde bildirimler alın.

SQL Server özellikleri

Makale Description
SQL Server özellikleri ve ADO.NET SqlClient üzerinden SQL Server'a özgü özelliklere göz atın.
Yerel Veritabanı SQL Server Express LocalDB örneklerine bağlanın.
Veri bulma ve sınıflandırma Sonuç kümelerinden hassasiyet sınıflandırma meta verilerini okuyun.

Başvuru ve kaynaklar

Makale Description
Microsoft. Data.SqlClient API referansı Sürücü için .NET API referansına göz atın.
AppContext anahtarları Uyumluluk ve güvenlik davranışını yapılandırın.
Ek SqlClient bilgisi bulun Kaynak kodu, destek ve topluluk kaynaklarını bulun.

İlgili içerik

  • Last updated on