Microsoft.Data.SqlClient için bağlantı dizeleri

Bir Microsoft.Data.SqlClient bağlantı dizesi, noktalı virgüllerle ayrılmış keyword=value anahtar/değer çiftlerinin bir listesidir. Onu SqlConnection veya SqlConnectionStringBuilder kişisine ver:

Server=tcp:sql.example.com,1433;Database=Orders;Integrated Security=true;Encrypt=Strict

Bir bağlantı dizesi dört soruya cevap verir:

  1. Uygulama hangi sunucuyu ve veritabanını kullanıyor?
  2. Uygulama hangi kimlik olarak çalışıyor?
  3. İstemci sunucu sertifikasını nasıl doğrular?
  4. İş yükünün hangi bağlantı davranışına ihtiyacı var?

Bu makale, sürücünün metni okumak için kullandığı bu seçimleri ve kuralları ele alır. Her anahtar sözcük, eşanlamlıları ve varsayılan değeri için Bağlantı seçenekleri'ne bakın. Kodda bağlantı dizileri oluşturmak ve değiştirmek için bkz. Bağlantı dizisi oluşturucular.

Bir kimlik modeli seçin

Konuşlandırmaya uygun deseni kullanın. Her yer tutucunu, örneğin <server>, değerinizle değiştirin.

Environment Pattern Bağlantı dizesi
Windows'ta etki alanı veya yerel Windows kimliğiyle SQL Server Windows tümleşik kimlik doğrulaması Server=<server>;Database=<database>;Integrated Security=true;Encrypt=true
Azure'da barındırılan ve Azure SQL'e bağlanan uygulama Microsoft Entra ID yönetilen kimliği Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Managed Identity;Encrypt=Strict
Azure SQL’e bağlanan geliştirici iş istasyonu Microsoft Entra ID varsayılan kimlik bilgisi zinciri Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict
Microsoft Fabric'te SQL veritabanına bağlanan geliştirici iş istasyonu Microsoft Entra ID varsayılan kimlik bilgisi zinciri Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict
Azure SQL’e bağlanan etkileşimli masaüstü aracı Microsoft Entra ID etkileşimli kimlik doğrulama Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Interactive;Encrypt=Strict
SQL kimlik doğrulaması gerektiren ortam Gizli bir mağazadan kullanıcı adı ve şifre Server=<server>;Database=<database>;User ID=<user>;Password=<password>;Encrypt=true

Windows entegre kimlik doğrulama, işlemin kimliğiyle bağlanır. Masaüstü veya konsol uygulamaları için bu genellikle oturum açmış kullanıcıdır. Bir web uygulaması veya Windows servisi için, bu uygulama havuzu veya hizmet hesabıdır. Kimliğe bürünme kimliği değiştirebilir. Uygulamanızın gerçekten kullandığı kimliğe giriş ve veritabanı izinleri verin.

Bu üç Windows entegre kimlik doğrulama türü eşdeğerdir:

Server=sql.example.com;Database=Orders;Integrated Security=true;Encrypt=true
Server=sql.example.com;Database=Orders;Integrated Security=SSPI;Encrypt=true
Server=sql.example.com;Database=Orders;Trusted_Connection=yes;Encrypt=true

Bir bağlantı dizesi Integrated Security=true ayarlar ve ayrıca Password ile User ID ayarlarsa, sürücü Windows authentication'ı kullanır ve kullanıcı adını ile şifreyi görmezden gelir.

Microsoft. Data.SqlClient 7.0 ve daha sonraki sürümler, sürücü tarafından sağlanan Microsoft Entra ID kimlik doğrulama yöntemleri için sürüm eşleştirilmiş Microsoft.Data.SqlClient.Extensions.Azure pakete ihtiyaç duyar. Uygulama kodu erişim tokenı veya access token callback sağladığında bu pakete ihtiyacınız olmuyor.

Kabul edilen Authentication değerler için Kimlik doğrulama seçeneklerine bakınız. Kimlik doğrulama ayrıca sunucuda veritabanı kullanıcıları, izinler ve kimlik yapılandırması gerektirir. Kurulum adımları için bkz. Microsoft Entra ID kimlik doğrulaması ve SQL Server kimlik doğrulaması.

Sunucu ve veritabanını belirtin

