SqlConnectionStringBuilder Classe

Definição

Espaço de Nomes:: System.Data.SqlClient

Assemblagem:: System.Data.dll

Importante

Algumas informações dizem respeito a um produto pré-lançado que pode ser substancialmente modificado antes de ser lançado. A Microsoft não faz garantias, de forma expressa ou implícita, em relação à informação aqui apresentada.

Fornece uma forma simples de criar e gerir o conteúdo das strings de ligação usadas pela SqlConnection classe.

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

A seguinte aplicação de consola constrói strings de ligação para uma base de dados SQL Server. O código utiliza a classe SqlConnectionStringBuilder para criar a cadeia de ligação. O exemplo analisa então a cadeia de ligação e demonstra várias formas de manipular o seu 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

Observações

O cadeia de ligação builder permite aos programadores criar cadeias de ligação sintaticamente corretas, e analisar e reconstruir cadeias de ligação existentes, usando propriedades e métodos da classe. O construtor de cadeia de ligação fornece propriedades fortemente tipadas correspondentes aos pares chave/valor conhecidos permitidos pelo SQL Server. Se precisares de criar strings de ligação como parte da tua aplicação, podes usar a SqlConnectionStringBuilder classe para construir e modificar strings de ligação. A classe também facilita a gestão de cadeias de ligação armazenadas num ficheiro de configuração de aplicação.

SqlConnectionStringBuilder realiza verificações para pares chave/valor válidos. Portanto, não pode usar esta classe para criar cadeias de ligação inválidas; Tentar adicionar pares inválidos gera uma exceção. A classe mantém uma coleção fixa de sinónimos e pode ser traduzida de um sinónimo para o nome de chave conhecido correspondente.

Por exemplo, quando usas a Item propriedade para recuperar um valor, podes especificar uma string que contenha qualquer sinónimo da chave de que precisas. Por exemplo, pode especificar "Endereço de Rede", "addr" ou qualquer outro sinónimo aceitável para esta chave dentro de uma cadeia de ligação quando usar qualquer membro que exija uma string que contenha o nome da chave, como a propriedade Item[String] ou o método Remove. Consulte a ConnectionString propriedade para uma lista completa de sinónimos aceitáveis.

