SqlConnectionStringBuilder Classe
Definição
Importante
Algumas informações se referem a produtos de pré-lançamento que podem ser substancialmente modificados antes do lançamento. A Microsoft não oferece garantias, expressas ou implícitas, das informações aqui fornecidas.
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(Microsoft.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))]
public sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilderpublic sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder[<System.ComponentModel.TypeConverter(typeof(Microsoft.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))>]
type SqlConnectionStringBuilder = class
inherit DbConnectionStringBuildertype SqlConnectionStringBuilder = class
inherit DbConnectionStringBuilderPublic 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 do 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.
Note
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=********;initial catalog=AdventureWorks";
// Now that the connection string has been parsed,
// you can work with individual items.
Console.WriteLine(builder.Password);
builder.Password = "********";
// 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 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. 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 execução verifica se há 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", "addr" ou qualquer outro sinônimo aceitável para essa chave em 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 propriedade ConnectionString 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 é 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
| Nome | Description |
|---|---|
| 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
| Nome | Description |
|---|---|
| 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 o Suporte do SqlClient para alta disponibilidade, recuperação de desastre. |
| ApplicationName |
Obtém ou define o nome do aplicativo associado à cadeia de conexão. |
| AsynchronousProcessing |
Obsoleto.
Obsolete. 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. |
| 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 com Microsoft Entra para SQL do Azure recursos. |
| ColumnEncryptionSetting |
Obtém ou define as configurações de criptografia de coluna para o construtor de cadeias 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. |
| ConnectionReset |
Obsoleto.
Obsoleto.
Obsolete. Obtém ou define um valor booliano que indica se a conexão é redefinida quando desenhada do pool de conexões. |
| 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 valor padrão para pontos de extremidade não Azure é 1. Para SQL do Azure pontos de extremidade, 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 êxito 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 ociosas. Um ArgumentException será lançado 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. |
| 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 |
Obsoleto.
Obsolete. Obtém ou define um valor que indica se uma conexão cliente/servidor ou em processo com o SQL Server deve ser feita. |
| CurrentLanguage |
Obtém ou define o idioma usado para mensagens de erro ou aviso 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 à 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 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 pool de conexões SQL Server inseri 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. |
| 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 |
| IdleTimeout |
Obtém ou define o tempo máximo, em segundos, que uma conexão pode ficar sem uso (ocioso) no pool de conexões antes de ser descartada. O padrão é 300 (5 minutos). |
| 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 |
| 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. 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) em sub-redes diferentes, a configuração |
| 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 booliano que indica se informações confidenciais de 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ó deverá ser definida |
| 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. |
| ServerCertificate |
Obtém ou define o caminho para um arquivo de certificado para corresponder ao 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 |
| 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 inscritada |
| TransparentNetworkIPResolution |
Obsoleto.
No .NET Framework, quando o valor dessa chave é definido como |
| 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
| Nome | Description |
|---|---|
| Clear() |
Limpa o conteúdo da SqlConnectionStringBuilder instância. |
| ContainsKey(String) |
Determina se a SqlConnectionStringBuilder chave 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 nesta instância SqlConnectionStringBuilder. |
| TryGetValue(String, Object) |
Recupera um valor correspondente à chave fornecida a partir deste SqlConnectionStringBuilder . |