OleDbConnection.ConnectionString Propriedade

Definição

Obtém ou define a cadeia de caracteres usada para abrir um banco de dados.Gets or sets the string used to open a database.

public:
 property System::String ^ ConnectionString { System::String ^ get(); void set(System::String ^ value); };
[System.ComponentModel.SettingsBindable(true)]
[System.Data.DataSysDescription("OleDbConnection_ConnectionString")]
public string ConnectionString { get; set; }
member this.ConnectionString : string with get, set
Public Property ConnectionString As String

Valor da propriedade

A cadeia de conexão do provedor OLE DB que inclui o nome da fonte de dados e outros parâmetros necessários para estabelecer a conexão inicial.The OLE DB provider connection string that includes the data source name, and other parameters needed to establish the initial connection. O valor padrão é uma cadeia de caracteres vazia.The default value is an empty string.

Implementações

Atributos

Exceções

Um argumento de cadeia de conexão inválido foi fornecido ou não foi fornecido um argumento de cadeia de conexão necessário.An invalid connection string argument has been supplied or a required connection string argument has not been supplied.

Exemplos

O exemplo a seguir cria um OleDbConnection e define algumas de suas propriedades na cadeia de conexão.The following example creates an OleDbConnection and sets some of its properties in the connection string.

static void OpenConnection(string connectionString)
{
    using (OleDbConnection connection = new OleDbConnection(connectionString))
    {
        try
        {
            connection.Open();
            Console.WriteLine("ServerVersion: {0} \nDataSource: {1}",
                connection.ServerVersion, connection.DataSource);
        }
        catch (Exception ex)
        {
            Console.WriteLine(ex.Message);
        }
        // The connection is automatically closed when the
        // code exits the using block.
    }
}
Public Sub OpenConnection(ByVal connectionString As String)

    Using connection As New OleDbConnection(connectionString)
        Try
            connection.Open()
            Console.WriteLine("Server Version: {0} DataSource: {1}", _
                connection.ServerVersion, connection.DataSource)
        Catch ex As Exception
            Console.WriteLine(ex.Message)
        End Try
        ' The connection is automatically closed when the
        ' code exits the Using block.
    End Using
End Sub

Comentários

O ConnectionString é projetado para corresponder OLE DB formato de cadeia de conexão o mais próximo possível com as seguintes exceções:The ConnectionString is designed to match OLE DB connection string format as closely as possible with the following exceptions:

  • A cláusula "Provider = value" é necessária.The "Provider = value " clause is required. No entanto, não é possível usar "Provider = MSDASQL" porque o Provedor de Dados de .NET Framework para OLE DB não oferece suporte ao provedor de OLE DB para ODBC (MSDASQL).However, you cannot use "Provider = MSDASQL" because the .NET Framework Data Provider for OLE DB does not support the OLE DB Provider for ODBC (MSDASQL). Para acessar fontes de dados ODBC, use o OdbcConnection objeto que está no namespace System.Data.Odbc.To access ODBC data sources, use the OdbcConnection object that is in the System.Data.Odbc namespace.

  • Ao contrário de ODBC ou ADO, a cadeia de conexão retornada é igual ao conjunto de usuários ConnectionString, menos informações de segurança se Persist Security Info for definido como false (padrão).Unlike ODBC or ADO, the connection string that is returned is the same as the user-set ConnectionString, minus security information if Persist Security Info is set to false (default). O Provedor de Dados .NET Framework para OLE DB não mantém ou retorna a senha em uma cadeia de conexão, a menos que você defina a palavra-chave Persist Security Info como true (não recomendado).The .NET Framework Data Provider for OLE DB does not persist or return the password in a connection string unless you set the Persist Security Info keyword to true (not recommended). Para manter um alto nível de segurança, é altamente recomendável que você use a palavra-chave Integrated Security com Persist Security Info definido como false.To maintain a high level of security, it is strongly recommended that you use the Integrated Security keyword with Persist Security Info set to false.