A Item[String] propriedade trata de tentativas de inserir entradas maliciosas. Por exemplo, o código seguinte, usando a propriedade padrão Item (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 ligação que trata o valor inválido de forma segura:

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

Construtores

Name	Description
SqlConnectionStringBuilder()	Inicializa uma nova instância da SqlConnectionStringBuilder classe.
SqlConnectionStringBuilder(String)	Inicializa uma nova instância da SqlConnectionStringBuilder classe. A cadeia de ligação fornecida fornece os dados para a informação interna de ligação da instância.

Propriedades

Name	Description
ApplicationIntent	Declara o tipo de carga de trabalho da aplicação ao ligar-se a uma base de dados num Grupo de Disponibilidade do SQL Server. Pode definir o valor desta propriedade com ApplicationIntent. Para obter mais informações sobre o suporte do SqlClient para Grupos de Disponibilidade Always On, consulte Suporte do SqlClient para Alta Disponibilidade, Recuperação de Desastres.
ApplicationName	Recebe ou define o nome da aplicação associada à cadeia de ligação.
AsynchronousProcessing	Obtém ou define um valor booleano que indica se o processamento assíncrono é permitido pela ligação criada ao usar esta cadeia de ligação.
AttachDBFilename	Recebe ou define uma cadeia que contém o nome do ficheiro de dados principal. Isto inclui o nome completo do caminho de uma base de dados anexável.
Authentication	Obtém a autenticação da cadeia de ligação.
BrowsableConnectionString	Obtém ou define um valor que indica se a propriedade ConnectionString é visível em Visual Studio designers. (Herdado de DbConnectionStringBuilder)
ColumnEncryptionSetting	Obtém ou define as definições de encriptação das colunas para o cadeia de ligação builder.
ConnectionReset	Obsoleto. Obsolete. Recebe ou define um valor Booleano que indica se a ligação é reiniciada quando retirada do pool de ligações.
ConnectionString	Obtém ou define o cadeia de ligação associado ao DbConnectionStringBuilder. (Herdado de DbConnectionStringBuilder)
ConnectRetryCount	O número de reconexões tentadas após identificar uma falha de ligação em inatividade. Este deve ser um número inteiro entre 0 e 255. A predefinição é 1. Definir para 0 para desativar a reconexão em caso de falhas de ligação inativa. An será lançado se for ArgumentException definido para um valor fora do intervalo permitido.
ConnectRetryInterval	Quantidade de tempo (em segundos) entre cada tentativa de reconexão após a identificação de uma falha de ligação em inatividade. Este deve ser um número inteiro entre 1 e 60. O padrão é 10 segundos. An será lançado se for ArgumentException definido para um valor fora do intervalo permitido.
ConnectTimeout	Obtém ou define o tempo (em segundos) para esperar uma ligação ao servidor antes de terminar a tentativa e gerar um erro.
ContextConnection	Recebe ou define um valor que indica se deve ser feita uma ligação cliente/servidor ou em processo ao SQL Server.
Count	Obtém o número atual de chaves contidas na ConnectionString propriedade. (Herdado de DbConnectionStringBuilder)
CurrentLanguage	Obtém ou define o nome do registo SQL Server Language.
DataSource	Obtém ou define o nome ou o endereço de rede da instância do SQL Server para se ligar.
EnclaveAttestationUrl	Obtém ou define o URL de atestação do enclave para ser usado com o Always Encrypted baseado no enclave.
Encrypt	Recebe ou define um valor booleano que indica se o SQL Server utiliza encriptação SSL para todos os dados enviados entre o cliente e o servidor, caso o servidor tenha um certificado instalado.
Enlist	Recebe ou define um valor Booleano que indica se o pooler de ligação do SQL Server regista automaticamente a ligação no contexto atual da transação do thread de criação.
FailoverPartner	Obtém ou define o nome ou o endereço do servidor parceiro para se ligar se o servidor principal estiver em baixo.
InitialCatalog	Obtém ou define o nome da base de dados associada à ligação.
IntegratedSecurity	Recebe ou define um valor booleano que indica se o ID de Utilizador e a Palavra-passe estão especificados na ligação (quando `false`) ou se as credenciais atuais da conta 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 é apenas de leitura. (Herdado de DbConnectionStringBuilder)
Item[String]	Obtém ou define o valor associado à chave especificada. Em C#, esta 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 ligação permanecer no pool de ligação antes de ser destruída.
MaxPoolSize	Obtém ou define o número máximo de ligações permitidas no pool de ligações para esta cadeia de ligação específica.
MinPoolSize	Obtém ou define o número mínimo de ligações permitidas no pool de ligações para esta cadeia de ligaçã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 Vários conjuntos de resultados ativos (MARS).
MultiSubnetFailover	Se a sua aplicação estiver a ligar-se a um grupo de disponibilidade Always On (AG) ou a uma Instância de Cluster de Failover Always On (FCI) em sub-redes diferentes, definir MultiSubnetFailover=true proporciona uma deteção e ligação mais rápidas ao servidor (atualmente) ativo. Para mais informações sobre o suporte SqlClient para as funcionalidades Always On, consulte Suporte SqlClient para Alta Disponibilidade, Recuperação de Desastres.
NetworkLibrary	Obtém ou define uma cadeia que contém o nome da biblioteca de rede usada para estabelecer uma ligação ao SQL Server.
PacketSize	Obtém ou define o tamanho em bytes dos pacotes de rede usados para comunicar com uma instância do SQL Server.
Password	Obtém ou define a palavra-passe da conta do SQL Server.
PersistSecurityInfo	Recebe ou define um valor que indica se informações sensíveis à segurança, como a palavra-passe ou o token de acesso, devem ser devolvidas como parte do cadeia de ligação numa ligação criada com este SqlConnectionStringBuilder depois de essa ligação alguma vez ter estado aberto.
PoolBlockingPeriod	O comportamento do período de bloqueio para um pool de ligações.
Pooling	Recebe ou define um valor Booleano que indica se a ligação será agrupada ou aberta explicitamente sempre que a ligação for solicitada.
Replication	Recebe ou define um valor Booleano que indica se a replicação é suportada através da ligação.
TransactionBinding	Recebe ou define um valor de cadeia que indica como a ligação mantém a sua associação com uma transação de enrolado `System.Transactions` .
TransparentNetworkIPResolution	Quando o valor desta chave é definido para `true`, a aplicação é obrigada a recuperar todos os endereços IP de uma determinada entrada DNS e tentar ligar-se ao primeiro da lista. Se a ligação não for estabelecida dentro de 0,5 segundos, a aplicação tentará ligar-se a todas as outras em paralelo. Quando o primeiro responde, a aplicação estabelecerá a ligação com o endereço IP do respondente.
TrustServerCertificate	Obtém ou define um valor que indica se o canal será encriptado, ignorando a percorrência da cadeia de certificados para validar a confiança.
TypeSystemVersion	Recebe ou define um valor de cadeia que indica o sistema de tipos que a aplicação espera.
UserID	Obtém ou define o ID de utilizador a ser usado ao ligar-se ao SQL Server.
UserInstance	Recebe ou define um valor que indica se deve redirecionar a ligação da instância padrão do SQL Server Express para uma instância iniciada em tempo de execução a correr sob a conta do chamador.
Values	Obtém-se um ICollection que contém os valores no SqlConnectionStringBuilder.
WorkstationID	Obtém ou define o nome da estação de trabalho que se liga ao SQL Server.

Métodos

Name	Description
Add(String, Object)	Adiciona uma entrada com a chave e valor especificados no DbConnectionStringBuilder. (Herdado de DbConnectionStringBuilder)
Clear()	Limpa o conteúdo da SqlConnectionStringBuilder instância.
ClearPropertyDescriptors()	Limpa a coleção de PropertyDescriptor objetos no .DbConnectionStringBuilder (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 a informação de ligação neste DbConnectionStringBuilder objeto com a informação de ligação no objeto fornecido. (Herdado de DbConnectionStringBuilder)
GetHashCode()	Serve como função de hash predefinida. (Herdado de Object)
GetProperties(Hashtable)	Preenche um fornecimento Hashtable 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 atual Object. (Herdado de Object)
Remove(String)	Remove a entrada com a chave especificada da SqlConnectionStringBuilder instância.
ShouldSerialize(String)	Indica se a chave especificada existe neste SqlConnectionStringBuilder caso.
ToString()	Devolve o cadeia de ligação associado a este DbConnectionStringBuilder. (Herdado de DbConnectionStringBuilder)
TryGetValue(String, Object)	Recupera um valor correspondente à chave fornecida a partir desta SqlConnectionStringBuilder.

Implementações de Interface Explícita

Name	Description
ICollection.CopyTo(Array, Int32)	Copia os elementos do ICollection para um Array, começando num índice particular Array . (Herdado de DbConnectionStringBuilder)
ICollection.IsSynchronized	Recebe 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()	Devolve uma coleção de atributos personalizados para esta instância de um componente. (Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetClassName()	Devolve o nome da classe desta instância de um componente. (Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetComponentName()	Devolve o nome desta instância de um componente. (Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetConverter()	Devolve um conversor de tipos para esta instância de um componente. (Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetDefaultEvent()	Devolve o evento predefinido para esta instância de um componente. (Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetDefaultProperty()	Devolve a propriedade padrão para esta instância de um componente. (Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetEditor(Type)	Devolve um editor do tipo especificado para esta instância de um componente. (Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetEvents()	Devolve os eventos para esta instância de um componente. (Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetEvents(Attribute[])	Devolve os eventos para esta instância de um componente usando o array de atributos especificado como filtro. (Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetProperties()	Devolve as propriedades para esta instância de um componente. (Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetProperties(Attribute[])	Devolve as propriedades para esta instância de um componente usando o array de atributos como filtro. (Herdado de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetPropertyOwner(PropertyDescriptor)	Devolve um objeto que contém a propriedade descrita pelo descritor de propriedades especificado. (Herdado de DbConnectionStringBuilder)
IDictionary.Add(Object, Object)	Adiciona um elemento com a chave e o valor fornecidos ao IDictionary objeto. (Herdado de DbConnectionStringBuilder)
IDictionary.Contains(Object)	Determina se o IDictionary objeto contém um elemento com a chave especificada. (Herdado de DbConnectionStringBuilder)
IDictionary.GetEnumerator()	Devolve um IDictionaryEnumerator objeto para o IDictionary objeto. (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 IDictionary objeto. (Herdado de DbConnectionStringBuilder)
IEnumerable.GetEnumerator()	Devolve um enumerador que itera numa coleção. (Herdado de DbConnectionStringBuilder)

Métodos da Extensão

Name	Description
AsParallel(IEnumerable)	Permite a paralelização de uma consulta.
AsQueryable(IEnumerable)	Converte um IEnumerable para um IQueryable.
Cast<TResult>(IEnumerable)	Conjura os elementos de an IEnumerable para o tipo especificado.
OfType<TResult>(IEnumerable)	Filtra os elementos de um IEnumerable com base num tipo especificado.

Aplica-se a

Ver também

Cadeias de Ligação (ADO.NET)
Visão geral ADO.NET

Comentários

Esta página foi útil?