Server ve Database en okunabilir anahtar kelime isimleridir. Yapımcı bunları kanonik eşdeğerleri olan Data Source ve Initial Catalog olarak yazar. Dört isim de bir bağlantı dizesi'te çalışır.

Server öğesini şu biçimlerden birine ayarlayın:

Form Example Use
Konak adı Server=sql.example.com 1433 portundaki varsayılan örnek.
Sunucu adı ve bağlantı noktası Server=tcp:sql.example.com,1433 Belirli bir TCP portu. Portu iki nokta yerine virgülle ayırın.
Adlandırılmış örnek Server=sql.example.com\SALES Isimlendirilmiş bir örnek. Sürücü, UDP 1434 numaralı bağlantı noktasındaki SQL Server Browser hizmetine bağlantı noktasını sorar.
Yerel sunucu Server=(local) veya Server=. Yerel bilgisayardaki varsayılan örnek.
LocalDB Server=(localdb)\MSSQLLocalDB SQL Server Express LocalDB Windows üzerinde. Bağlantı, Encrypt=Mandatory ile bile şifreli değil ve Encrypt=Strict başarısız oluyor.
Adlandırılmış boru Server=np:\\sql.example.com\pipe\sql\query Windows'ta isimli bir boru bağlantısı.

Tam nitelikli bir ana bilgisayar adı ve üretimde açık bir port kullanın tcp:. Sunucu sertifikasıyla eşleşen bir DNS adı kullanın, IP adresi değil, çünkü sertifika doğrulaması, bağlantı dizesi'deki sunucu adını sertifikadaki isimlerle karşılaştırır.

Azure SQL Veritabanı'e SQL kimlik doğrulamasıyla bağlandığınızda ve kullanıcı adı user@servername biçimindeyse, servername kısmı Server içindeki sunucuyla eşleşmelidir.

Bir kullanılabilirlik grubu dinleyicisi veya yük devretme kümesi örneği için, Multi Subnet Failover bölümündeki öğesini de gözden geçirin.

Şifreleme ve sertifika doğrulamasını yapılandırmak

Encrypt anahtar sözcüğü, büyük/küçük harfe duyarlı olmaksızın aşağıdaki değerleri kabul eder:

Value Oluşturucu değeri Meaning
Strict Strict TDS 8.0 kullanıyor. Giriş öncesi bağlantıyı şifreler ve her zaman sunucu sertifikasını doğrular.
Mandatory, true, yes True Bağlantıyı şifreler. Bu değer varsayılandır.
Optional, false, no False Tüm bağlantıyı yalnızca sunucu şifreleme gerektirdiğinde şifreler. Sunucu şifrelemeyi desteklediğinde ama bunu gerektirmiyorsa, sadece giriş paketi şifrelenir.

Sunucu TDS 8.0'ı desteklediğinde ve istemcinin doğrulayabileceği bir sertifikaya sahip olduğunda kullanın Strict . Azure SQL Veritabanı ve Microsoft Fabric'teki SQL database bunu destekliyor. Bir LocalDB bağlantısı, Mandatory ile bile şifrelenmez ve Strict başarısız olur.

Encrypt ve Trust Server Certificate değerleri aşağıdaki şekilde birleşir:

Şifreleme Sunucu Sertifikasına Güven Result
Optional false Sunucu şifreleme gerektirdiğinde, tüm bağlantı şifrelenir ve sunucu sertifikasının doğrulanması gerekir. Aksi takdirde bağlantı başarısız olur. Sunucu şifrelemeyi desteklediğinde ama bunu gerektirmediğinde, sadece giriş paketi şifrelenir ve sürücü sunucu sertifikasını doğrulamaz, ancak bağlantı veya AccessTokenCallback.AccessToken Sunucu şifrelemeyi desteklemediğinde hiçbir şey şifrelenmez.
Optional true Sunucu şifreleme gerektirdiğinde, tüm bağlantı şifrelenir. Sunucu şifrelemeyi destekleyip gerektirmediğinde, sadece giriş paketi şifrelenir. Sürücü sunucu sertifikasını doğrulamaz.
Mandatory false Şifreleme yalnızca sunucu sertifikası doğrulandığında gerçekleşir. Aksi takdirde bağlantı başarısız olur.
Mandatory true Şifreleme her zaman gerçekleşir, ancak sürücü sunucu sertifikasını doğrulamaz.
Strict Ignored Şifreleme her zaman gerçekleşir ve sunucu sertifikası doğrulamalıdır. Aksi takdirde bağlantı bozulur.