Você pode usar a propriedade ConnectionString para se conectar a uma variedade de fontes de dados.You can use the ConnectionString property to connect to a variety of data sources. O exemplo a seguir ilustra várias cadeias de conexão possíveis.The following example illustrates several possible connection strings.

"Provider=MSDAORA; Data Source=ORACLE8i7;Persist Security Info=False;Integrated Security=Yes"  
  
"Provider=Microsoft.Jet.OLEDB.4.0; Data Source=c:\bin\LocalAccess40.mdb"  
  
"Provider=SQLOLEDB;Data Source=(local);Integrated Security=SSPI"  

Se a palavra-chave Data Source não for especificada na cadeia de conexão, o provedor tentará se conectar ao servidor local, se houver uma disponível.If the Data Source keyword is not specified in the connection string, the provider will try to connect to the local server if one is available.

Para obter mais informações sobre cadeias de conexão, consulte usando palavras-chave da cadeia de conexão com SQL Server Native Client.For more information about connection strings, see Using Connection String Keywords with SQL Server Native Client.

A propriedade ConnectionString pode ser definida somente quando a conexão é fechada.The ConnectionString property can be set only when the connection is closed. Muitos dos valores de cadeia de conexão têm propriedades somente leitura correspondentes.Many of the connection string values have corresponding read-only properties. Quando a cadeia de conexão é definida, essas propriedades são atualizadas, exceto quando um erro é detectado.When the connection string is set, these properties are updated, except when an error is detected. Nesse caso, nenhuma das propriedades é atualizada.In this case, none of the properties are updated. OleDbConnection Propriedades retornam apenas as configurações contidas no ConnectionString.OleDbConnection properties return only those settings that are contained in the ConnectionString.

Redefinir o ConnectionString em uma conexão fechada redefine todos os valores de cadeia de conexão e propriedades relacionadas.Resetting the ConnectionString on a closed connection resets all connection string values and related properties. Isso inclui a senha.This includes the password. Por exemplo, se você definir uma cadeia de conexão que inclui "Initial Catalog = AdventureWorks" e, em seguida, redefinir a cadeia de conexão para "Provider = SQLOLEDB; Data Source = MySqlServer; IntegratedSecurity = SSPI", a propriedade Database não será mais definida como AdventureWorks.For example, if you set a connection string that includes "Initial Catalog= AdventureWorks", and then reset the connection string to "Provider= SQLOLEDB;Data Source= MySQLServer;IntegratedSecurity=SSPI", the Database property is no longer set to AdventureWorks. (O valor inicial do catálogo da cadeia de conexão corresponde à propriedade Database.)(The Initial Catalog value of the connection string corresponds to the Database property.)

Uma validação preliminar da cadeia de conexão é executada quando a propriedade é definida.A preliminary validation of the connection string is performed when the property is set. Se os valores para o Provider, Connect Timeout, Persist Security Infoou OLE DB Services forem incluídos na cadeia de caracteres, esses valores serão verificados.If values for the Provider, Connect Timeout, Persist Security Info, or OLE DB Services are included in the string, these values are checked. Quando um aplicativo chama o método Open, a cadeia de conexão é totalmente validada.When an application calls the Open method, the connection string is fully validated. Se a cadeia de conexão contiver propriedades inválidas ou sem suporte, uma exceção de tempo de execução, como ArgumentException, será gerada.If the connection string contains invalid or unsupported properties, a run-time exception, such as ArgumentException, is generated.

Cuidado

É possível fornecer informações de conexão para um 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 informações de 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.

