SqlConnectionStringBuilder Classe

Definição

Fornece uma maneira simples de criar e gerenciar o conteúdo de cadeias de conexão usadas pela classe SqlConnection.

public ref class SqlConnectionStringBuilder sealed : System::Data::Common::DbConnectionStringBuilder
public sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder
[System.ComponentModel.TypeConverter(typeof(System.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))]
public sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder
type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder
[<System.ComponentModel.TypeConverter(typeof(System.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))>]
type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder
Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder
Herança
SqlConnectionStringBuilder
Atributos

Exemplos

O aplicativo de console a seguir cria cadeias de conexão para um banco de dados SQL Server. O código usa uma SqlConnectionStringBuilder classe para criar a cadeia de conexão e, em seguida, passa a ConnectionString propriedade da SqlConnectionStringBuilder instância para o construtor da classe de conexão. O exemplo também analisa uma cadeia de conexão existente e demonstra várias maneiras de manipular o conteúdo da cadeia de conexão.

Observação

Este exemplo inclui uma senha para demonstrar como SqlConnectionStringBuilder funciona com cadeias de conexão. Em seus aplicativos, recomendamos que você use Windows Autenticação. Se você precisar usar uma senha, não inclua uma senha codificada em código em seu aplicativo.

using System.Data;
using System.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";
        builder.AsynchronousProcessing = true;

        // 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";
    }
}
Imports System.Data.SqlClient

Module Module1
    Sub Main()
        ' Create a new SqlConnectionStringBuilder and
        ' initialize it with a few name/value pairs:
        Dim builder As 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"
        builder.AsynchronousProcessing = True

        ' 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

        ' The Item property is the default for the class, 
        ' and setting the Item property adds the value to the 
        ' dictionary, if necessary. 
        builder.Item("Trusted_Connection") = True
        Console.WriteLine(builder.ConnectionString)

        Console.WriteLine("Press Enter to finish.")
        Console.ReadLine()
    End Sub

    Private Function GetConnectionString() As String
        ' 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"
    End Function
End Module

Comentários

O construtor de cadeias de conexão permite que os desenvolvedores criem programaticamente cadeias de conexão sintaticamente corretas e analisem e recompilem cadeias de conexão existentes, usando propriedades e métodos da classe. O construtor de cadeia de conexão fornece propriedades fortemente tipadas correspondentes aos pares chave/valor conhecidos permitidos por SQL Server. Os desenvolvedores que precisam criar cadeias de conexão como parte dos aplicativos podem usar a SqlConnectionStringBuilder classe para criar e modificar cadeias de conexão. A classe também facilita o gerenciamento de cadeias de conexão armazenadas em um arquivo de configuração de aplicativo.

A SqlConnectionStringBuilder verificação de pares chave/valor válidos. Portanto, você não pode usar essa classe para criar cadeias de conexão inválidas; tentar adicionar pares inválidos gerará uma exceção. A classe mantém uma coleção fixa de sinônimos e pode ser convertida de um sinônimo para o nome de chave conhecido correspondente.

Por exemplo, ao usar a propriedade Item para recuperar um valor, você pode especificar uma cadeia de caracteres que contenha qualquer sinônimo para a chave necessária. Por exemplo, você pode especificar "Endereço de Rede", "addr" ou qualquer outro sinônimo aceitável para essa chave dentro de uma cadeia de conexão quando você usa qualquer membro que exija uma cadeia de caracteres que contenha o nome da chave, como a propriedade Item ou o Remove método. Consulte a ConnectionString propriedade para obter uma lista completa de sinônimos aceitáveis.

