SqlConnectionStringBuilder Klasa

Definicja

Przestrzeń nazw:

Microsoft.Data.SqlClient

Zestaw:

Microsoft.Data.SqlClient.dll

Pakiet:

Microsoft.Data.SqlClient v5.2.0

Zapewnia prosty sposób tworzenia zawartości parametrów połączenia używanych przez klasę SqlConnection i zarządzania nimi.

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

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

type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder

Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder

Dziedziczenie

DbConnectionStringBuilder

SqlConnectionStringBuilder

Przykłady

Poniższa aplikacja konsolowa tworzy parametry połączenia dla bazy danych SQL Server. Kod używa SqlConnectionStringBuilder klasy do utworzenia parametry połączenia, a następnie przekazuje ConnectionString właściwość SqlConnectionStringBuilder wystąpienia do konstruktora klasy połączenia. Przykład analizuje również istniejącą parametry połączenia i demonstruje różne sposoby manipulowania zawartością parametry połączenia.

Uwaga

Ten przykład zawiera hasło, które pokazuje, jak SqlConnectionStringBuilder działa z parametrami połączenia. W aplikacjach zalecamy użycie uwierzytelniania systemu Windows. Jeśli musisz użyć hasła, nie dołączaj w aplikacji trwale zakodowanego hasła.

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= a!Pass113;initial catalog=AdventureWorks";

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

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

Uwagi

Konstruktor parametry połączenia umożliwia deweloperom programowe tworzenie składniowo poprawnych parametrów połączenia oraz analizowanie i ponowne kompilowanie istniejących parametrów połączenia przy użyciu właściwości i metod klasy. Konstruktor parametry połączenia udostępnia silnie typizowane właściwości odpowiadające znanym parom klucz/wartość dozwolonym przez SQL Server. Deweloperzy, którzy muszą tworzyć parametry połączenia w ramach aplikacji, mogą używać SqlConnectionStringBuilder klasy do tworzenia i modyfikowania parametrów połączenia. Klasa ułatwia również zarządzanie parametrami połączenia przechowywanymi w pliku konfiguracji aplikacji.

Funkcja SqlConnectionStringBuilder wykonuje testy prawidłowych par klucz/wartość. W związku z tym nie można użyć tej klasy do utworzenia nieprawidłowych parametrów połączenia; Próba dodania nieprawidłowych par zgłosi wyjątek. Klasa utrzymuje stałą kolekcję synonimów i może tłumaczyć się z synonimu na odpowiednią dobrze znaną nazwę klucza.

Jeśli na przykład używasz właściwości Item do pobrania wartości, możesz określić ciąg zawierający dowolny synonim potrzebnego klucza. Można na przykład określić "Adres sieciowy", "addr" lub dowolny inny akceptowalny synonim tego klucza w parametry połączenia, gdy używasz dowolnego elementu członkowskiego wymagającego ciągu zawierającego nazwę klucza, takiego jak właściwość Item lub Remove metoda. Zobacz właściwość , ConnectionString aby uzyskać pełną listę dopuszczalnych synonimów.

