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, Microsoft Fabric'teki SQL veritabanı ve Microsoft Fabric'teki Warehouse 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. .NET uygulamalarına bağlantılar, komutlar, sonuç işleme, işlemler, toplu kopyalama ve SQL Server'a özgü özellikler sağlar.

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ı isimlerini IConfiguration öğesinden okur, böylece değerler hostun yapılandırdığı yapılandırma sağlayıcılarından gelir; örneğin appsettings.json, environment variables, Azure Uygulama Yapılandırması ve Key Vault-destekli ayarlar. Konfigürasyon şu özellikleri birleştirir:

  • Taşıma Katmanı Güvenliği (TLS).
  • Yönetilen kimlik.
  • Boşta kalan bağlantı dayanıklılığı.
  • Yapılandırılabilir yeniden deneme mantığı (CRL) ile ilk bağlantı için yeniden deneme, yapılandırılmış loglama ile.
  • Sorgu sırasında meydana gelen geçici hatalar için komut seviyesinde yeniden deneme.
  • Hızlı yük devretme grubu kurtarması.
  • İptal tokenı kabul eden asenkron çağrılar.

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 .

Snippet, .NET 8 veya daha sonraki sürümleri hedefleyen ve Microsoft.Data.SqlClient.Extensions.Azure ile Microsoft.Data.SqlClient 7.1.1 paketlerine başvuran bir proje varsayımındadır. .NET Genel Sunucu veya ASP.NET Core gibi ana bilgisayar, IConfiguration ve ILogger öğelerini sağlar; yapılandırma ise sunucu adını Sql:Server içinde ve veritabanı adını Sql:Database içinde sağlar.

public static async Task<string> QueryDatabaseNameAsync(
    IConfiguration config, ILogger logger, CancellationToken cancellationToken = default)
{
    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 (server must support it)
        ConnectTimeout = 30,                         // per-attempt connect timeout in seconds
        // Retry transient failures during Open() and reconnect a dropped idle connection.
        // The configurable provider below adds another policy around Open().
        ConnectRetryCount = 3,
        ConnectRetryInterval = 10,
        MultiSubnetFailover = true,                  // recommended for TCP endpoints; enables parallel connect
        // ApplicationIntent = ApplicationIntent.ReadOnly, // uncomment to route to a readable secondary
    };

    // Add exponential backoff and jitter around Open().
    // 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);
    };

    await using var connection = new SqlConnection(builder.ConnectionString)
    {
        RetryLogicProvider = openRetry,
    };
    await connection.OpenAsync(cancellationToken);

    await using var command = new SqlCommand("SELECT DB_NAME()", connection)
    {
        RetryLogicProvider = commandRetry,
        CommandTimeout = 30,
    };

    var name = (string)await command.ExecuteScalarAsync(cancellationToken);
    logger.LogInformation("Connected to database {DatabaseName}", name);
    return name;
}

Yöntem, bağlandığı veritabanının adını döndürür ve Connected to database <database> günlüğe kaydeder. Tekrar deneme olduğunda, onu tetikleyen istisna ile birlikte her tekrar denemede bir uyarı kaydedilir.

