SqlConnectionStringBuilder Kelas

Definisi

Ruang nama:

Microsoft.Data.SqlClient

Rakitan:

Microsoft.Data.SqlClient.dll

Paket:

Microsoft.Data.SqlClient v7.1.0

Menyediakan cara sederhana untuk membuat dan mengelola konten string koneksi yang digunakan oleh kelas SqlConnection.

public ref class SqlConnectionStringBuilder sealed : System::Data::Common::DbConnectionStringBuilder

[System.ComponentModel.TypeConverter(typeof(Microsoft.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))]
public sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder

[<System.ComponentModel.TypeConverter(typeof(Microsoft.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))>]
type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder

Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder

Warisan

DbConnectionStringBuilder

SqlConnectionStringBuilder

Atribut

TypeConverterAttribute

Contoh

Aplikasi konsol berikut membangun string koneksi untuk database SQL Server. Kode menggunakan SqlConnectionStringBuilder kelas untuk membuat string koneksi, lalu meneruskan ConnectionString properti SqlConnectionStringBuilder instans ke konstruktor kelas koneksi. Contohnya juga mengurai string koneksi yang ada dan menunjukkan berbagai cara untuk memanipulasi konten string koneksi.

Note

Contoh ini mencakup kata sandi untuk menunjukkan cara SqlConnectionStringBuilder kerja dengan string koneksi. Di aplikasi Anda, kami sarankan Anda menggunakan Autentikasi Windows. Jika Anda harus menggunakan kata sandi, jangan sertakan kata sandi yang dikodekan secara permanen dalam aplikasi Anda.

using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        // Create a new SqlConnectionStringBuilder and
        // initialize it with a few name/value pairs.
        SqlConnectionStringBuilder builder =
            new SqlConnectionStringBuilder(GetConnectionString());

        // The input connection string used the 
        // Server key, but the new connection string uses
        // the well-known Data Source key instead.
        Console.WriteLine(builder.ConnectionString);

        // Pass the SqlConnectionStringBuilder an existing 
        // connection string, and you can retrieve and
        // modify any of the elements.
        builder.ConnectionString = "server=(local);user id=ab;" +
            "password=********;initial catalog=AdventureWorks";

        // Now that the connection string has been parsed,
        // you can work with individual items.
        Console.WriteLine(builder.Password);
        builder.Password = "********";

        // You can refer to connection keys using strings, 
        // as well. When you use this technique (the default
        // Item property in Visual Basic, or the indexer in C#),
        // you can specify any synonym for the connection string key
        // name.
        builder["Server"] = ".";
        builder["Connect Timeout"] = 1000;
        builder["Trusted_Connection"] = true;
        Console.WriteLine(builder.ConnectionString);

        Console.WriteLine("Press Enter to finish.");
        Console.ReadLine();
    }

    private static string GetConnectionString()
    {
        // To avoid storing the connection string in your code,
        // you can retrieve it from a configuration file. 
        return "Server=(local);Integrated Security=SSPI;" +
            "Initial Catalog=AdventureWorks";
    }
}

Keterangan

Penyusun string koneksi memungkinkan pengembang membuat string koneksi yang benar secara terprogram, dan mengurai dan membangun kembali string koneksi yang ada, menggunakan properti dan metode kelas. Penyusun string koneksi menyediakan properti yang sangat diketik sesuai dengan pasangan kunci/nilai yang diketahui yang diizinkan oleh SQL Server. Pengembang perlu membuat string koneksi sebagai bagian dari aplikasi dapat menggunakan SqlConnectionStringBuilder kelas untuk membangun dan memodifikasi string koneksi. Kelas ini juga memudahkan untuk mengelola string koneksi yang disimpan dalam file konfigurasi aplikasi.

Melakukan SqlConnectionStringBuilder pemeriksaan untuk pasangan kunci/nilai yang valid. Oleh karena itu, Anda tidak dapat menggunakan kelas ini untuk membuat string koneksi yang tidak valid; mencoba menambahkan pasangan yang tidak valid akan melemparkan pengecualian. Kelas mempertahankan kumpulan sinonim tetap dan dapat diterjemahkan dari sinonim ke nama kunci terkenal yang sesuai.