Trust Server Certificate=true öğesini üretimde bağlantı hatasını düzeltmek için ayarlamayın. Kanalı şifreliyor ama sunucunun kimliğini doğrulamaz. Güvenilir bir sertifikanın mevcut olmadığı geliştirme ortamlarıyla sınırlayın.

Sunucu adı Data Source sertifikayla eşleşmiyorsa, sertifikadaki isme ayarlayın Host Name In Certificate . SqlClient sadece sunucu adı eşleşmediğinde bunu kontrol eder ve bir sertifikayı sabitlemez. Yalnızca bir belirli sertifikayı kabul etmek için PEM, DER veya CER dosyasının yoluna ayarlanın Server Certificate :

Server=tcp:sql.example.com,1433;Encrypt=Strict;Host Name In Certificate=sqlhost.example.com
Server=tcp:sql.example.com,1433;Encrypt=Strict;Server Certificate=C:\certificates\server.cer

Tam doğrulama kuralları için Şifreleme ve sertifika doğrulaması bölümünü ziyaret edin.

Bağlantı havuzunu kullanın

Havuzlama varsayılan olarak açıktır. Bir SqlConnection bağlantısı açtığınızda, sürücü, bağlantıya uygun bir havuzdan fiziksel bir bağlantı alır. Bağlantıyı kapattığınızda veya serbest bıraktığınızda, fiziksel bağlantı kapanmak yerine havuza geri döner. Ortak açık bir giriş, ağ bağlantısını, TLS el sıkışmasını ve girişi atlar.

Şu kuralları izleyin:

  • Bir bağlantıyı tam ihtiyacınız olmadan önce açın ve işiniz biter bitmez using veya await using ile serbest bırakın. Serbest bırakılmayan bir bağlantı ayrılmış olarak kalır ve havuz bitebilir.

  • Başlangıçta bağlantı dizesi'i bir kez oluştur ve tekrar kullan. Pool anahtarı, bağlantı dizesi'in tam metnini içerir, böylece farklı bir anahtar kelime sırası, eşanlamlı veya istek başına değer (örneğin istek kimliği veya kullanıcı adı) ayrı bir havuz oluşturur. Yapımcı bir kanonik form yazar. Daha fazla bilgi için bkz. Tek bir standart bağlantı dizesi kullanın.

  • Entegre kimlik doğrulama altında her Windows kimliği için ayrı bir havuz, her SqlCredential örnek ve her AccessToken değer bekleniyor. Her bağlantıda ayar AccessToken yerine sürücü tarafından sağlanan Authentication bir yöntem veya tekrar kullanılan AccessTokenCallback bir yöntem kullanın.

  • Max Pool Size'ı yükseltmeden önce kapatılmamış bağlantılara bakın; bu değer varsayılan olarak 100'dür. Bir havuzdaki her bağlantı kullanıldığında, Open bekler Connect Timeout ve sonra InvalidOperationExceptionatlar :

    Timeout expired.  The timeout period elapsed prior to obtaining a connection from the pool.  This may have occurred because all pooled connections were in use and max pool size was reached.

  • Her havuz için sunucu kapasitesini planlayın. Her süreç veya .NET Framework'teki her uygulama alanı kendi havuzları vardır. Sunucuya olan bağlantılar, her süreçteki havuzlarla ve uygulama örneklerinin sayısıyla çarpılan Max Pool Size değerine ulaşabilir.

  • Havuzlama sorununu aşmak için Pooling=false ayarını yapmayın. Her açılış tam giriş gerçekleştirir.

Çok uzun süre boşta kalan havuzlu bağlantıları kapatmak için bkz. Bağlantı boşta süresini sınırla. Havuz anahtarları, boyutlandırma, temizleme ve işlemler için bkz. SQL Server bağlantı havuzu oluşturma.

Ayrı bağlantı ve komut ayarları

Bir bağlantı dizesi, bağlantı kurulumunu ve oturum davranışını kontrol eder. Bir komut, bir SQL işlemini kontrol eder.

