SqlConnectionStringBuilder Třída

Definice

Obor názvů:

Microsoft.Data.SqlClient

Sestavení:

Microsoft.Data.SqlClient.dll

Balíček:

Microsoft.Data.SqlClient v7.1.0

Poskytuje jednoduchý způsob, jak vytvořit a spravovat obsah připojovacích řetězců používaných SqlConnection třídy.

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

Dědičnost

DbConnectionStringBuilder

SqlConnectionStringBuilder

Atributy

TypeConverterAttribute

Příklady

Následující konzolová aplikace sestaví připojovací řetězce pro databázi SQL Serveru. Kód používá SqlConnectionStringBuilder třídu k vytvoření připojovací řetězec a pak předá ConnectionString vlastnost SqlConnectionStringBuilder instance konstruktoru třídy připojení. Příklad také analyzuje existující připojovací řetězec a ukazuje různé způsoby manipulace s obsahem připojovací řetězec.

Note

Tento příklad obsahuje heslo, které ukazuje, jak SqlConnectionStringBuilder funguje s připojovacími řetězci. Ve svých aplikacích doporučujeme používat ověřování systému Windows. Pokud musíte použít heslo, nezahrnujte do aplikace pevně zakódované heslo.

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

Poznámky

Tvůrce připojovacích řetězců umožňuje vývojářům programově vytvářet syntakticky správné připojovací řetězce a parsovat a znovu sestavit existující připojovací řetězce pomocí vlastností a metod třídy. Tvůrce připojovacích řetězců poskytuje vlastnosti silného typu odpovídající známým párům klíč/hodnota povolených SQL Serverem. Vývojáři, kteří potřebují vytvářet připojovací řetězce v rámci aplikací, můžou pomocí SqlConnectionStringBuilder třídy vytvářet a upravovat připojovací řetězce. Třída také usnadňuje správu připojovacích řetězců uložených v konfiguračním souboru aplikace.

Provádí SqlConnectionStringBuilder kontroly platných párů klíč/hodnota. Proto nelze tuto třídu použít k vytvoření neplatných připojovacích řetězců; při pokusu o přidání neplatných dvojic dojde k výjimce. Třída udržuje pevnou kolekci synonym a může přeložit ze synonyma na odpovídající dobře známý název klíče.

Když například použijete vlastnost Item k načtení hodnoty, můžete zadat řetězec, který obsahuje jakékoli synonymum pro klíč, který potřebujete. Můžete například zadat "Síťová adresa", "addr" nebo jakýkoli jiný přijatelný synonymum pro tento klíč v rámci připojovací řetězec při použití libovolného člena, který vyžaduje řetězec obsahující název klíče, například Item vlastnost nebo metoduRemove. Úplný seznam přijatelných synonym najdete ve vlastnosti ConnectionString.