O formato básico de uma cadeia de conexão inclui uma série de pares de palavras-chave/valor separados por ponto e vírgula.The basic format of a connection string includes a series of keyword/value pairs separated by semicolons. O sinal de igual (=) conecta cada palavra-chave e seu valor.The equal sign (=) connects each keyword and its value. Para incluir valores que contenham um ponto-e-vírgula, caractere de aspa simples ou caractere de aspas duplas, o valor deve ser colocado entre aspas duplas.To include values that contain a semicolon, single-quote character, or double-quote character, the value must be enclosed in double quotation marks. Se o valor contiver um ponto e vírgula e um caractere de aspas duplas, o valor poderá ser colocado entre aspas simples.If the value contains both a semicolon and a double-quote character, the value can be enclosed in single quotation marks. A aspa simples também será útil se o valor começar com um caractere de aspas duplas.The single quotation mark is also useful if the value starts with a double-quote character. Por outro lado, as aspas duplas podem ser usadas se o valor começar com uma aspa simples.Conversely, the double quotation mark can be used if the value starts with a single quotation mark. Se o valor contiver caracteres de aspas simples e aspas duplas, o caractere de aspas usado para colocar o valor deverá ser dobrado sempre que ocorrer dentro do valor.If the value contains both single-quote and double-quote characters, the quotation-mark character used to enclose the value must be doubled every time it occurs within the value.

Para incluir espaços anteriores ou posteriores no valor da cadeia de caracteres, o valor deve ser colocado entre aspas simples ou aspas duplas.To include preceding or trailing spaces in the string value, the value must be enclosed in either single quotation marks or double quotation marks. Quaisquer espaços à esquerda ou à direita em relação a valores inteiros, boolianos ou enumerados são ignorados, mesmo se colocados entre aspas.Any leading or trailing spaces around integer, Boolean, or enumerated values are ignored, even if enclosed in quotation marks. No entanto, espaços em uma palavra-chave literal de cadeia de caracteres ou valor são preservados.However, spaces within a string literal keyword or value are preserved. Aspas simples ou duplas podem ser usadas em uma cadeia de conexão sem usar delimitadores (por exemplo, Data Source= my'Server ou Data Source= my"Server), a menos que um caractere de aspas seja o primeiro ou o último caractere no valor.Single or double quotation marks may be used within a connection string without using delimiters (for example, Data Source= my'Server or Data Source= my"Server) unless a quotation-mark character is the first or last character in the value.

Para incluir um sinal de igual (=) em uma palavra-chave ou valor, ele deve ser precedido por outro sinal de igual.To include an equal sign (=) in a keyword or value, it must be preceded by another equal sign. Por exemplo, na cadeia de conexão hipotéticaFor example, in the hypothetical connection string

"key==word=value"  

a palavra-chave é "Key = Word" e o valor é "value".the keyword is "key=word" and the value is "value".

Se uma palavra-chave específica em um par de palavras-chave = valor ocorrer várias vezes em uma cadeia de conexão, a última ocorrência listada será usada no conjunto de valores.If a specific keyword in a keyword=value pair occurs multiple times in a connection string, the last occurrence listed is used in the value set.

As palavras-chave não diferenciam maiúsculas de minúsculas.Keywords are not case sensitive.

Cuidado

Você deve ter cuidado ao construir uma cadeia de conexão com base na entrada do usuário, por exemplo, ao recuperar informações de ID de usuário e senha de uma caixa de diálogo e acrescentá-las à cadeia de conexão.You should use caution when constructing a connection string based on user input, for example, when retrieving user ID and password information from a dialog box and appending it to the connection string. O aplicativo deve garantir que um usuário não possa inserir parâmetros de cadeia de conexão adicionais nesses valores, por exemplo, inserindo uma senha como "validpassword; Database = somedb" em uma tentativa de anexar a um banco de dados diferente.The application should make sure that a user cannot embed additional connection-string parameters in these values, for example, entering a password as "validpassword;database= somedb" in an attempt to attach to a different database. Se você usar o parâmetro de cadeia de conexão propriedades estendidas para OLE DB conexões, Evite passar IDs e senhas de usuário, pois você deve evitar armazenar IDs de usuário e senhas em texto não criptografado, se puder, e porque a configuração padrão de Persist Security Info= false não afeta o parâmetro Extended Properties.If you use the Extended Properties connection string parameter for OLE DB connections, avoid passing user IDs and passwords because you should avoid storing user IDs and passwords in clear text if you can, and because the default setting of Persist Security Info= false does not affect the Extended Properties parameter.

Aplica-se a

Veja também