Misalnya, saat Anda menggunakan properti Item untuk mengambil nilai, Anda dapat menentukan string yang berisi sinonim apa pun untuk kunci yang Anda butuhkan. Misalnya, Anda dapat menentukan "Alamat Jaringan", "addr", atau sinonim lain yang dapat diterima untuk kunci ini dalam string koneksi saat Anda menggunakan anggota apa pun yang memerlukan string yang berisi nama kunci, seperti properti Item atau Remove metode . Lihat properti ConnectionString untuk daftar lengkap sinonim yang dapat diterima.

Properti Item mencoba menyisipkan entri berbahaya. Misalnya, kode berikut, menggunakan properti Item default (pengindeks, di C#) dengan benar lolos dari pasangan kunci/nilai berlapis:

Dim builder As New Microsoft.Data.SqlClient.SqlConnectionStringBuilder  
builder("Data Source") = "(local)"  
builder("Integrated Security") = True  
builder("Initial Catalog") = "AdventureWorks;NewValue=Bad"  
Console.WriteLine(builder.ConnectionString)  

Microsoft.Data.SqlClient.SqlConnectionStringBuilder builder =  
new Microsoft.Data.SqlClient.SqlConnectionStringBuilder();  
builder["Data Source"] = "(local)";  
builder["Integrated Security"] = true;  
builder["Initial Catalog"] = "AdventureWorks;NewValue=Bad";  
Console.WriteLine(builder.ConnectionString);  

Hasilnya adalah string koneksi berikut yang menangani nilai yang tidak valid dengan cara yang aman:

Source=(local);Initial Catalog="AdventureWorks;NewValue=Bad";  
Integrated Security=True  

Konstruktor

Nama	Deskripsi
SqlConnectionStringBuilder()	Menginisialisasi instans baru dari kelas SqlConnectionStringBuilder.
SqlConnectionStringBuilder(String)	Menginisialisasi instans baru dari kelas SqlConnectionStringBuilder. String koneksi yang disediakan menyediakan data untuk informasi koneksi internal instans.

Properti

Nama	Deskripsi
ApplicationIntent	Menyatakan jenis beban kerja aplikasi saat menyambungkan ke database di Grup Ketersediaan SQL Server. Anda dapat mengatur nilai properti ini dengan ApplicationIntent. Untuk informasi selengkapnya tentang dukungan SqlClient untuk Grup Ketersediaan AlwaysOn, lihat Dukungan SqlClient untuk Ketersediaan Tinggi, Pemulihan Bencana.
ApplicationName	Mendapatkan atau mengatur nama aplikasi yang terkait dengan string koneksi.
AttachDBFilename	Mendapatkan atau mengatur string yang berisi nama file data utama. Ini termasuk nama jalur lengkap database yang dapat dilampirkan.
AttestationProtocol	Mendapatkan atau menetapkan nilai Protokol Pengesahan.
Authentication	Mendapatkan atau mengatur metode autentikasi yang digunakan untuk Menyambungkan dengan Microsoft Entra ke sumber daya Azure SQL.
ColumnEncryptionSetting	Mendapatkan atau mengatur pengaturan enkripsi kolom untuk penyusun string koneksi.
CommandTimeout	Waktu tunggu default (dalam detik) sebelum mengakhiri upaya untuk menjalankan perintah dan menghasilkan kesalahan. Defaultnya adalah 30 detik.
ConnectionReset	Kedaluwarsa. Usang. Mendapatkan atau mengatur nilai Boolean yang menunjukkan apakah koneksi diatur ulang saat digambar dari kumpulan koneksi.
ConnectRetryCount	Jumlah koneksi ulang yang dicoba setelah mengidentifikasi bahwa ada kegagalan koneksi diam. Ini harus berupa bilangan bulat antara 0 dan 255. Nilai default untuk titik akhir non Azure adalah 1. Untuk titik akhir Azure SQL, defaultnya adalah 2. Mulai dari versi 5.x, untuk Azure SQL titik akhir tanpa server atau sesuai permintaan, defaultnya adalah 5 untuk meningkatkan keberhasilan koneksi untuk koneksi ke instans diam atau dijeda. Atur ke 0 untuk menonaktifkan menyambungkan kembali pada kegagalan koneksi diam. Akan ArgumentException dilemparkan jika diatur ke nilai di luar rentang yang diizinkan.
ConnectRetryInterval	Jumlah waktu (dalam detik) antara setiap upaya koneksi ulang setelah mengidentifikasi bahwa ada kegagalan koneksi diam. Ini harus berupa bilangan bulat antara 1 dan 60. Defaultnya adalah 10 detik.
ConnectTimeout	Mendapatkan atau mengatur lamanya waktu (dalam detik) untuk menunggu koneksi ke server sebelum mengakhiri upaya dan menghasilkan kesalahan.
CurrentLanguage	Mendapatkan atau mengatur bahasa yang digunakan untuk peringatan server database atau pesan kesalahan..
DataSource	Mendapatkan atau mengatur nama atau alamat jaringan instans SQL Server untuk disambungkan.
EnclaveAttestationUrl	Mendapatkan atau mengatur URL pengesahan enklave yang akan digunakan dengan Always Encrypted berbasis enklave.
Encrypt	Mendapatkan atau menetapkan SqlConnectionEncryptOption nilai sejak versi 5.0 atau Boolean nilai untuk versi sebelumnya yang menunjukkan apakah enkripsi TLS diperlukan untuk semua data yang dikirim antara klien dan server.
Enlist	Mendapatkan atau menetapkan nilai Boolean yang menunjukkan apakah kumpulan koneksi SQL Server secara otomatis mendaftarkan koneksi dalam konteks transaksi alur pembuatan saat ini.
FailoverPartner	Mendapatkan atau mengatur nama atau alamat server mitra untuk disambungkan jika server utama tidak berfungsi.
FailoverPartnerSPN	Mendapatkan atau mengatur nama perwakilan layanan (SPN) mitra failover untuk koneksi.
HostNameInCertificate	Mendapatkan atau mengatur nama host yang akan digunakan saat memvalidasi sertifikat server untuk koneksi. Ketika tidak ditentukan, nama server dari Data Source digunakan untuk validasi sertifikat. (Hanya tersedia di v5.0+)
IdleTimeout	Mendapatkan atau mengatur waktu maksimum, dalam detik, bahwa koneksi dapat duduk tidak digunakan (diam) di kumpulan koneksi sebelum dibuang. Defaultnya adalah 300 (5 menit).
InitialCatalog	Mendapatkan atau mengatur nama database yang terkait dengan koneksi.
IntegratedSecurity	Mendapatkan atau menetapkan nilai Boolean yang menunjukkan apakah ID Pengguna dan Kata Sandi ditentukan dalam koneksi (ketika false ) atau apakah kredensial akun Windows saat ini digunakan untuk autentikasi (saat true ).
IPAddressPreference	Mendapatkan atau mengatur preferensi keluarga alamat IP saat membuat koneksi TCP.
IsFixedSize	Mendapatkan nilai yang menunjukkan apakah SqlConnectionStringBuilder memiliki ukuran tetap.
Item[String]	Mendapatkan atau mengatur nilai yang terkait dengan kunci yang ditentukan. Di C#, properti ini adalah pengindeks.
Keys	Mendapatkan yang ICollection berisi kunci di SqlConnectionStringBuilder.
LoadBalanceTimeout	Mendapatkan atau mengatur waktu minimum, dalam detik, agar koneksi hidup di kumpulan koneksi sebelum dihancurkan.
MaxPoolSize	Mendapatkan atau mengatur jumlah maksimum koneksi yang diizinkan dalam kumpulan koneksi untuk string koneksi khusus ini.
MinPoolSize	Mendapatkan atau mengatur jumlah minimum koneksi yang diizinkan dalam kumpulan koneksi untuk string koneksi khusus ini.
MultipleActiveResultSets	Jika true, aplikasi dapat mempertahankan beberapa tataan hasil aktif (MARS). Ketika false, aplikasi harus memproses atau membatalkan semua tataan hasil dari satu batch sebelum dapat menjalankan batch lain pada koneksi tersebut. Untuk informasi selengkapnya, lihat Beberapa Kumpulan Hasil Aktif (MARS).
MultiSubnetFailover	Jika aplikasi Anda tersambung ke grup ketersediaan AlwaysOn (AG) pada subnet yang berbeda, pengaturan MultiSubnetFailover=true menyediakan deteksi dan koneksi yang lebih cepat ke server aktif (saat ini). Untuk informasi selengkapnya tentang dukungan SqlClient untuk Grup Ketersediaan AlwaysOn, lihat Dukungan SqlClient untuk Ketersediaan Tinggi, Pemulihan Bencana.
NetworkLibrary	Mendapatkan atau mengatur string yang berisi nama pustaka jaringan yang digunakan untuk membuat koneksi ke SQL Server.
PacketSize	Mendapatkan atau mengatur ukuran dalam byte paket jaringan yang digunakan untuk berkomunikasi dengan instans SQL Server.
Password	Mendapatkan atau mengatur kata sandi untuk akun SQL Server.
PersistSecurityInfo	Mendapatkan atau menetapkan nilai Boolean yang menunjukkan apakah informasi sensitif keamanan, seperti kata sandi atau token akses, harus dikembalikan sebagai bagian dari string koneksi pada koneksi yang dibuat dengan ini SqlConnectionStringBuilder setelah koneksi tersebut berada dalam status terbuka. Properti ini hanya boleh diatur ke true jika aplikasi Anda memiliki kebutuhan khusus untuk membaca kata sandi dari koneksi database yang sudah dibuka. Nilai default adalah pengaturan yang lebih aman; menggunakan false untuk properti ini membuka aplikasi Anda terhadap risiko keamanan seperti pengelogan true atau pelacakan kata sandi database secara tidak sengaja.
PoolBlockingPeriod	Perilaku periode pemblokiran untuk kumpulan koneksi.
Pooling	Mendapatkan atau menetapkan nilai Boolean yang menunjukkan apakah koneksi akan dikumpulkan atau dibuka secara eksplisit setiap kali koneksi diminta.
Replication	Mendapatkan atau mengatur nilai Boolean yang menunjukkan apakah replikasi didukung menggunakan koneksi.
ServerCertificate	Mendapatkan atau mengatur jalur ke file sertifikat untuk dicocokkan dengan sertifikat TLS/SSL SQL Server untuk koneksi. Format sertifikat yang diterima adalah PEM, DER, dan CER. Jika ditentukan, sertifikat SQL Server diperiksa dengan memverifikasi apakah yang ServerCertificate disediakan sama persis. (Hanya tersedia di v5.1+)
ServerSPN	Mendapatkan atau mengatur nama perwakilan layanan (SPN) sumber data.
TransactionBinding	Mendapatkan atau menetapkan nilai string yang menunjukkan bagaimana koneksi mempertahankan asosiasinya dengan transaksi yang terdaftar System.Transactions .
TransparentNetworkIPResolution	Kedaluwarsa. Pada .NET Framework, ketika nilai kunci ini diatur ke true, driver menjalankan beberapa putaran koneksi di seluruh alamat IP yang diselesaikan DNS, dengan batas waktu per upaya yang semakin besar dan minimum 500 md pada upaya mode berurutan, sampai koneksi berhasil atau keseluruhan Connect Timeout tercapai.
TrustServerCertificate	Mendapatkan atau menetapkan nilai yang menunjukkan apakah saluran akan dienkripsi saat melewati rantai sertifikat untuk memvalidasi kepercayaan.
TypeSystemVersion	Mendapatkan atau mengatur nilai string yang menunjukkan sistem jenis yang diharapkan aplikasi.
UserID	Mendapatkan atau mengatur ID pengguna yang akan digunakan saat menyambungkan ke SQL Server.
UserInstance	Mendapatkan atau menetapkan nilai yang menunjukkan apakah akan mengalihkan koneksi dari instans SQL Server Express default ke instans yang dimulai runtime yang berjalan di bawah akun pemanggil.
Values	Mendapatkan yang ICollection berisi nilai dalam SqlConnectionStringBuilder .
WorkstationID	Mendapatkan atau mengatur nama stasiun kerja yang tersambung ke SQL Server.

Metode

Nama	Deskripsi
Clear()	Menghapus konten instans SqlConnectionStringBuilder .
ContainsKey(String)	Menentukan apakah SqlConnectionStringBuilder berisi kunci tertentu.
Remove(String)	Menghapus entri dengan kunci yang ditentukan dari instans SqlConnectionStringBuilder.
ShouldSerialize(String)	Menunjukkan apakah kunci yang ditentukan ada dalam instans SqlConnectionStringBuilder ini.
TryGetValue(String, Object)	Mengambil nilai yang sesuai dengan kunci yang disediakan dari ini SqlConnectionStringBuilder .