Requirement Açık konfigüre et
Bağlantı kurmak veya havuzdan bir bağlantı almak için verilen zaman Connect Timeout anahtar sözcük
Bağlantıdaki komutlar için varsayılan zaman aşımı Command Timeout anahtar sözcük
Bir komut için mola CommandTimeout
Arayan tarafından iptal CancellationToken asenkron yöntemlere aktarılan
Bağlantı açmak veya komut çalıştırmak için tekrar deneme politikası Yapılandırılabilir yeniden deneme mantığıSqlConnection veya SqlCommand üzerinde

Daha uzun bir zaman aşımı yeniden deneme mantığı değildir. Bir mola bir beklemeyi sınırlandırıyor. Bir yeniden deneme başka bir denemeyi başlatır ve bu deneme sınırlı olmalı, güvenle tekrarlanabilmelidir.

Uygulama kimliğini bildir

Application Name, sunucunun APP_NAME() aracılığıyla bildirdiği adı ayarlar. Her dağıtılan iş yükü için tek bir kararlı isim kullanın. Bir uygulama için bağlantı açan çerçeveler ve araçlar da kendilerini bağlantı dizesi anahtar sözcüğü olmayan RegisteredApplication özelliği üzerinden raporlayabilir. Daha fazla bilgi için Uygulama kimliğini bildir bölümüne bakınız.

Bağlantı dizilerini güvenli şekilde inşa edin

Kod bir değer eklerken veya değiştirdiğinde kullanın SqlConnectionStringBuilder . Güvenilmeyen metni bir bağlantı dizesi'e eklemeyin, çünkü o metindeki nokta virgül bir anahtar kelime ekleyebilir veya değiştirebilir. Oluşturucu değerleri doğrular, eşanlamlıları kanonik anahtar kelimelere eşler ve her değeri, değerin anahtar kelime ekleyememesi için tırnak içine alır. Örneğin, bkz. Bağlantı dizisi oluşturucular.

Bağlantı bilgilerini kod dışında sakla

Uygulamanın yapılandırma sisteminden bağlantı dizilerini yükleyin. .NET uygulamaları genellikle ortam değişkenleri, yerel geliştirme için kullanıcı sırları, Azure Uygulama Yapılandırması ve Azure Key Vault kullanır.

Şu kuralları izleyin:

  • Parolaları, istemci sırlarını, erişim belirteçlerini veya üretim bağlantı dizelerini commit etmeyin.
  • Bağlantı dizesinde parola gerektirmeyen bir kimlik doğrulama yöntemini tercih edin.
  • Yapılandırma kaynağına erişimi kısıtlayın.
  • Depolanmış gizli anahtarların rotasyonunu yapın ve bunları önbelleğe alan uygulamaları yeniden başlatın veya yenileyin.
  • Loglara, istisnalara, izlere veya telemetriye bağlantı dizileri yazmayın.
  • Persist Security Info=false varsayılan olarak bırakın; böylece açık bir bağlantı, şifreyi ConnectionString özelliği aracılığıyla açığa çıkarmaz.

.NET yapılandırma sağlayıcıları için bkz. .NET'te Yapılandırma. Daha fazla kontrol için, Bağlantı bilgilerini koruma bölümüne bakınız.

Ayrıştırma kuralları

Sürücü şu kuralları uygular:

  • Anahtar kelimeler büyük/küçük harfe duyarlı değildir. DATABASE, Database, ve database aynı anahtar kelimedir.
  • Birçok anahtar kelimenin eş anlamlıları vardır. Server ve Data Source aynı değeri ayarlar. Bağlantı seçenekleri makalesi her anahtar kelimenin eşanlamlılarını listeler.
  • Bir anahtar kelime birden fazla kez göründüğünde, son değer kazanır. Eşanlamlılar aynı anahtar kelime olarak sayılır.
  • Sürücü, anahtar kelimelerin ve tırnaklanmamış değerlerin etrafındaki boşlukları görmezden gelir.
  • Sondaki noktalı virgül isteğe bağlıdır.
  • Sürücünün tanımadığı bir anahtar kelime, ArgumentException iletisiyle Keyword not supported atar.

Değerler, anahtar kelimeye bağlı olarak büyük/küçük harfe duyarlı olabilir. Bir şifre büyük/küçük harfe duyarlıdır. Encrypt=STRICT ve Encrypt=strict aynıdır.

