Sintaxe da cadeia de conexão

  • Artigo

Aplicável a: .NET Framework .NET .NET Standard

Baixar ADO.NET

O Microsoft.Data.SqlClient tem um objeto Connection que herda de DbConnection, além de uma propriedade ConnectionString específica do provedor. A sintaxe da cadeia de conexão específica para o provedor SqlClient está documentada na propriedade ConnectionString. Para obter mais informações sobre a sintaxe da cadeia de conexão, consulte ConnectionString.

Construtores de cadeia de conexão

O Provedor de Dados Microsoft SqlClient para SQL Server introduziu o construtor de cadeias de conexão a seguir.

Os construtores de cadeia de conexão permitem que você construa cadeias de conexão sintaticamente válidas em tempo de execução, para que você não precise concatenar manualmente os valores de cadeia de conexão no seu código. Para obter mais informações, confira Construtores de cadeias de conexão.

Autenticação do Windows

Recomendamos o uso da Autenticação do Windows (às vezes chamada de segurança integrada) para se conectar a fontes de dados que dão suporte a ela. A tabela a seguir mostra a sintaxe da Autenticação do Windows usada com o Provedor de Dados Microsoft SqlClient para SQL Server.

Provedor Syntax
SqlClient Integrated Security=true;

-- or --

Integrated Security=SSPI;

Cadeias de conexão SqlClient

A sintaxe para uma cadeia de conexão SqlConnection está documentada na propriedade SqlConnection.ConnectionString. Você pode usar a propriedade ConnectionString para obter ou definir uma cadeia de conexão para um banco de dados do SQL Server. As palavras-chave da cadeia de conexão também são mapeadas para as propriedades no SqlConnectionStringBuilder.

Importante

A configuração padrão para a palavra-chave Persist Security Info é false. Configurá-lo como true ou yes permite informações confidenciais de segurança, incluindo a identificação de usuário e a senha, para serem obtidas da conexão depois que ela tiver sido aberta. Mantenha Persist Security Info definida como false para garantir que uma fonte não confiável não tenha acesso a informações confidenciais da cadeia de conexão.

Autenticação do Windows com SqlClient

Cada uma das formas de sintaxe a seguir usa a Autenticação do Windows para se conectar ao banco de dados AdventureWorks em um servidor local.

"Persist Security Info=False;Integrated Security=true;  
    Initial Catalog=AdventureWorks;Server=MSSQL1;Encrypt=True;"  
"Persist Security Info=False;Integrated Security=SSPI;  
    database=AdventureWorks;server=(local);Encrypt=True;"  
"Persist Security Info=False;Trusted_Connection=True;  
    database=AdventureWorks;server=(local);Encrypt=True;"

Autenticação do SQL Server com SqlClient

A Autenticação do Windows é preferencial para se conectar ao SQL Server. No entanto, se a Autenticação do SQL Server for necessária, use a seguinte sintaxe para especificar um nome de usuário e uma senha. Nesse exemplo, os asteriscos são usados para representar um nome de usuário e uma senha válidos.

"Persist Security Info=False;User ID=*****;Password=*****;Initial Catalog=AdventureWorks;Server=MySqlServer;Encrypt=True;"

Quando você se conectar com o Banco de Dados SQL do Azure ou ao Azure Synapse Analytics e fornecer um nome de usuário no formato user@servername, verifique se o valor servername no nome de usuário corresponde ao valor fornecido para Server=.

Observação

A autenticação do Windows tem precedência sobre logons do SQL Server. Se você especificar Integrated Security=true assim como um nome de usuário e uma senha, o nome de usuário e a senha serão ignorados e a autenticação do Windows será usada.

Conectar-se a uma instância nomeada do SQL Server

Para se conectar a uma instância nomeada do SQL Server, use a sintaxe server name\instance name.

"Data Source=MySqlServer\MSSQL1;"

Você também pode definir a propriedade DataSource de SqlConnectionStringBuilder para o nome da instância ao criar uma cadeia de conexão. A propriedade DataSource de um objeto SqlConnection é somente leitura.

Alterações de versão do sistema de tipos

A palavra-chave Type System Version em um SqlConnection.ConnectionString especifica a representação do lado do cliente de tipos do SQL Server. Para obter mais informações sobre a palavra-chave Type System Version, confira SqlConnection.ConnectionString.

Conectar e anexar as instâncias de usuário do SQL Server Express