A propriedade Item manipula tentativas de inserir entradas mal-intencionadas. Por exemplo, o código a seguir, usando a propriedade Item padrão (o indexador, em C#) escapa corretamente do par chave/valor aninhado:

Dim builder As New System.Data.SqlClient.SqlConnectionStringBuilder
builder("Data Source") = "(local)"
builder("Integrated Security") = True
builder("Initial Catalog") = "AdventureWorks;NewValue=Bad"
Console.WriteLine(builder.ConnectionString)
System.Data.SqlClient.SqlConnectionStringBuilder builder =
  new System.Data.SqlClient.SqlConnectionStringBuilder();
builder["Data Source"] = "(local)";
builder["integrated Security"] = true;
builder["Initial Catalog"] = "AdventureWorks;NewValue=Bad";
Console.WriteLine(builder.ConnectionString);

O resultado é a seguinte cadeia de conexão que manipula o valor inválido de maneira segura:

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

Construtores

SqlConnectionStringBuilder()

Inicializa uma nova instância da classe SqlConnectionStringBuilder.

SqlConnectionStringBuilder(String)

Inicializa uma nova instância da classe SqlConnectionStringBuilder. A cadeia de conexão fornecida oferece os dados para obter informações de conexão internas da instância.

Propriedades

ApplicationIntent

Declara o tipo de carga de trabalho do aplicativo ao se conectar a um banco de dados em um grupo de disponibilidade do SQL Server. Você pode definir o valor dessa propriedade para ApplicationIntent. Para saber mais sobre o suporte ao SqlClient para Grupos de Disponibilidade AlwaysOn, confira Suporte do SqlClient para alta disponibilidade e recuperação de desastres.

ApplicationName

Obtém ou define o nome do aplicativo associado à cadeia de conexão.

AsynchronousProcessing

Obtém ou define um valor booliano que indica se o processamento assíncrono é permitido pela conexão criada usando essa cadeia de conexão.

AttachDBFilename

Obtém ou define uma cadeia de caracteres que contém o nome do arquivo de dados primário. Isso inclui o nome de caminho completo de um banco de dados anexável.

Authentication

Obtém a autenticação da cadeia de conexão.

BrowsableConnectionString

Obtém ou define um valor que indica se a propriedade ConnectionString é visível nos designers do Visual Studio.

(Herdado de DbConnectionStringBuilder)
ColumnEncryptionSetting

Obtém ou define a coluna de configurações de criptografia para o construtor de cadeia de conexão.

ConnectionReset
Obsoleto.

Obsoleto. Obtém ou define um valor booliano que indica se a conexão é redefinida quando desenhada com base no pool de conexão.

ConnectionString

Obtém ou define a cadeia de conexão associada a DbConnectionStringBuilder.

(Herdado de DbConnectionStringBuilder)
ConnectRetryCount

O número de tentativas de reconexão após identificar que houve uma falha de conexão ociosa. Esse valor deve ser um inteiro entre 0 e 255. O padrão é UTF-1. Defina como 0 para desabilitar a reconexão em falhas de conexão ociosa. Um ArgumentException será gerado se definido como um valor fora do intervalo permitido.

ConnectRetryInterval

Tempo (em segundos) entre cada tentativa de reconexão após a identificação de uma falha de conexão ociosa. Esse valor deve ser um inteiro entre 1 e 60. O padrão é 10 segundos. Um ArgumentException será gerado se definido como um valor fora do intervalo permitido.

ConnectTimeout

Obtém ou define o tempo (em segundos) de espera por uma conexão com o servidor antes de finalizar a tentativa e gerar um erro.

ContextConnection

Obtém ou define um valor que indica se um cliente/servidor ou conexão em processo para o SQL Server deve ser feita.

Count

Obtém o número atual de chaves contidas na propriedade ConnectionString.

(Herdado de DbConnectionStringBuilder)
CurrentLanguage

Obtém ou define o nome de registro do SQL Server Language.

DataSource

Obtém ou define o nome ou o endereço de rede da instância do SQL Server para conexão.

EnclaveAttestationUrl

Obtém ou define a URL de atestado de enclave a ser usada com Always Encrypted baseado em enclave.

Encrypt

Obtém ou define um valor booliano que indica que o SQL Server usará criptografia SSL para todos os dados enviados entre o cliente e o servidor, se o servidor tiver um certificado instalado.

Enlist

Obtém ou define um valor booliano que indica se o pooler de conexão do SQL Server inscreve automaticamente a conexão no contexto de transação atual do thread de criação.

FailoverPartner

Obtém ou define o nome ou o endereço do servidor parceiro ao qual se conectar se o servidor primário estiver inativo.

InitialCatalog

Obtém ou define o nome do banco de dados associado à conexão.

IntegratedSecurity

Obtém ou define um valor booliano que indica se a ID de Usuário e a Senha são especificadas na conexão (quando false) ou se as atuais credenciais da conta do Windows são usadas para autenticação (quando true).

IsFixedSize

Obtém um valor que indica se o SqlConnectionStringBuilder tem um tamanho fixo.

IsFixedSize

Obtém um valor que indica se o DbConnectionStringBuilder tem um tamanho fixo.

(Herdado de DbConnectionStringBuilder)
IsReadOnly

Obtém um valor que indica se o DbConnectionStringBuilder é somente leitura.

(Herdado de DbConnectionStringBuilder)
Item[String]

Obtém ou define o valor associado à chave especificada. No C#, essa propriedade é o indexador.

Keys

Obtém um ICollection que contém as chaves no SqlConnectionStringBuilder.

LoadBalanceTimeout

Obtém ou define o tempo mínimo, em segundos, para a conexão permanecer no pool de conexão antes de ser destruída.

MaxPoolSize

Obtém ou define o número máximo de conexões permitido no pool de conexão para essa cadeia de conexão específica.

MinPoolSize

Obtém ou define o número mínimo de conexões permitido no pool de conexão para essa cadeia de conexão específica.

MultipleActiveResultSets

Quando for verdadeiro, um aplicativo poderá manter MARS (conjuntos de resultados ativos múltiplos). Quando for falso, um aplicativo deverá processar ou cancelar todos os conjuntos de resultados de um lote antes de poder executar outro lote nessa conexão.

Para obter mais informações, confira MARS (Conjunto de Resultados Ativos Múltiplos).

MultiSubnetFailover

Se o aplicativo estiver se conectando a um ag (grupo de disponibilidade) Always On ou à FCI (Instância de Cluster de Failover) Always On em sub-redes diferentes, definir MultiSubnetFailover=true fornecerá detecção e conexão mais rápidas com o servidor ativo (atualmente). Para obter mais informações sobre o suporte do SqlClient para os recursos de Always On, consulte o Suporte do SqlClient para alta disponibilidade e recuperação de desastre.

NetworkLibrary

Obtém ou define uma cadeia de caracteres que contém o nome da biblioteca de rede usada para estabelecer uma conexão com o SQL Server.

PacketSize

Obtém ou define o tamanho em bytes dos pacotes de rede usados na comunicação com a instância do SQL Server.

Password

Obtém ou define a senha para a conta do SQL Server.

PersistSecurityInfo

Obtém ou define um valor que indica se informações confidenciais à segurança, como a senha ou o token de acesso, devem ser retornadas como parte da cadeia de conexão em uma conexão criada com isso SqlConnectionStringBuilder depois que essa conexão estiver em um estado aberto.

PoolBlockingPeriod

O comportamento do período bloqueio para um pool de conexões.

Pooling

Obtém ou define um valor booliano que indica se a conexão será agrupada em pool ou aberta explicitamente sempre que a conexão for solicitada.

Replication

Obtém ou define um valor booliano que indica se há suporte para replicação usando a conexão.

TransactionBinding

Obtém ou define um valor de cadeia de caracteres que indica como a conexão mantém sua associação com uma transação System.Transactions inscrita.

TransparentNetworkIPResolution

Quando o valor dessa chave é definido como true, o aplicativo é necessário para recuperar todos os endereços IP para uma determinada entrada DNS e tentar se conectar à primeira na lista. Se a conexão não for estabelecida em 0,5 segundos, o aplicativo tentará se conectar a todos os outros paralelamente. Quando o primeiro responder, o aplicativo estabelecerá a conexão com o endereço IP do respondedor.

TrustServerCertificate

Obtém ou define um valor que indica se o canal será criptografado ao ignorar a movimentação da cadeia de certificados para validar a confiança.

TypeSystemVersion

Obtém ou define um valor de cadeia de caracteres que indica o sistema de tipos que o aplicativo espera.

UserID

Obtém ou define a ID de usuário a ser usada ao conectar-se ao SQL Server.

UserInstance

Obtém ou define um valor que indica se é preciso redirecionar a conexão da instância do SQL Server Express padrão para uma instância iniciada pelo runtime em execução sob a conta do chamador.

Values

Obtém um ICollection que contém os valores no SqlConnectionStringBuilder.

WorkstationID

Obtém ou define o nome da estação de trabalho que está se conectando ao SQL Server.

Métodos

Add(String, Object)

Adiciona uma entrada com a chave e o valor especificados ao DbConnectionStringBuilder.

(Herdado de DbConnectionStringBuilder)
Clear()

Limpa o conteúdo da instância SqlConnectionStringBuilder.

ClearPropertyDescriptors()

Limpa a coleção de objetos PropertyDescriptor no DbConnectionStringBuilder associado.

(Herdado de DbConnectionStringBuilder)
ContainsKey(String)

Determina se a SqlConnectionStringBuilder contém uma chave específica.

Equals(Object)

Determina se o objeto especificado é igual ao objeto atual.

(Herdado de Object)
EquivalentTo(DbConnectionStringBuilder)

Compara as informações de conexão neste objeto DbConnectionStringBuilder com as informações de conexão no objeto fornecido.

(Herdado de DbConnectionStringBuilder)
GetHashCode()

Serve como a função de hash padrão.

(Herdado de Object)
GetProperties(Hashtable)

Preenche um Hashtable fornecido com informações sobre todas as propriedades deste DbConnectionStringBuilder.

(Herdado de DbConnectionStringBuilder)
GetType()

Obtém o Type da instância atual.

(Herdado de Object)
MemberwiseClone()

Cria uma cópia superficial do Object atual.

(Herdado de Object)
Remove(String)

Remove a entrada com a chave especificada da instância de SqlConnectionStringBuilder.

ShouldSerialize(String)

Indica se a chave especificada existe nessa instância SqlConnectionStringBuilder.

ToString()

Retorna a cadeia de conexão associada a esse DbConnectionStringBuilder.

(Herdado de DbConnectionStringBuilder)
TryGetValue(String, Object)

Recupera um valor correspondente para a chave fornecida deste SqlConnectionStringBuilder.

Implantações explícitas de interface

ICollection.CopyTo(Array, Int32)

Copia os elementos do ICollection para um Array, começando em um determinado índice Array.

(Herdado de DbConnectionStringBuilder)
ICollection.IsSynchronized

Obtém um valor que indica se o acesso à ICollection é sincronizado (thread-safe).

(Herdado de DbConnectionStringBuilder)
ICollection.SyncRoot

Obtém um objeto que pode ser usado para sincronizar o acesso ao ICollection.

(Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetAttributes()

Retorna uma coleção de atributos personalizados para esta instância de um componente.

(Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetClassName()

Retorna o nome de classe desta instância de um componente.

(Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetComponentName()

Retorna o nome desta instância de um componente.

(Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetConverter()

Retorna um conversor de tipo para esta instância de um componente.

(Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetDefaultEvent()

Retorna o evento padrão para esta instância de um componente.

(Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetDefaultProperty()

Retorna a propriedade padrão para esta instância de um componente.

(Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetEditor(Type)

Retorna um editor do tipo especificado para esta instância de um componente.

(Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetEvents()

Retorna os eventos desta instância de um componente.

(Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetEvents(Attribute[])

Retorna os eventos desta instância de um componente usando a matriz de atributos especificada como um filtro.

(Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetProperties()

Retorna as propriedades desta instância de um componente.

(Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetProperties(Attribute[])

Retorna as propriedades desta instância de um componente usando a matriz de atributos como um filtro.

(Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetPropertyOwner(PropertyDescriptor)

Retorna um objeto que contém a propriedade descrita pelo descritor de propriedade especificado.

(Herdado de DbConnectionStringBuilder)
IDictionary.Add(Object, Object)

Adiciona um elemento com a chave e o valor fornecidos ao objeto IDictionary.

(Herdado de DbConnectionStringBuilder)
IDictionary.Contains(Object)

Determina se o objeto IDictionary contém um elemento com a chave especificada.

(Herdado de DbConnectionStringBuilder)
IDictionary.GetEnumerator()

Retorna um objeto IDictionaryEnumerator para o objeto IDictionary.

(Herdado de DbConnectionStringBuilder)
IDictionary.IsFixedSize

Obtém um valor que indica se o objeto IDictionary tem um tamanho fixo.

(Herdado de DbConnectionStringBuilder)
IDictionary.IsReadOnly

Obtém um valor que indica se o IDictionary é somente leitura.

(Herdado de DbConnectionStringBuilder)
IDictionary.Item[Object]

Obtém ou define o elemento com a chave especificada.

(Herdado de DbConnectionStringBuilder)
IDictionary.Remove(Object)

Remove o elemento com a chave especificada do objeto IDictionary.

(Herdado de DbConnectionStringBuilder)
IEnumerable.GetEnumerator()

Retorna um enumerador que itera em uma coleção.

(Herdado de DbConnectionStringBuilder)

Métodos de Extensão

Cast<TResult>(IEnumerable)

Converte os elementos de um IEnumerable para o tipo especificado.

OfType<TResult>(IEnumerable)

Filtra os elementos de um IEnumerable com base em um tipo especificado.

AsParallel(IEnumerable)

Habilita a paralelização de uma consulta.

AsQueryable(IEnumerable)

Converte um IEnumerable em um IQueryable.

Aplica-se a

Confira também