Bu program, oluşturucunun anahtar kelimeleri nasıl normalleştirdiğini, yinelenen bir öğeyi nasıl giderdiğini ve özel karakterleri nasıl alıntıladığını gösterir. .NET Framework sekmesi C# 7.3 kullanır. Örnekleri çalıştıran bir proje oluşturmak için, Projeyi Oluştur bölümüne bakınız.

using Microsoft.Data.SqlClient;

// Synonyms and keyword case are normalized to canonical keywords.
var parsed = new SqlConnectionStringBuilder(
    "server=tcp:sql.example.com,1433;DATABASE=Orders;uid=app_user;encrypt=yes;timeout=30");
Console.WriteLine(parsed.ConnectionString);

// When a keyword repeats, the last value wins.
var duplicate = new SqlConnectionStringBuilder(
    "Server=sql.example.com;Database=Orders;Database=Archive");
Console.WriteLine($"InitialCatalog: {duplicate.InitialCatalog}");

// The builder quotes values that contain delimiters.
var quoted = new SqlConnectionStringBuilder
{
    DataSource = "sql.example.com",
    UserID = "app_user",
    Password = "a;b'c\"d",
};
Console.WriteLine(quoted.ConnectionString);
Console.WriteLine($"Round trip: {new SqlConnectionStringBuilder(quoted.ConnectionString).Password == quoted.Password}");

Çıktı şudur:

Data Source=tcp:sql.example.com,1433;Initial Catalog=Orders;User ID=app_user;Connect Timeout=30;Encrypt=True
InitialCatalog: Archive
Data Source=sql.example.com;User ID=app_user;Password="a;b'c""d"
Round trip: True

İlk satır, her eşanlamlının kanonik anahtar sözcüğüyle değiştirildiğini gösterir: server yerine Data Source, Initial Catalog yerine DATABASE, User ID yerine uid ve timeout yerine Connect Timeout.

Değerleri tırnak içine alın

Bir değeri, değer noktalı virgül içerdiğinde, boşlukla başladığında veya bittiğinde ya da tırnak işaretiyle başladığında veya bittiğinde çift tırnak işareti (") veya tek tırnak işareti (') içine ekleyin. Alıntılı bir değerin içinde, çevreleyen tırnak işaretini iki kez yazın.

Value Bağlantı dizisi formu
a;b Password="a;b"
abc' Password="abc'"
say "hi" Password='say "hi"'
a;b'c"d Password="a;b'c""d"

Alıntı kuralları kolayca yanlış anlaşılabilir. Değerleri mülkler üzerinden SqlConnectionStringBuilder belirleyin ve inşaatçının fiyat vermesine izin verin. Daha fazla bilgi için bkz. Bağlantı dizelerini güvenli şekilde inşa et.

Boolean değerleri belirtin

Boolean değeri alan anahtar kelimeler, , , ve noher durumda , , ve kabul yestruefalseeder. Integrated Security ayrıca , kabul sspieder, yani true. Oluşturucu True veya False yazar.

Diğer şoförlerden anahtar kelimeler kullanın

Microsoft. Data.SqlClient, ODBC veya OLE DB anahtar kelimelerini kabul etmiyor, örneğin Driver ve Provider. Bir bağlantı dizesi'i başka bir sürücüden taşıdığınızda bu anahtar kelimeleri kaldırın. System.Data.SqlClient bağlantı dizileri Microsoft.Data.SqlClient içinde şu farklarla çalışır:

  • Encrypt, Microsoft.Data.SqlClient içinde varsayılan olarak Mandatory olur. Güvenilir sertifikası olmayan bir sunucu, sertifika doğrulamasında başarısız olur. Sunucuya güvenilir bir sertifika yükleyin.
  • .NET'te, Network Library, Connection Reset, ve Transparent Network IP Resolution desteklenmiyor. Bunları kaldırın.
  • Context Connection=true desteklenmez.
  • Asynchronous Processing desteklenen bir anahtar kelime değildir ve ArgumentException hatası verir. Onu kaldırın. Asenkron yöntemler onsuz da çalışır.
  • Type System Version=SQL Server 2000 desteklenmez. Bağlantı oluşturma işlemi ArgumentException hatası verir. Latest, SQL Server 2012, SQL Server 2008 veya SQL Server 2005 kullanın.

İlgili içerik

  • Son güncelleştirme: