Sintaxe da cadeia de conexãoConnection String Syntax

Cada provedor de dados .NET Framework tem um objeto de Connection que herda de DbConnection bem como de uma propriedade ConnectionString específica do provedor.Each .NET Framework data provider has a Connection object that inherits from DbConnection as well as a provider-specific ConnectionString property. A sintaxe específica da cadeia de conexão para cada provedor está documentada em sua propriedade ConnectionString.The specific connection string syntax for each provider is documented in its ConnectionString property. A tabela a seguir lista os quatro provedores de dados que estão incluídos no .NET Framework.The following table lists the four data providers that are included in the .NET Framework.

Provedor de dados .NET Framework.NET Framework data provider DescriptionDescription
System.Data.SqlClient Fornece acesso a dados para o Microsoft SQL Server.Provides data access for Microsoft SQL Server. Para obter mais informações sobre a sintaxe da cadeia de conexão, consulte ConnectionString.For more information on connection string syntax, see ConnectionString.
System.Data.OleDb Fornece acesso a dados para as fontes de dados expostas usando OLE DB.Provides data access for data sources exposed using OLE DB. Para obter mais informações sobre a sintaxe da cadeia de conexão, consulte ConnectionString.For more information on connection string syntax, see ConnectionString.
System.Data.Odbc Fornece acesso a dados para as fontes de dados expostas usando ODBC.Provides data access for data sources exposed using ODBC. Para obter mais informações sobre a sintaxe da cadeia de conexão, consulte ConnectionString.For more information on connection string syntax, see ConnectionString.
System.Data.OracleClient Fornece acesso a dados para Oracle versão 8.1.7 ou posterior.Provides data access for Oracle version 8.1.7 or later. Para obter mais informações sobre a sintaxe da cadeia de conexão, consulte ConnectionString.For more information on connection string syntax, see ConnectionString.

Construtores de cadeia de conexãoConnection String Builders

O ADO.NET 2.0 introduziu os seguintes construtores de cadeia de conexão para provedores de dados .NET Framework.ADO.NET 2.0 introduced the following connection string builders for the .NET Framework data providers.

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 tenha que manualmente concatenar os valores de cadeia de conexão no seu código.The connection string builders allow you to construct syntactically valid connection strings at run time, so you do not have to manually concatenate connection string values in your code. Para obter mais informações, confira Construtores de cadeias de conexão.For more information, see Connection String Builders.

Autenticação do WindowsWindows Authentication

É recomendável usar a autenticação do Windows (às vezes conhecida como segurança integrada) para se conectar a fontes de dados que dão suporte a ela.We recommend using Windows Authentication (sometimes referred to as integrated security) to connect to data sources that support it. A sintaxe empregada na cadeia de conexão varia de acordo com o provedor.The syntax employed in the connection string varies by provider. A tabela a seguir mostra a sintaxe de Autenticação do Windows usada com os provedores de dados .NET Framework.The following table shows the Windows Authentication syntax used with the .NET Framework data providers.

ProvedorProvider SyntaxSyntax
SqlClient Integrated Security=true;

-- or --

Integrated Security=SSPI;
OleDb Integrated Security=SSPI;
Odbc Trusted_Connection=yes;
OracleClient Integrated Security=yes;

Observação

O Integrated Security=true gera uma exceção quando usado com o provedor OleDb.Integrated Security=true throws an exception when used with the OleDb provider.

Cadeias de conexão do SqlClientSqlClient Connection Strings

A sintaxe para uma cadeia de conexão SqlConnection está documentada na propriedade SqlConnection.ConnectionString.The syntax for a SqlConnection connection string is documented in the SqlConnection.ConnectionString property. Você pode usar a propriedade ConnectionString para obter ou definir uma cadeia de conexão para um banco de dados do SQL Server.You can use the ConnectionString property to get or set a connection string for a SQL Server database. Se você precisar de conexão a uma versão anterior do SQL Server, você deve usar o provedor de dados .NET Framework para OleDb (System.Data.OleDb).If you need to connect to an earlier version of SQL Server, you must use the .NET Framework Data Provider for OleDb (System.Data.OleDb). A maioria das palavras-chave de cadeia de conexão também mapeiam para as propriedades no SqlConnectionStringBuilder.Most connection string keywords also map to properties in the SqlConnectionStringBuilder.

Importante

A configuração padrão para a Persist Security Info palavra-chave é false .The default setting for the Persist Security Info keyword is 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.Setting it to true or yes allows security-sensitive information, including the user ID and password, to be obtained from the connection after the connection has been opened. Mantenha Persist Security Info definido como false para garantir que uma fonte não confiável não tenha acesso às informações de cadeia de conexão confidenciais.Keep Persist Security Info set to false to ensure that an untrusted source does not have access to sensitive connection string information.

Autenticação do Windows com SqlClientWindows authentication with 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.Each of the following forms of syntax uses Windows Authentication to connect to the AdventureWorks database on a local server.

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

Autenticação de SQL Server com SqlClientSQL Server authentication with SqlClient

A Autenticação do Windows é preferencial para se conectar ao SQL Server.Windows Authentication is preferred for connecting to 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.However, if SQL Server Authentication is required, use the following syntax to specify a user name and password. Nesse exemplo, os asteriscos são usados para representar um nome de usuário e uma senha válidos.In this example, asterisks are used to represent a valid user name and password.

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

Quando você se conectar ao banco de dados SQL do Azure ou ao SQL Data Warehouse do Azure e fornecer um logon no formato user@servername , verifique se o servername valor no logon corresponde ao valor fornecido para Server= .When you connect to Azure SQL Database or to Azure SQL Data Warehouse and provide a login in the format user@servername, make sure that the servername value in the login matches the value provided for Server=.

Observação

A autenticação do Windows tem precedência sobre logons do SQL Server.Windows authentication takes precedence over SQL Server logins. 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.If you specify both Integrated Security=true as well as a user name and password, the user name and password will be ignored and Windows authentication will be used.

Conectar-se a uma instância nomeada do SQL ServerConnect to a named instance of SQL Server

Para se conectar a uma instância nomeada do SQL Server, use a sintaxe de nome \ instância do servidor .To connect to a named instance of SQL Server, use the server name\instance name syntax.

"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.You can also set the DataSource property of the SqlConnectionStringBuilder to the instance name when building a connection string. A propriedade DataSource de um objeto SqlConnection é somente leitura.The DataSource property of a SqlConnection object is read-only.

Alterações de versão do sistema de tiposType System Version Changes

A Type System Version palavra-chave em um SqlConnection.ConnectionString especifica a representação do lado do cliente de tipos de SQL Server.The Type System Version keyword in a SqlConnection.ConnectionString specifies the client-side representation of SQL Server types. Consulte SqlConnection.ConnectionString para obter mais informações sobre a palavra-chave Type System Version.See SqlConnection.ConnectionString for more information about the Type System Version keyword.

Conectando e anexando a instâncias de usuário do SQL Server ExpressConnecting and Attaching to SQL Server Express User Instances

As instâncias de usuário são um recurso no SQL Server Express.User instances are a feature in 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.They allow a user running on a least-privileged local Windows account to attach and run a SQL Server database without requiring administrative privileges. Uma instância de usuário é executada com as credenciais do Windows do usuário, não como um serviço.A user instance executes with the user's Windows credentials, not as a service.

Para obter mais informações sobre como trabalhar com instâncias de usuário, consulte SQL Server Express instâncias de usuário.For more information on working with user instances, see SQL Server Express User Instances.

Usando TrustServerCertificateUsing TrustServerCertificate

A TrustServerCertificate palavra-chave é válida somente ao se conectar a uma instância do SQL Server com um certificado válido.The TrustServerCertificate keyword is valid only when connecting to a SQL Server instance with a valid certificate. Quando TrustServerCertificate estiver definido como true, a camada de transporte usará SSL para criptografar o canal e não precisar passar pela verificação da cadeia do certificado para validar a confiança.When TrustServerCertificate is set to true, the transport layer will use SSL to encrypt the channel and bypass walking the certificate chain to validate trust.

"TrustServerCertificate=true;"

Observação

Se TrustServerCertificate estiver definido como true e a criptografia estiver ativada, o nível de criptografia especificado no servidor será usado mesmo que Encrypt esteja definido como false na cadeia de conexão.If TrustServerCertificate is set to true and encryption is turned on, the encryption level specified on the server will be used even if Encrypt is set to false in the connection string. A conexão falhará se isso for feito de outra maneira.The connection will fail otherwise.

Habilitando a criptografiaEnabling Encryption

Para habilitar a criptografia quando um certificado não foi provisionado no servidor, as opções forçar criptografia de protocolo e certificado de servidor confiável devem ser definidas em SQL Server Configuration Manager.To enable encryption when a certificate has not been provisioned on the server, the Force Protocol Encryption and the Trust Server Certificate options must be set in SQL Server Configuration Manager. Neste caso, a criptografia usará um certificado do servidor autoassinado sem validação, se nenhum certificado verificável tiver sido provisionado no servidor.In this case, encryption will use a self-signed server certificate without validation if no verifiable certificate has been provisioned on the server.

As configurações do aplicativo não podem reduzir o nível de segurança configurado no SQL Server, mas podem opcionalmente reforçá-lo.Application settings cannot reduce the level of security configured in SQL Server, but can optionally strengthen it. Um aplicativo pode solicitar criptografia definindo as TrustServerCertificate Encrypt palavras-chave e como true , garantindo que a criptografia ocorra mesmo quando um certificado de servidor não tiver sido provisionado e forçar a criptografia de protocolo não ter sido configurada para o cliente.An application can request encryption by setting the TrustServerCertificate and Encrypt keywords to true, guaranteeing that encryption takes place even when a server certificate has not been provisioned and Force Protocol Encryption has not been configured for the client. No entanto, se TrustServerCertificate não estiver ativado na configuração do cliente, um certificado do servidor provisionado ainda será necessário.However, if TrustServerCertificate is not enabled in the client configuration, a provisioned server certificate is still required.

A tabela a seguir descreve todos os casos.The following table describes all cases.

Configuração do cliente Forçar Criptografia de ProtocoloForce Protocol Encryption client setting Configuração do cliente Confiar em Certificado do ServidorTrust Server Certificate client setting Criptografar/Usar criptografia para a cadeia de conexão/atributo de dadosEncrypt/Use Encryption for Data connection string/attribute Cadeia de conexão/atributo do Certificado do Servidor de ConfiançaTrust Server Certificate connection string/attribute ResultResult
NãoNo N/DN/A Não (padrão)No (default) IgnoredIgnored Não ocorre criptografia.No encryption occurs.
NãoNo N/DN/A SimYes Não (padrão)No (default) A criptografia só ocorrerá se houver um certificado de servidor verificável; caso contrário, a tentativa de conexão falhará.Encryption occurs only if there is a verifiable server certificate, otherwise the connection attempt fails.
NãoNo N/DN/A SimYes SimYes A criptografia sempre ocorre, mas pode usar um certificado do servidor autoassinado.Encryption always occurs, but may use a self-signed server certificate.
SimYes NãoNo IgnoredIgnored IgnoredIgnored A criptografia ocorre somente se houver um certificado de servidor verificável; caso contrário, a tentativa de conexão falhará.Encryption occurs only if there is a verifiable server certificate; otherwise, the connection attempt fails.
SimYes SimYes Não (padrão)No (default) IgnoredIgnored A criptografia sempre ocorre, mas pode usar um certificado do servidor autoassinado.Encryption always occurs, but may use a self-signed server certificate.
SimYes SimYes SimYes Não (padrão)No (default) A criptografia ocorre somente se houver um certificado de servidor verificável; caso contrário, a tentativa de conexão falhará.Encryption occurs only if there is a verifiable server certificate; otherwise, the connection attempt fails.
SimYes SimYes SimYes SimYes A criptografia sempre ocorre, mas pode usar um certificado do servidor autoassinado.Encryption always occurs, but may use a self-signed server certificate.

Para obter mais informações, confira Usando criptografia sem validação.For more information, see Using Encryption Without Validation.

Cadeias de conexão do OleDbOleDb Connection Strings

A propriedade ConnectionString de um OleDbConnection permite que você obtenha ou defina uma cadeia de conexão para uma fonte de dados do OLE DB, como o Microsoft Access.The ConnectionString property of a OleDbConnection allows you to get or set a connection string for an OLE DB data source, such as Microsoft Access. Você também pode criar uma cadeia de conexão OleDb em tempo de execução usando a classe OleDbConnectionStringBuilder.You can also create an OleDb connection string at run time by using the OleDbConnectionStringBuilder class.

Sintaxe da cadeia de conexão OleDbOleDb Connection String Syntax

Você deve especificar um nome de provedor para uma cadeia de conexão OleDbConnection.You must specify a provider name for an OleDbConnection connection string. A seguinte cadeia de conexão conecta-se a um banco de dados do Microsoft Access usando o provedor Jet.The following connection string connects to a Microsoft Access database using the Jet provider. Observe que as palavras-chave User ID e Password serão opcionais se o banco de dados for inseguro (o padrão).Note that the User ID and Password keywords are optional if the database is unsecured (the default).

Provider=Microsoft.Jet.OLEDB.4.0; Data Source=d:\Northwind.mdb;User ID=Admin;Password=;

Se o banco de dados Jet estiver protegido usando a segurança de nível de usuário, você deverá fornecer o local do arquivo de informações do grupo de trabalho (.mdw).If the Jet database is secured using user-level security, you must provide the location of the workgroup information file (.mdw). O arquivo de informações do grupo de trabalho é usado para validar as credenciais apresentadas na cadeia de conexão.The workgroup information file is used to validate the credentials presented in the connection string.

Provider=Microsoft.Jet.OLEDB.4.0;Data Source=d:\Northwind.mdb;Jet OLEDB:System Database=d:\NorthwindSystem.mdw;User ID=*****;Password=*****;  

Importante

É possível fornecer informações de conexão para uma OleDbConnection em um arquivo de universal data link (udl); no entanto, você deve evitar fazer isso.It is possible to supply connection information for an OleDbConnection in a Universal Data Link (UDL) file; however you should avoid doing so. Os arquivos UDL não são criptografados e expõem as informações da cadeia de conexão em texto não criptografado.UDL files are not encrypted, and expose connection string information in clear text. Como um arquivo UDL é um recurso externo com base em arquivo para o seu aplicativo, ele não poderá ser protegido usando o .NET Framework.Because a UDL file is an external file-based resource to your application, it cannot be secured using the .NET Framework. Não há suporte para arquivos UDL para SqlClient.UDL files are not supported for SqlClient.

Usando DataDirectory para conectar-se ao Access/JetUsing DataDirectory to Connect to Access/Jet

DataDirectory não é exclusivo para SqlClient.DataDirectory is not exclusive to SqlClient. Ele também pode ser usado com os provedores de dados System.Data.OleDb e System.Data.Odbc do .NET.It can also be used with the System.Data.OleDb and System.Data.Odbc .NET data providers. A cadeia de caracteres de exemplo OleDbConnection a seguir demonstra a sintaxe necessária para se conectar ao Northwind.mdb localizado na pasta app_data do aplicativo.The following sample OleDbConnection string demonstrates the syntax required to connect to the Northwind.mdb located in the application's app_data folder. O banco de dados do sistema (System.mdw) também é armazenado nesse local.The system database (System.mdw) is also stored in that location.

"Provider=Microsoft.Jet.OLEDB.4.0;  
Data Source=|DataDirectory|\Northwind.mdb;  
Jet OLEDB:System Database=|DataDirectory|\System.mdw;"  

Importante

Especificar o local do banco de dados do sistema na cadeia de conexão não será necessário se o banco de dados Access/Jet for inseguro.Specifying the location of the system database in the connection string is not required if the Access/Jet database is unsecured. A segurança é desativada por padrão, com todos os usuários que se conectam como o usuário Admin interno com uma senha em branco.Security is off by default, with all users connecting as the built-in Admin user with a blank password. Mesmo quando a segurança em nível de usuário estiver implementada corretamente, um banco de dados Jet permanecerá vulnerável ao ataque.Even when user-level security is correctly implemented, a Jet database remains vulnerable to attack. Portanto, armazenar informações confidenciais em um banco de dados Access/Jet não é recomendado devido à fraqueza inerente de seu esquema de segurança baseado em arquivo.Therefore, storing sensitive information in an Access/Jet database is not recommended because of the inherent weakness of its file-based security scheme.

Conectando ao ExcelConnecting to Excel

O provedor Microsoft Jet é usado para conectar-se a uma pasta de trabalho do Excel.The Microsoft Jet provider is used to connect to an Excel workbook. Na cadeia de conexão a seguir, a palavra-chave de Extended Properties define as propriedades que são específicas do Excel.In the following connection string, the Extended Properties keyword sets properties that are specific to Excel. "HDR = Yes;" indica que a primeira linha contém nomes de coluna, não dados e "IMEX = 1;" instrui o driver a sempre ler colunas de dados "intermistas" como texto."HDR=Yes;" indicates that the first row contains column names, not data, and "IMEX=1;" tells the driver to always read "intermixed" data columns as text.

Provider=Microsoft.Jet.OLEDB.4.0;Data Source=D:\MyExcel.xls;Extended Properties=""Excel 8.0;HDR=Yes;IMEX=1""  

Observe que o caractere de aspas duplas necessário para as Extended Properties também deve estar entre aspas duplas.Note that the double quotation character required for the Extended Properties must also be enclosed in double quotation marks.

Sintaxe da cadeia de conexão do provedor de forma de dadosData Shape Provider Connection String Syntax

Use as palavras-chave Provider e Data Provider ao usar o provedor Microsoft Data Shape.Use both the Provider and the Data Provider keywords when using the Microsoft Data Shape provider. O exemplo a seguir usa o provedor Shape para se conectar a uma instância local do SQL Server.The following example uses the Shape provider to connect to a local instance of SQL Server.

"Provider=MSDataShape;Data Provider=SQLOLEDB;Data Source=(local);Initial Catalog=pubs;Integrated Security=SSPI;"

Cadeias de conexão do OdbcOdbc Connection Strings

A propriedade ConnectionString de um OdbcConnection permite obter ou definir uma cadeia de conexão para uma fonte de dados do OLE DB.The ConnectionString property of a OdbcConnection allows you to get or set a connection string for an OLE DB data source. As cadeias de conexão de Odbc também têm suporte pelo OdbcConnectionStringBuilder.Odbc connection strings are also supported by the OdbcConnectionStringBuilder.

A cadeia de conexão a seguir usa o Microsoft Text Driver.The following connection string uses the Microsoft Text Driver.

Driver={Microsoft Text Driver (*.txt; *.csv)};DBQ=d:\bin  

Usando DataDirectory para conectar-se ao Visual FoxProUsing DataDirectory to Connect to Visual FoxPro

O exemplo a seguir da cadeia de conexão OdbcConnection demonstra o uso do DataDirectory para se conectar a um arquivo do Microsoft Visual FoxPro.The following OdbcConnection connection string sample demonstrates using DataDirectory to connect to a Microsoft Visual FoxPro file.

"Driver={Microsoft Visual FoxPro Driver};  
SourceDB=|DataDirectory|\MyData.DBC;SourceType=DBC;"  

Cadeias de conexão do OracleOracle Connection Strings

A propriedade ConnectionString de um OracleConnection permite obter ou definir uma cadeia de conexão para uma fonte de dados do OLE DB.The ConnectionString property of a OracleConnection allows you to get or set a connection string for an OLE DB data source. As cadeias de conexão de Oracle também têm suporte pelo OracleConnectionStringBuilder.Oracle connection strings are also supported by the OracleConnectionStringBuilder .

Data Source=Oracle9i;User ID=*****;Password=*****;  

Para obter mais informações sobre a sintaxe da cadeia de conexão ODBC, consulte ConnectionString.For more information on ODBC connection string syntax, see ConnectionString.

Confira tambémSee also