Snippet'in her bir parçası nasıl çalışır:

  • Hedefler: Microsoft Entra doğrulaması için yapılandırılmış herhangi bir SQL Database Engine uç noktası: Azure SQL Veritabanı, Azure SQL Yönetilen Örneği, Microsoft Fabric'te SQL database ve Azure Sanal Makineler üzerindeki veya Azure Arc ile etkinleştirilen SQL Server 2022 ve sonraki sürümler.
  • Encrypt = SqlConnectionEncryptOption.Strict: TDS 8.0 şifrelemesini seçer. SQL Server 2022 ve daha sonraki sürümleri, Azure SQL Veritabanı, Azure SQL Yönetilen Örneği veya Microsoft Fabric'te SQL veritabanı gerektirir. Eski sunucular için SqlConnectionEncryptOption.Mandatory kullanın.
  • ActiveDirectoryManagedIdentity: Yalnızca Azure App Service, Azure İşlevleri veya Azure sanal makinesi gibi yönetilen bir kimlik mevcut olduğunda çalışır. Yerel geliştirme için, Azure CLI'ı, Visual Studio oturum açmasını ve diğer kimlik bilgisi kaynaklarını deneyen SqlAuthenticationMethod.ActiveDirectoryDefault kullanın. Üretimden uzak tutun çünkü her kaynağı yoklamak bağlantıyı yavaşlatıyor. Daha fazla bilgi için Varsayılan kimlik doğrulamayı kullan bölümüne bakın.
  • MultiSubnetFailover = true: Tüm çözülmüş IP adreslerine paralel olarak TCP bağlantıları dener ve başarılı olan ilk bağlantıyı kullanır, böylece IP’ler arasında yavaş ardışık denemeden kaçınır. Bunu Azure SQL Veritabanı, Azure SQL Yönetilen Örneği, Microsoft Fabric'teki SQL veritabanı, kullanılabilirlik grubu dinleyicileri ve yük devretme kümesi örnekleri için ayarlayın. Tek IP’li hedeflerde güvenlidir. Adlandırılmış örnekler, TCP dışındaki protokoller, 64'ten fazla IP adresi olan örnekler veya kullanımdan kaldırılmış veritabanı yansıtma için desteklenmez. 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.
  • ConnectRetryCount = 3 ve ConnectRetryInterval = 10: Sürücü, Open() sırasında geçici hataları yeniden dener ve bir sonraki komutta kesilen boşta bağlantıyı yeniden bağlar. Varsayılan sayı 1'dir. 10 saniye arayla yapılan üç deneme, daha uzun süren bir yeniden yapılandırma veya failover sürecini atlatabilir. Sürücü, yalnızca sunucu adı .database.windows.net gibi bilinen bir Azure SQL etki alanıyla bittiğinde 1 değerini 2’ye yükseltir; böylece özel DNS takma adı 1 değerini alır.
  • openRetry: SqlConnection.RetryLogicProvider öğesine atanmış olarak, Open() çevresine üstel geri çekilme ekler. Sürücü, ConnectTimeout süresi dolunca iç yeniden denemelerini durdurur, bu yüzden en kötü durumda OpenAsync hata vermeden önce, her biri 30 saniyeye kadar süren beş deneme ve buna ek olarak geri çekilme süresi olur. Her boşta yeniden bağlanma denemesi aynı zamanda openRetry ilkesinin tamamını çalıştırır ve bu politika denemelerini bitirdiğinde, boşta kurtarma sona erer.
  • Sunucusuz otomatik duraklatma: Azure SQL Veritabanı serverless için ConnectTimeout değerini en az 60 saniyeye yükseltin. İlki Open(), veritabanı yeniden başlatılırken 40613 hatasıyla başarısız olabilir ve openRetry bunu yeniden dener. İstemci tarafında bir zaman aşımı, -2 hatası olarak ortaya çıkar ve bu yeniden denenmez, bu yüzden her bağlantı denemesi sürdürmeden daha uzun sürmelidir. Daha fazla bilgi için bkz. Otomatik duraklatma ve otomatik devam.
  • commandRetry: Yalnızca komutu yeniden yürütmek güvenliyse bunu SqlCommand.RetryLogicProvider öğesine ekleyin: okumalar, doğal bir anahtarla korunan MERGE, bir saklı yordam aracılığıyla yapılan upsert işlemleri ve diğer idempotent işlemler. İşlem içinde yeniden denemeyi atlar, bu yüzden uygulama kodu çoklu ifadeli işlemleri yeniden denemek zorundadır. ExecuteReader ve ExecuteScalar, ilk sonuç kümesi başlamadan önce döndürülen hataları yalnızca yeniden dener. ExecuteNonQuery çağrının tamamını tekrar deniyor.
  • Geçici hata listesi: Ayarlama TransientErrors yerleşik listenin yerini alır. Bunun yerine uzatmak için SqlConfigurableRetryFactory.BaselineTransientErrors kullanın (Microsoft.Data.SqlClient 7.0 ve sonrası)
  • Retrying Olay: Retrying Her yeniden denemeden önce, yeniden deneme sayısı, sonraki gecikme ve şimdiye kadarki istisnalarla tetiklenir. Bunu ILogger veya telemetri işlem hattınıza yönlendirin.
  • İstisnalar: Yöntem istisnaları yakalamaz. Tükenmiş bir sağlayıcı, her denemedeki özel durumu AggregateException fırlatır. Geçici olmayan bir hata orijinal özel durum olarak yayılır. Çağıran, bunu istek bağlamının geri kalanıyla birlikte bir kez kaydeder.
  • İptal: CancellationToken sağlayıcının yeniden denemeler arasındaki beklemesini durdurur. Sürücünün Open beklemesini tek bir ConnectRetryInterval deneme içinde kesintiye uğratmaz. Daha fazla bilgi için asenkron programlama bölümünü inceleyin.
  • Sağlayıcı ömrü: Snippet, her aramada yeniden deneme sağlayıcılarını bağımsız kalmak için oluşturur. Bir uygulamada, onları bir kez oluşturun ve tekrar kullanın.

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