Vlastnost Item se pokusí vložit škodlivé položky. Například následující kód pomocí výchozí vlastnosti Item (indexer, v jazyce C#) správně ukazuje dvojici vnořených klíč/hodnota:

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

Výsledkem je následující připojovací řetězec, který bezpečně zpracovává neplatnou hodnotu:

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

Konstruktory

Název	Description
SqlConnectionStringBuilder()	Inicializuje novou instanci SqlConnectionStringBuilder třídy.
SqlConnectionStringBuilder(String)	Inicializuje novou instanci SqlConnectionStringBuilder třídy. Zadaný připojovací řetězec poskytuje data pro interní informace o připojení instance.

Vlastnosti

Název	Description
ApplicationIntent	Deklaruje typ úlohy aplikace při připojování k databázi ve skupině dostupnosti SQL Serveru. Hodnotu této vlastnosti můžete nastavit pomocí ApplicationIntent. Další informace o podpoře SqlClient pro skupiny dostupnosti AlwaysOn naleznete v tématu Podpora SqlClient pro vysokou dostupnost, zotavení po havárii.
ApplicationName	Získá nebo nastaví název aplikace přidružené k připojovacímu řetězci.
AttachDBFilename	Získá nebo nastaví řetězec, který obsahuje název primárního datového souboru. To zahrnuje úplný název cesty připojitelné databáze.
AttestationProtocol	Získá nebo nastaví hodnotu Attestation Protocol.
Authentication	Získá nebo nastaví metodu ověřování použitou pro Connect with Microsoft Entra na Azure SQL prostředky.
ColumnEncryptionSetting	Získá nebo nastaví nastavení šifrování sloupce pro tvůrce připojovacích řetězců.
CommandTimeout	Výchozí doba čekání (v sekundách) před ukončením pokusu o spuštění příkazu a vygenerováním chyby. Výchozí hodnota je 30 sekund.
ConnectionReset	Zastaralé. Obsolete. Získá nebo nastaví logickou hodnotu, která označuje, zda se připojení resetuje při vykreslení z fondu připojení.
ConnectRetryCount	Počet pokusů o opětovné připojení po zjištění, že došlo k selhání nečinného připojení. Musí to být celé číslo od 0 do 255. Výchozí hodnota pro koncové body, které nejsou Azure, je 1. U koncových bodů Azure SQL je výchozí hodnota 2. Počínaje verzí 5.x pro Azure SQL bezserverové koncové body nebo koncové body na vyžádání je výchozí 5, aby se zlepšil úspěch připojení pro připojení k nečinné nebo pozastavené instanci. Nastavte na hodnotu 0 a zakažte opětovné připojení při selhání nečinných připojení. Pokud ArgumentException je nastavená hodnota mimo povolený rozsah, vyvolá se chyba.
ConnectRetryInterval	Doba (v sekundách) mezi jednotlivými pokusy o opětovné připojení po zjištění, že došlo k selhání nečinného připojení. Musí to být celé číslo od 1 do 60. Výchozí hodnota je 10 sekund.
ConnectTimeout	Získá nebo nastaví dobu (v sekundách) počkat na připojení k serveru před ukončením pokusu a vygenerováním chyby.
CurrentLanguage	Získá nebo nastaví jazyk použitý pro upozornění databázového serveru nebo chybové zprávy..
DataSource	Získá nebo nastaví název nebo síťovou adresu instance SQL Serveru pro připojení.
EnclaveAttestationUrl	Získá nebo nastaví adresu URL ověření identity enklávy, která se má použít s enklávou založenou na funkci Always Encrypted.
Encrypt	Získá nebo nastaví SqlConnectionEncryptOption hodnotu od verze 5.0 nebo Boolean hodnotu pro starší verze, která indikuje, zda je šifrování TLS vyžadováno pro všechna data odesílaná mezi klientem a serverem.
Enlist	Získá nebo nastaví logickou hodnotu, která určuje, zda SQL Server fond připojení automaticky zapíše připojení do kontextu aktuální transakce vlákna vytvoření.
FailoverPartner	Získá nebo nastaví název nebo adresu partnerského serveru pro připojení, pokud je primární server dole.
FailoverPartnerSPN	Získá nebo nastaví hlavní název služby (SPN) partnera pro převzetí služeb při selhání pro připojení.
HostNameInCertificate	Získá nebo nastaví název hostitele, který se má použít při ověřování certifikátu serveru pro připojení. Pokud ho nezadáte, použije se název serveru z Data Source ověření certifikátu. (K dispozici pouze ve verzi 5.0+)
IdleTimeout	Získá nebo nastaví maximální dobu v sekundách, po kterou může připojení sedět nevyužité (nečinné) ve fondu připojení předtím, než se zruší. Výchozí hodnota je 300 (5 minut).
InitialCatalog	Získá nebo nastaví název databáze přidružené k připojení.
IntegratedSecurity	Získá nebo nastaví logickou hodnotu, která označuje, zda jsou ID uživatele a heslo zadány v připojení (když false ) nebo zda aktuální Windows přihlašovací údaje účtu se používají k ověřování (když true ).
IPAddressPreference	Získá nebo nastaví předvolbu rodiny IP adres při navazování připojení TCP.
IsFixedSize	Získá hodnotu, která označuje, zda SqlConnectionStringBuilder má pevnou velikost.
Item[String]	Získá nebo nastaví hodnotu přidruženou k zadanému klíči. V jazyce C# je tato vlastnost indexerem.
Keys	ICollection Získá, který obsahuje klíče v objektu SqlConnectionStringBuilder.
LoadBalanceTimeout	Získá nebo nastaví minimální dobu v sekundách, aby připojení žilo ve fondu připojení před zničením.
MaxPoolSize	Získá nebo nastaví maximální počet připojení povolených ve fondu připojení pro tento konkrétní připojovací řetězec.
MinPoolSize	Získá nebo nastaví minimální počet připojení povolených ve fondu připojení pro tento konkrétní připojovací řetězec.
MultipleActiveResultSets	Pokud je pravda, může aplikace udržovat více aktivních sad výsledků (MARS). Pokud je hodnota false, musí aplikace zpracovat nebo zrušit všechny sady výsledků z jedné dávky, aby bylo možné na daném připojení spustit jakoukoli jinou dávku. Další informace naleznete v tématu Více aktivních sad výsledků (MARS).
MultiSubnetFailover	Pokud se vaše aplikace připojuje ke skupině dostupnosti AlwaysOn v různých podsítích, poskytuje nastavení MultiSubnetFailover=true rychlejší detekci a připojení k (aktuálně) aktivnímu serveru. Další informace o podpoře SqlClient pro skupiny dostupnosti AlwaysOn naleznete v tématu Podpora SqlClient pro vysokou dostupnost, zotavení po havárii.
NetworkLibrary	Získá nebo nastaví řetězec, který obsahuje název síťové knihovny použité k navázání připojení k SQL Serveru.
PacketSize	Získá nebo nastaví velikost v bajtech síťových paketů používaných ke komunikaci s instancí SQL Serveru.
Password	Získá nebo nastaví heslo pro účet SQL Serveru.
PersistSecurityInfo	Získá nebo nastaví logickou hodnotu označující, jestli jsou citlivé na zabezpečení, jako je heslo nebo přístupový token, by se měly vrátit jako součást připojovací řetězec v připojení vytvořeném s tímto SqlConnectionStringBuilder připojením po tomto připojení v otevřeném stavu. Tato vlastnost by měla být nastavena true pouze v případě, že vaše aplikace potřebuje přečíst heslo z již otevřeného připojení k databázi. Výchozí hodnota false je bezpečnější nastavení. Použití true této vlastnosti otevře aplikaci na bezpečnostní rizika, jako je náhodné protokolování nebo trasování hesla databáze.
PoolBlockingPeriod	Chování blokujícího období pro fond připojení.
Pooling	Získá nebo nastaví logickou hodnotu, která označuje, zda bude připojení ve fondu nebo explicitně otevřeno při každém vyžádání připojení.
Replication	Získá nebo nastaví logickou hodnotu, která označuje, zda je replikace podporována pomocí připojení.
ServerCertificate	Získá nebo nastaví cestu k souboru certifikátu, aby se shodovaly s SQL Server certifikátEM TLS/SSL pro připojení. Přijaté formáty certifikátů jsou PEM, DER a CER. Pokud je zadáno, zkontroluje se certifikát SQL Server ověřením, jestli zadané ServerCertificate certifikáty přesně odpovídají. (K dispozici pouze ve verzi 5.1+)
ServerSPN	Získá nebo nastaví hlavní název služby (SPN) zdroje dat.
TransactionBinding	Získá nebo nastaví řetězcovou hodnotu, která označuje, jak připojení udržuje své přidružení k zařazení System.Transactions transakce.
TransparentNetworkIPResolution	Zastaralé. Pokud je hodnota tohoto klíče nastavená truena .NET Framework, ovladač spustí více kol připojení napříč IP adresami přeloženými DNS s postupně většími časovými limity pro jednotlivé pokusy a minimálním limitem 500 ms při pokusu o sekvenční režim, dokud připojení nebude úspěšné nebo celkový Connect Timeout počet.
TrustServerCertificate	Získá nebo nastaví hodnotu, která označuje, zda kanál bude zašifrován při obejití procházení řetězu certifikátů k ověření důvěryhodnosti.
TypeSystemVersion	Získá nebo nastaví řetězcovou hodnotu, která označuje typ systému, který aplikace očekává.
UserID	Získá nebo nastaví ID uživatele, které se má použít při připojování k SQL Serveru.
UserInstance	Získá nebo nastaví hodnotu, která určuje, zda se má přesměrovat připojení z výchozí instance SQL Server Express na instanci spuštěnou za běhu spuštěnou pod účtem volajícího.
Values	ICollection Získá, který obsahuje hodnoty v objektu SqlConnectionStringBuilder .
WorkstationID	Získá nebo nastaví název pracovní stanice, která se připojuje k SQL Serveru.

Metody

Název	Description
Clear()	Vymaže obsah SqlConnectionStringBuilder instance.
ContainsKey(String)	Určuje, zda SqlConnectionStringBuilder obsahuje konkrétní klíč.
Remove(String)	Odebere položku se zadaným klíčem z instance SqlConnectionStringBuilder.
ShouldSerialize(String)	Určuje, zda zadaný klíč existuje v této instanci SqlConnectionStringBuilder.
TryGetValue(String, Object)	Načte z tohoto SqlConnectionStringBuilder klíče hodnotu odpovídající zadanému klíči .