SqlConnectionStringBuilder Classe

Definição

Namespace:

System.Data.SqlClient

Assembly:

System.Data.dll

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

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

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

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

Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder

Herança

Object

DbConnectionStringBuilder

SqlConnectionStringBuilder

Atributos

TypeConverterAttribute

Exemplos

O aplicativo de console a seguir cria cadeias de conexão para um banco de dados do SQL Server. O código usa a classe SqlConnectionStringBuilder para criar a cadeia de conexão. Em seguida, o exemplo analisa a cadeia de conexão e demonstra várias maneiras de manipular o conteúdo.

// Create a new SqlConnectionStringBuilder and
// initialize it with a few name/value pairs.
SqlConnectionStringBuilder builder = new(
    "Server=(local);Integrated Security=true;" +
    "Initial Catalog=AdventureWorks"
    );

// The input connection string used the
// Server key, but the new connection string uses
// the well-known Data Source key instead.
Console.WriteLine($"Original connection string: '{builder.ConnectionString}'");

// Now that the connection string has been parsed,
// you can work with individual items.
Console.WriteLine($"Initial catalog: '{builder.InitialCatalog}'");
builder.InitialCatalog = "Northwind";
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($"Modified connection string: '{builder.ConnectionString}'");

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(
            "Server=(local);Integrated Security=true;" &
            "Initial Catalog=AdventureWorks"
            )

        ' The input connection string used the 
        ' Server key, but the new connection string uses
        ' the well-known Data Source key instead.
        Console.WriteLine("Original connection string: " + builder.ConnectionString)

        ' Now that the connection string has been parsed,
        ' you can work with individual items.
        Console.WriteLine("Initial catalog: " + builder.InitialCatalog)
        builder.InitialCatalog = "Northwind"
        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("Modified connection string: " + builder.ConnectionString)
    End Sub
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 pelo SQL Server. Se você precisar criar cadeias de conexão como parte do seu aplicativo, poderá usar a classe SqlConnectionStringBuilder 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.

SqlConnectionStringBuilder executa verificações 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 traduzir 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", "complemento" 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[String] ou o método Remove. Consulte a propriedade ConnectionString para obter uma lista completa de sinônimos aceitáveis.

A propriedade Item[String] 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 fornece os dados para as informações de conexão interna 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 com ApplicationIntent. Para obter mais informações sobre o suporte do SqlClient para Grupos de Disponibilidade AlwaysOn, consulte Suporte do SqlClient para alta disponibilidade,de recuperação de desastre.
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 completo do caminho 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 está visível em designers do Visual Studio. (Herdado de DbConnectionStringBuilder)
ColumnEncryptionSetting	Obtém ou define as configurações de criptografia de coluna para o construtor de cadeias de conexão.
ConnectionReset	Obsoleto. Obsoleto. Obtém ou define um valor booliano que indica se a conexão é redefinida quando desenhada do pool de conexões.
ConnectionString	Obtém ou define a cadeia de conexão associada ao DbConnectionStringBuilder. (Herdado de DbConnectionStringBuilder)
ConnectRetryCount	O número de reconexões tentadas após identificar que houve uma falha de conexão ociosa. Isso deve ser um inteiro entre 0 e 255. O padrão é 1. Defina como 0 para desabilitar a reconexão em falhas de conexão ociosas. 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 identificar que houve uma falha de conexão ociosa. Isso 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) para aguardar uma conexão com o servidor antes de encerrar a tentativa e gerar um erro.
ContextConnection	Obtém ou define um valor que indica se uma conexão cliente/servidor ou em processo com 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 do registro de idioma do SQL Server.
DataSource	Obtém ou define o nome ou o endereço de rede da instância do SQL Server à qual se conectar.
EnclaveAttestationUrl	Obtém ou define a URL de atestado do enclave a ser usada com o Always Encrypted baseado em enclave.
Encrypt	Obtém ou define um valor booliano que indica se o SQL Server usa 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ões do SQL Server insera automaticamente a conexão no contexto de transação atual do thread de criação.
FailoverPartner	Obtém ou define o nome ou 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 credenciais atuais 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.
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. Em 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 que a conexão resida no pool de conexões antes de ser destruída.
MaxPoolSize	Obtém ou define o número máximo de conexões permitidas no pool de conexões para essa cadeia de conexão específica.
MinPoolSize	Obtém ou define o número mínimo de conexões permitidas no pool de conexões para essa cadeia de conexão específica.
MultipleActiveResultSets	Quando verdadeiro, um aplicativo pode manter vários conjuntos de resultados ativos (MARS). Quando falso, um aplicativo deve processar ou cancelar todos os conjuntos de resultados de um lote antes de poder executar qualquer outro lote nessa conexão. Para obter mais informações, consulte mars (conjuntos de resultados ativos múltiplos).
MultiSubnetFailover	Se o aplicativo estiver se conectando a um AG (grupo de disponibilidade AlwaysOn) ou à FCI (Instância de Cluster de Failover AlwaysOn) em sub-redes diferentes, definir MultiSubnetFailover=true fornecerá uma 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 always on, consulte Suporte do SqlClient para alta disponibilidade,de 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 para se comunicar com uma instância do SQL Server.
Password	Obtém ou define a senha da conta do SQL Server.
PersistSecurityInfo	Obtém ou define um valor que indica se informações confidenciais de 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 esse SqlConnectionStringBuilder depois que essa conexão estiver em um estado aberto.
PoolBlockingPeriod	O comportamento do período de bloqueio para um pool de conexões.
Pooling	Obtém ou define um valor booliano que indica se a conexão será agrupada 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 inscritada.
TransparentNetworkIPResolution	Quando o valor dessa chave é definido como true, o aplicativo é necessário para recuperar todos os endereços IP para uma entrada DNS específica e tentar se conectar com o primeiro da lista. Se a conexão não for estabelecida dentro de 0,5 segundos, o aplicativo tentará se conectar a todas as outras em paralelo. Quando as primeiras respostas forem respondidas, o aplicativo estabelecerá a conexão com o endereço IP do entrevistado.
TrustServerCertificate	Obtém ou define um valor que indica se o canal será criptografado ao ignorar a 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 do usuário a ser usada ao se conectar ao SQL Server.
UserInstance	Obtém ou define um valor que indica se a conexão deve ser redirecionada da instância padrão do SQL Server Express para uma instância iniciada por runtime em execução na 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 se conecta 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 de SqlConnectionStringBuilder.
ClearPropertyDescriptors()	Limpa a coleção de objetos PropertyDescriptor no DbConnectionStringBuilderassociado. (Herdado de DbConnectionStringBuilder)
ContainsKey(String)	Determina se o 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 Objectatual. (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 nesta instância SqlConnectionStringBuilder.
ToString()	Retorna a cadeia de conexão associada a esse DbConnectionStringBuilder. (Herdado de DbConnectionStringBuilder)
TryGetValue(String, Object)	Recupera um valor correspondente à 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 índice Array específico. (Herdado de DbConnectionStringBuilder)
ICollection.IsSynchronized	Obtém um valor que indica se o acesso ao 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 da classe dessa instância de um componente. (Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetComponentName()	Retorna o nome dessa 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 para esta instância de um componente. (Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetEvents(Attribute[])	Retorna os eventos dessa instância de um componente usando a matriz de atributo especificada como um filtro. (Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetProperties()	Retorna as propriedades dessa instância de um componente. (Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetProperties(Attribute[])	Retorna as propriedades dessa 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.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 por meio de 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.

Confira também

• de cadeias de conexão (ADO.NET)
• visão geral ADO.NET