As instâncias de usuário são um recurso no SQL Server Express. Elas permitem que um usuário que esteja executando uma conta local do Windows com menos privilégios anexe e execute um banco de dados do SQL Server sem exigir privilégios administrativos. Uma instância de usuário é executada com as credenciais do Windows do usuário, não como um serviço.

Para obter mais informações sobre como trabalhar com instâncias de usuário, confira Instâncias de usuário do SQL Server Express.

Usar o TrustServerCertificate

A palavra-chave TrustServerCertificate é usada ao se conectar a uma instância de SQL Server. Quando TrustServerCertificate é definida como true, a camada de transporte usa TLS/SSL para criptografar o canal, deixando de passar pela cadeia de certificado para validar a confiança.

  • Em versões anteriores ao Microsoft.Data.SqlClient 2.0, essa configuração é ignorada quando Encrypt é definida como False e o certificado do servidor não é validado.
  • A partir da versão 2.0 do Microsoft.Data.SqlClient, mesmo que Encrypt esteja definido False, a configuração controla se a validação do certificado é executada quando o servidor força a criptografia.
  • A partir da versão 5.0 do Microsoft.Data.SqlClient, essa configuração é ignorada quando Encrypt é definida como Strict. O certificado do servidor sempre é validado no modo Strict.

Para obter mais informações, veja Criptografia e validação de certificado.

"TrustServerCertificate=true;"

HostNameInCertificate

A partir da versão 5.0 do Microsoft.Data.SqlClient, HostNameInCertificate é uma nova opção de conexão. O certificado de servidor garante que o CN (Nome Comum) ou o SAN (Nome Alternativo da Entidade) no certificado corresponda ao nome do servidor com o qual está conectado. Em alguns casos, como aliases DNS, o nome do servidor pode não corresponder ao CN nem ao SAN. O valor HostNameInCertificate pode ser usado para especificar um CN ou SAN diferente esperado no certificado do servidor.

"HostNameInCertificate=myserver.example.com"

ServerCertificate

A partir da versão 5.1 do Microsoft.Data.SqlClient, ServerCertificate é uma nova opção de conexão. O valor padrão da configuração de conexão ServerCertificate é uma cadeia de caracteres vazia. Quando Encrypt é definido como Mandatory ou Strict, ServerCertificate pode ser usado para especificar um caminho no sistema de arquivos para um arquivo de certificado que corresponda ao certificado TLS do servidor. Para o certificado ser validade, o certificado especificado precisa ser uma correspondência exata. Os formatos de certificado aceitos são PEM, DER e CER. Veja um exemplo:

"Data Source=...;Encrypt=Strict;ServerCertificate=C:\certificates\server.cer"

Habilitar criptografia

Defina a propriedade de conexão Confiar no certificado do servidor como True para habilitar a criptografia quando um certificado não tiver sido provisionado no servidor. Neste caso, a criptografia usa um certificado do servidor autoassinado sem validação, pois nenhum certificado verificável foi provisionado no servidor.

As configurações do aplicativo não podem reduzir o nível de segurança configurado no SQL Server, mas podem, opcionalmente, reforçá-lo. Um aplicativo pode solicitar a criptografia definindo as palavras-chave TrustServerCertificate e Encrypt como true, a fim de garantir que a criptografia ocorra mesmo se um certificado do servidor não tiver sido provisionado. No entanto, se TrustServerCertificate não estiver ativado na configuração do cliente, um certificado do servidor provisionado ainda será necessário.

A tabela a seguir descreve todos os casos.

Criptografar atributos/cadeias de conexão Cadeia de conexão/atributo do Certificado do Servidor de Confiança Result
Não/Opcional Ignored Não ocorre criptografia.
Sim/obrigatório Não A criptografia só ocorrerá se houver um certificado do servidor verificável; caso contrário, a tentativa de conexão falhará.
Sim/obrigatório Sim A criptografia sempre ocorre, mas pode usar um certificado do servidor autoassinado.
Estrito1 Ignored A criptografia sempre ocorre e deve usar um certificado do servidor verificável; caso contrário, a tentativa de conexão falha.

1 A criptografia estrita só está disponível a partir do Microsoft.Data.SqlClient versão 5.0.

Para obter mais informações, incluindo o comportamento em versões anteriores, confira Criptografia e validação de certificado.

Confira também

Cadeias de conexão
Criptografia e validação de certificado
Conectar-se a fontes de dados
Microsoft ADO.NET for SQL Server