Temel veri erişim görevlerini öğrenin

Bağlantı kurduktan sonra, aşağıdaki makaleleri sırayla kullanın:

  1. Bir komut çalıştırın, bir sonuç şekli seçin ve Transact-SQL çalıştırın (T-SQL).
  2. Parametreleri yapılandırın veritabanı sözleşmesine uyacak şekilde.
  3. SqlDataReader ile satırları ve birden çok sonucu işlemek için veri alın.
  4. Verileri depolanmış prosedürlerle değiştirin; çıktı parametrelerini ve döndürme değerlerini kullanın.
  5. Çağıran tarafından iptal ve sınırlı zaman aşımları eklemek için asenkron programlama ve iptal kullanın.
  6. Tekrar denemeler veya üretim teşhisi eklemeden önce hataları ve mesajları işleyin.

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. 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ı havuzu: Varsayılan olarak açık. Bir isteğe bağlı V2 havuzu değerlendirme aşamasında.
  • 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.
  • Uygulama kimliği: Kütüphanenizi veya aracınızı SQL Server'a tanıtmak için SqlConnection.RegisteredApplication ayarlayın (Microsoft.Data.SqlClient 7.1 ve sonrası).

Get started

Makale Description
SqlClient sürücüsünü kullanmaya başlayın Bir proje kurun, veritabanı oluşturun, bağlantı kurun, sorgulayın ve bağlantı dayanıklılığı ekleyin.
Microsoft.Data.SqlClient’i yükleme, güncelleştirme ve dağıtma NuGet paketlerini kurun, bir sürüm seçin, sürücüyü güncelleyin ve dağıtım çıktısını hazırlayın.
Destek yaşam döngüsü Desteklenen sürücü sürümlerini ve destek tarihlerini gözden geçirin.
System.Data.SqlClient'tan Microsoft'a geçiş. Data.SqlClient Paket referanslarını, isim alanlarını, yapılandırmayı ve sürücü davranışını güncelleyin.
Microsoft. Data.SqlClient isim alanı ve uyumluluğu SqlClient'ın ADO.NET'i nasıl uyguladığını ve bunun System.Data.SqlClient, .NET ve SQL Server ile uyumluluğunu anlayın.
Microsoft'ta ne yenilikler? Data.SqlClient Güncel sürümleri, büyük yükseltme değişikliklerini ve üst akış sürüm notlarını bulun.

Yapılandırma ve bağlanma

Makale Description
Bir veri kaynağına bağlanın Bağlantıları aç ve yönet, bağlantı durumu değişikliklerine yanıt ver.
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.
Hataları ve mesajları ele alın Hataları yakalayın ve bilgilendirici mesajlar alın.

Doğrulama ve güvence

Makale Description
Microsoft.Data.SqlClient için güvenlik en iyi uygulamaları 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
Bir komutu çalıştır 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.
SqlBatch ile birden fazla komutu çalıştır Sıralı bir komut koleksiyonu gönderin ve sonuçlarını işleyin.
Akış verileri Büyük ikili, metin, XML ve JSON değerlerini değerin tamamını arabelleğe almadan aktarın.
İş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.
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
SQL Server veri tipi eşlemeleri SQL Server tiplerini .NET ve System.Data.SqlTypes türlerine eşleyin.
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.
SqlClient'da olay sayaçları 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.
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.
Microsoft.Data.SqlClient GitHub deposu Sürücü kaynak kodunu, sürüm notlarını ve örnekleri okuyun.
Microsoft.Data.SqlClient örnekleri Sürücü API'leri için C# örneklerine göz atın.
.NET runtime GitHub repository .NET çalışma zamanı kütüphanelerinin kaynağını okuyun.

Özellik isteme

Bir özellik talebinde bulunmak için Microsoft.Data.SqlClient GitHub deposunda bir sorun açın.

İlgili içerik

  • Son güncelleştirme: