SqlConnectionStringBuilder Classe

Definição

Namespace:

Microsoft.Data.SqlClient

Assembly:

Microsoft.Data.SqlClient.dll

Pacote:

Microsoft.Data.SqlClient v5.2.0

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

type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder

Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder

Herança

DbConnectionStringBuilder

SqlConnectionStringBuilder

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 o 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 um cadeia de conexão existente e demonstra várias maneiras de manipular o conteúdo do 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 a Autenticação do Windows. Se você precisar usar uma senha, não inclua uma senha codificada em código em seu aplicativo.

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

Comentários

O construtor de cadeia 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 tipdas correspondentes aos pares chave/valor conhecidos permitidos por SQL Server. Os desenvolvedores que precisam criar cadeias de conexão como parte de 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.

O 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 um 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.

Os identificadores da propriedade Item tentam 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 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);  

O resultado é o 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.
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.
AttestationProtocol	Obtém ou define o valor do Protocolo de Atestado.
Authentication	Obtém ou define o método de autenticação usado para conectar-se a Banco de Dados SQL usando a Autenticação do Azure Active Directory.
ColumnEncryptionSetting	Obtém ou define a coluna de configurações de criptografia para o construtor de cadeia de conexão.
CommandTimeout	O tempo de espera padrão (em segundos) antes de encerrar a tentativa de executar um comando e gerar um erro. O padrão é 30 segundos.
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 valor padrão para pontos de extremidade que não são do Azure é 1. Para pontos de extremidade SQL do Azure, o padrão é 2. A partir da versão 5.x, para SQL do Azure pontos de extremidade sem servidor ou sob demanda, o padrão é 5 para melhorar o sucesso da conexão para conexões com uma instância ociosa ou pausada. 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.
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.
CurrentLanguage	Obtém ou define o idioma usado para mensagens de aviso ou erro do servidor de banco de dados.
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 baseadas em enclave.
Encrypt	Obtém ou define um SqlConnectionEncryptOption valor desde a versão 5.0 ou um Boolean valor para as versões anteriores que indica se a criptografia TLS é necessária para todos os dados enviados entre o cliente e o servidor.
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.
FailoverPartnerSPN	Obtém ou define o SPN (nome da entidade de serviço) do parceiro de failover para a conexão.
HostNameInCertificate	Obtém ou define o nome do host a ser usado ao validar o certificado do servidor para a conexão. Quando não especificado, o nome do servidor do Data Source é usado para validação de certificado. (Disponível apenas na v5.0+)
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).
IPAddressPreference	Obtém ou define a preferência da família de endereços IP ao estabelecer conexões TCP.
IsFixedSize	Obtém um valor que indica se o SqlConnectionStringBuilder tem um tamanho fixo.
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 seu aplicativo estiver se conectando a um AG (grupo de disponibilidade) AlwaysOn em diferentes sub-redes, definir MultiSubnetFailover como true fornece uma detecção e uma conexão mais rápida ao servidor (atualmente) ativo. 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.
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 booliano que indica se informações confidenciais à segurança, como a senha ou o token de acesso, devem ser retornadas como parte do cadeia de conexão em uma conexão criada com isso SqlConnectionStringBuilder depois que essa conexão estiver em um estado aberto. Essa propriedade só deve ser definida true como se seu aplicativo tiver uma necessidade específica de ler a senha de uma conexão de banco de dados já aberta. O valor padrão de false é a configuração mais segura; usar true para essa propriedade abre seu aplicativo para riscos de segurança, como fazer logon acidentalmente ou rastrear a senha do banco de dados.
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.
ServerCertificate	Obtém ou define o caminho para um arquivo de certificado a ser correspondido com o certificado TLS/SSL SQL Server para a conexão. Os formatos de certificado aceitos são PEM, DER e CER. Se especificado, o certificado SQL Server será verificado verificando se o ServerCertificate fornecido é uma correspondência exata. (Disponível apenas na v5.1+)
ServerSPN	Obtém ou define o SPN (nome da entidade de serviço) da fonte de dados.
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.
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

Clear()	Limpa o conteúdo da instância SqlConnectionStringBuilder.
ContainsKey(String)	Determina se a SqlConnectionStringBuilder contém uma chave específica.
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.
TryGetValue(String, Object)	Recupera um valor correspondente para a chave fornecida deste SqlConnectionStringBuilder.