Udostępnij za pośrednictwem


SqlConnectionStringBuilder Klasa

Definicja

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
[System.ComponentModel.TypeConverter(typeof(Microsoft.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))]
public sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder
public sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder
[<System.ComponentModel.TypeConverter(typeof(Microsoft.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))>]
type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder
type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder
Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder
Dziedziczenie
SqlConnectionStringBuilder
Atrybuty

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.

AsynchronousProcessing
Przestarzałe.

Nieaktualne. Pobiera lub ustawia wartość logiczną wskazującą, czy przetwarzanie asynchroniczne jest dozwolone przez połączenie utworzone przy użyciu tego 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.

ConnectionReset
Przestarzałe.
Przestarzałe.

Nieaktualne. Pobiera lub ustawia wartość logiczną wskazującą, czy połączenie jest resetowane podczas pobierania z puli połączeń.

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.

ContextConnection
Przestarzałe.

Nieaktualne. Pobiera lub ustawia wartość, która wskazuje, czy należy nawiązać połączenie klienta/serwera, czy w procesie z SQL Server.

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

NetworkLibrary

Pobiera lub ustawia ciąg zawierający nazwę biblioteki sieciowej używanej do nawiązania połączenia z SQL Server.

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 .

TransparentNetworkIPResolution

Gdy wartość tego klucza jest ustawiona na true, aplikacja jest wymagana do pobrania wszystkich adresów IP dla określonego wpisu DNS i próby nawiązania połączenia z pierwszym na liście. Jeśli połączenie nie zostanie nawiązane w ciągu 0,5 sekundy, aplikacja spróbuje nawiązać połączenie ze wszystkimi innymi. Po pierwszych odpowiedziach aplikacja nawiąże połączenie z adresem IP respondenta.

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 .

Dotyczy