Właściwość Item próbuje wstawić złośliwe wpisy. Na przykład poniższy kod, używając domyślnej właściwości Item (indeksator w języku C#) poprawnie ucieka przed zagnieżdżonym parą klucz/wartość:

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

Wynik jest następujący parametry połączenia, który obsługuje nieprawidłową wartość w bezpieczny sposób:

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

Konstruktory

SqlConnectionStringBuilder()	Inicjuje nowe wystąpienie klasy SqlConnectionStringBuilder.
SqlConnectionStringBuilder(String)	Inicjuje nowe wystąpienie klasy SqlConnectionStringBuilder. Podany parametry połączenia dostarcza dane dla informacji o połączeniu wewnętrznym wystąpienia.

Właściwości

ApplicationIntent	Deklaruje typ obciążenia aplikacji podczas nawiązywania połączenia z bazą danych w grupie dostępności SQL Server. Wartość tej właściwości można ustawić za pomocą polecenia ApplicationIntent. Aby uzyskać więcej informacji na temat obsługi klienta SqlClient dla zawsze włączonych grup dostępności, zobacz SqlClient Support for High Availability, Disaster Recovery (Obsługa klienta Sql Dla wysokiej dostępności i odzyskiwania po awarii).
ApplicationName	Pobiera lub ustawia nazwę aplikacji skojarzonej z parametry połączenia.
AttachDBFilename	Pobiera lub ustawia ciąg zawierający nazwę podstawowego pliku danych. Obejmuje to pełną nazwę ścieżki dołączanej bazy danych.
AttestationProtocol	Pobiera lub ustawia wartość protokołu zaświadczania.
Authentication	Pobiera lub ustawia metodę uwierzytelniania używaną do nawiązywania połączenia z SQL Database przy użyciu uwierzytelniania usługi Azure Active Directory.
ColumnEncryptionSetting	Pobiera lub ustawia ustawienia szyfrowania kolumn dla konstruktora parametry połączenia.
CommandTimeout	Domyślny czas oczekiwania (w sekundach) przed zakończeniem próby wykonania polecenia i wygenerowaniu błędu. Wartość domyślna to 30 sekund.
ConnectRetryCount	Liczba ponownych połączeń podjęta po zidentyfikowaniu, że wystąpił błąd bezczynności połączenia. Musi to być liczba całkowita z zakresu od 0 do 255. Wartość domyślna dla punktów końcowych spoza platformy Azure to 1. W przypadku Azure SQL punktów końcowych wartość domyślna to 2. Począwszy od wersji 5.x, dla Azure SQL bezserwerowych lub na żądanie punktów końcowych, wartość domyślna to 5, aby poprawić powodzenie połączenia dla połączeń z bezczynnym lub wstrzymanym wystąpieniem. Ustaw wartość 0, aby wyłączyć ponowne nawiązywanie połączenia w przypadku niepowodzeń bezczynności połączenia. Wartość ArgumentException zostanie wyrzucona, jeśli zostanie ustawiona na wartość spoza dozwolonego zakresu.
ConnectRetryInterval	Czas (w sekundach) między każdą ponowną próbą nawiązania połączenia po zidentyfikowaniu, że wystąpił błąd bezczynności połączenia. Musi to być liczba całkowita z zakresu od 1 do 60. Wartość domyślna to 10 sekund.
ConnectTimeout	Pobiera lub ustawia czas oczekiwania na połączenie z serwerem (w sekundach) przed zakończeniem próby i wygenerowaniem błędu.
CurrentLanguage	Pobiera lub ustawia język używany na potrzeby ostrzeżeń serwera bazy danych lub komunikatów o błędach.
DataSource	Pobiera lub ustawia nazwę lub adres sieciowy wystąpienia SQL Server, z którymi ma nawiązać połączenie.
EnclaveAttestationUrl	Pobiera lub ustawia adres URL zaświadczania enklawy, który ma być używany z enklawą opartą Always Encrypted.
Encrypt	Pobiera lub ustawia SqlConnectionEncryptOption wartość od wersji 5.0 lub Boolean wartość dla wcześniejszych wersji, która wskazuje, czy szyfrowanie TLS jest wymagane dla wszystkich danych wysyłanych między klientem a serwerem.
Enlist	Pobiera lub ustawia wartość logiczną wskazującą, czy SQL Server puli połączeń automatycznie zaciąga połączenie w bieżącym kontekście transakcji wątku tworzenia.
FailoverPartner	Pobiera lub ustawia nazwę lub adres serwera partnerskiego, z którymi ma nawiązać połączenie, jeśli serwer podstawowy nie działa.
FailoverPartnerSPN	Pobiera lub ustawia nazwę główną usługi (SPN) partnera trybu failover dla połączenia.
HostNameInCertificate	Pobiera lub ustawia nazwę hosta do użycia podczas sprawdzania poprawności certyfikatu serwera dla połączenia. Jeśli nie zostanie określona, nazwa serwera z elementu Data Source jest używana do weryfikacji certyfikatu. (Dostępne tylko w wersji 5.0 lub nowszej)
InitialCatalog	Pobiera lub ustawia nazwę bazy danych skojarzonej z połączeniem.
IntegratedSecurity	Pobiera lub ustawia wartość logiczną wskazującą, czy identyfikator użytkownika i hasło są określone w połączeniu (gdy false) lub czy bieżące poświadczenia konta systemu Windows są używane do uwierzytelniania (gdy true).
IPAddressPreference	Pobiera lub ustawia preferencję rodziny adresów IP podczas nawiązywania połączeń TCP.
IsFixedSize	Pobiera wartość wskazującą, czy element SqlConnectionStringBuilder ma stały rozmiar.
Item[String]	Pobiera lub ustawia wartość skojarzona z określonym kluczem. W języku C# ta właściwość jest indeksatorem.
Keys	Pobiera element ICollection zawierający klucze w obiekcie SqlConnectionStringBuilder.
LoadBalanceTimeout	Pobiera lub ustawia minimalny czas (w sekundach) dla połączenia na żywo w puli połączeń przed zniszczeniem.
MaxPoolSize	Pobiera lub ustawia maksymalną liczbę połączeń dozwolonych w puli połączeń dla tej konkretnej parametry połączenia.
MinPoolSize	Pobiera lub ustawia minimalną liczbę połączeń dozwolonych w puli połączeń dla tego konkretnego parametry połączenia.
MultipleActiveResultSets	W przypadku wartości true aplikacja może obsługiwać wiele aktywnych zestawów wyników (MARS). W przypadku wartości false aplikacja musi przetworzyć lub anulować wszystkie zestawy wyników z jednej partii, zanim będzie mogła wykonać dowolną inną partię w tym połączeniu. Aby uzyskać więcej informacji, zobacz Wiele aktywnych zestawów wyników (MARS).
MultiSubnetFailover	Jeśli aplikacja łączy się z zawsze włączoną grupą dostępności w różnych podsieciach, ustawienie parametru MultiSubnetFailover=true zapewnia szybsze wykrywanie i nawiązywanie połączenia z (obecnie) aktywnym serwerem. Aby uzyskać więcej informacji na temat obsługi klienta SqlClient dla zawsze włączonych grup dostępności, zobacz SqlClient Support for High Availability, Disaster Recovery (Obsługa klienta Sql Dla wysokiej dostępności i odzyskiwania po awarii).
PacketSize	Pobiera lub ustawia rozmiar w bajtach pakietów sieciowych używanych do komunikowania się z wystąpieniem SQL Server.
Password	Pobiera lub ustawia hasło dla konta SQL Server.
PersistSecurityInfo	Pobiera lub ustawia wartość logiczną wskazującą, czy informacje poufne zabezpieczeń, takie jak hasło lub token dostępu, powinny być zwracane w ramach parametry połączenia w połączeniu utworzonym z tym SqlConnectionStringBuilder po wystąpieniu tego połączenia w stanie otwartym. Tę właściwość należy ustawić true tylko wtedy, gdy aplikacja musi odczytać hasło z już otwartego połączenia z bazą danych. Wartość domyślna false to bezpieczniejsze ustawienie. Użycie true tej właściwości powoduje otwarcie aplikacji na zagrożenia bezpieczeństwa, takie jak przypadkowe rejestrowanie lub śledzenie hasła bazy danych.
PoolBlockingPeriod	Zachowanie okresu blokowania dla puli połączeń.
Pooling	Pobiera lub ustawia wartość logiczną wskazującą, czy połączenie zostanie w puli, czy jawnie otwarte za każdym razem, gdy jest wymagane połączenie.
Replication	Pobiera lub ustawia wartość logiczną wskazującą, czy replikacja jest obsługiwana przy użyciu połączenia.
ServerCertificate	Pobiera lub ustawia ścieżkę do pliku certyfikatu, aby był zgodny z certyfikatem TLS/SSL SQL Server dla połączenia. Akceptowane formaty certyfikatów to PEM, DER i CER. Jeśli zostanie określony, certyfikat SQL Server jest sprawdzany przez sprawdzenie, czy ServerCertificate podane jest dokładne dopasowanie. (Dostępne tylko w wersji 5.1 lub nowszej)
ServerSPN	Pobiera lub ustawia nazwę główną usługi (SPN) źródła danych.
TransactionBinding	Pobiera lub ustawia wartość parametrów, która wskazuje, w jaki sposób połączenie utrzymuje jego skojarzenie z transakcją zaciągniętą System.Transactions .
TrustServerCertificate	Pobiera lub ustawia wartość wskazującą, czy kanał będzie szyfrowany podczas pomijania chodzenia przez łańcuch certyfikatów w celu zweryfikowania zaufania.
TypeSystemVersion	Pobiera lub ustawia wartość ciągu, która wskazuje system typów oczekiwany przez aplikację.
UserID	Pobiera lub ustawia identyfikator użytkownika, który ma być używany podczas nawiązywania połączenia z SQL Server.
UserInstance	Pobiera lub ustawia wartość wskazującą, czy przekierować połączenie z domyślnego wystąpienia SQL Server Express do wystąpienia zainicjowanego przez środowisko uruchomieniowe uruchomione na koncie obiektu wywołującego.
Values	Pobiera element ICollection zawierający wartości w obiekcie SqlConnectionStringBuilder.
WorkstationID	Pobiera lub ustawia nazwę stacji roboczej łączącej się z SQL Server.

Metody

Clear()	Czyści zawartość SqlConnectionStringBuilder wystąpienia.
ContainsKey(String)	Określa, czy element SqlConnectionStringBuilder zawiera określony klucz.
Remove(String)	Usuwa wpis z określonym kluczem SqlConnectionStringBuilder z wystąpienia.
ShouldSerialize(String)	Wskazuje, czy określony klucz istnieje w tym SqlConnectionStringBuilder wystąpieniu.
TryGetValue(String, Object)	Pobiera wartość odpowiadającą podanemu kluczowi z tego SqlConnectionStringBuilderelementu .