Propriedade ConnectionString

Artigo
01/17/2011

Obtém ou define a cadeia de caracteres usada para abrir um banco de dados.

Namespace: System.Data.SqlServerCe
Assembly: System.Data.SqlServerCe (em System.Data.SqlServerCe.dll)

Sintaxe

'Declaração
Public Overrides Property ConnectionString As String
    Get
    Set
'Uso
Dim instance As SqlCeConnection
Dim value As String

value = instance.ConnectionString

instance.ConnectionString = value

public override string ConnectionString { get; set; }

public:
virtual property String^ ConnectionString {
    String^ get () override;
    void set (String^ value) override;
}

abstract ConnectionString : string with get, set
override ConnectionString : string with get, set

override function get ConnectionString () : String
override function set ConnectionString (value : String)

Valor da propriedade

Tipo: System. . :: . .String
A cadeia de caracteres de conexão do Provedor de Dados do .NET Compact Framework para SQL Server Compact 3.5 que inclui o nome da fonte de dados e outros parâmetros necessários para estabelecer a conexão inicial. O valor padrão é uma cadeia de caracteres vazia.

Implementa

IDbConnection. . :: . .ConnectionString

Exceções

Exceção	Condição
ArgumentException	Foi fornecido um argumento de cadeia de caracteres de conexão inválido.

Comentários

A propriedade ConnectionString pode ser definida somente quando a conexão é fechada. Muitos dos valores de cadeia de caracteres de conexão possuem propriedades somente leitura correspondentes. Ao definir a cadeia de caracteres de conexão, todas essas propriedades são atualizadas, exceto quando um erro é detectado. Nesse caso, nenhuma das propriedades é atualizada. As propriedades de SqlCeConnection retornam somente as configurações contidas na ConnectionString.

A redefinição de ConnectionString em uma conexão fechada redefine todos os valores de cadeia de caracteres de conexão e as propriedades relacionadas, inclusive a senha.

A tabela a seguir lista as propriedades de ConnectionString com suporte no SQL Server Compact 3.5.

Propriedade	Descrição
data source - ou - datasource	O caminho do arquivo e o nome do banco de dados do SQL Server Compact 3.5. Para indicar um caminho relativo do banco de dados a partir do diretório do aplicativo use a cadeia de caracteres de substituição Data Source = \|DataDirectory\| (entre símbolos de barra vertical). Use o método SetData()()()() no objeto AppDomain para definir o diretório de dados do aplicativo. Não há suporte para DataDirectory para dispositivos. Para obter mais informações, consulte Instalando e implantando em um desktop (SQL Server Compact)".
Password - ou - Pwd - ou - database password - ou - ssce:database password	A senha do banco de dados, que pode ter até 40 caracteres de comprimento. Se não for especificada, o valor padrão será sem senha. Esta propriedade será necessária se você habilitar a criptografia no banco de dados. Se você especificar uma senha, a criptografia será habilitada automaticamente no banco de dados. Se você especificar uma senha em branco, o banco de dados não será criptografado.
ssce:enlist ou enlist	Por padrão, o valor de enlist é false. Ele pode ser definido como true. Se uma conexão com o banco de dados do SQL Server Compact 3.5 for aberta usando Enlist definida como true, a conexão será promovida para uma transação.
ssce:encryption mode ou encryption mode	Os valores desta propriedade são engine default ou platform default ou ppc2003 compatibility O padrão é platform default. Observação Essa propriedade é uma opção no momento de criação do banco de dados e é ignorada durante a conexão com um banco de dados existente.
Encrypt - ou - encrypt database - ou - ssce:encrypt database	Um valor booleano que determina se o banco de dados é criptografado ou não. Deve ser definida como true para habilitar a criptografia ou false para desabilitá-la. Se não for especificada, o valor padrão será false. Se você habilitar a criptografia, especifique também uma senha com a propriedade password. Se você especificar uma senha, a criptografia será habilitada independentemente de como a propriedade for definida. Observação Essa propriedade é uma opção no momento de criação do banco de dados e é ignorada durante a conexão com um banco de dados existente. Se SSCE:Database Password for especificada, o banco de dados será criptografado independentemente de SSCE:Encrypt Database estar especificada ou não.
max buffer size - ou - ssce:max buffer size	A maior quantidade de memória, em quilobytes, que o SQL Server Compact 3.5 pode usar antes de começar a liberar alterações para o disco. Se não for especificada, o valor padrão será 640.
max database size - ou - ssce:max database size	O tamanho máximo do banco de dados, em megabytes. Se não for especificada, o valor padrão será 128.
Mode - ou - file mode - ou - ssce:mode	O modo a ser usado ao abrir o arquivo do banco de dados. Para obter os valores válidos, consulte a tabela a seguir. Se não for especificada, o valor padrão será 'Read Write'.
default lock timeout - ou - ssce:default lock timeout	O número padrão de milissegundos que uma transação aguardará por um bloqueio. Se não for especificada, o valor padrão será 2000.
default lock escalation - ou - ssce:default lock escalation	O número de bloqueios que uma transação adquirirá antes de tentar a escalação de linha para página ou de página para tabela. Se não for especificada, o valor padrão será 100.
flush interval - ou - ssce:flush interval	Especifica o intervalo (em segundos) antes que todas as transações confirmadas sejam liberadas para o disco. Se não for especificada, o valor padrão será 10.
autoshrink threshold - ou - ssce:autoshrink threshold	A porcentagem de espaço livre no arquivo do banco de dados que é permitida antes de iniciar a redução automática. O valor 100 desabilita a redução automática. Se não for especificada, o valor padrão será 60.
temp path - ou - temp file directory - ou - ssce:temp file directory	O local do banco de dados temporário. Se não for especificada, o padrão será usar o banco de dados especificado na propriedade data source para o armazenamento temporário.
temp file max size	O tamanho máximo do arquivo do banco de dados temporário, em megabytes. Se não for especificada, o valor padrão será 128.
persist security info	Quando definida como false (o que é altamente recomendável), informações confidenciais de segurança, como a senha, não serão retornadas como parte da conexão, se ela estiver aberta ou já tiver sido aberta. A redefinição da cadeia de caracteres de conexão redefine todos os valores de cadeia de caracteres de conexão, inclusive a senha. O valor padrão é false.
locale identifier - ou - Lcid-or-initial lcid	O identificação de localidade (LCID) a ser usada com o banco de dados. Os valores de LCID válidos estão listados na classe CultureInfo. Observação Essa propriedade é uma opção no momento de criação do banco de dados e é ignorada durante a conexão com um banco de dados existente.
Case Sensitive - ou - CaseSensitive	Um valor booleano que determina se o agrupamento de bancos de dados diferencia maiúsculas de minúsculas. Deve ser definida como true para habilitar o agrupamento com distinção de maiúsculas e minúsculas ou false para desabilitá-lo. Se não for especificada, o valor padrão será false. Se você se conectar a um banco de dados do SQL Server Compact existente com uma propriedade "Case Sensitive" na cadeia de conexão, o SQL Server Compact 3.5 SP1 irá ignorar essa configuração. Observação Essa propriedade é uma opção no momento de criação do banco de dados e é ignorada durante a conexão com um banco de dados existente.

A tabela a seguir mostra os valores válidos da propriedade mode da cadeia de caracteres.

Valor	Definição
Read Write	Permite que vários processos abram e modifiquem o banco de dados. Esta será a configuração padrão se a propriedade mode não for especificada.
Read Only	Permite abrir uma cópia somente leitura do banco de dados.
Exclusive	Não permite que outros processos abram ou modifiquem o banco de dados.
Shared Read	Permite que outros processos leiam, mas não modifiquem, o banco de dados enquanto ele está aberto.

Uma validação preliminar da cadeia de caracteres de conexão é executada ao definir a propriedade. Quando um aplicativo chama o método Open, a cadeia de caracteres de conexão é totalmente validada. Se a cadeia de caracteres de conexão contiver propriedades para as quais não há suporte ou que não são válidas, uma exceção de tempo limite, como ArgumentException, será gerada.

As seguintes regras se aplicam a cadeias de caracteres de conexão:

Todos os caracteres em branco, exceto aqueles colocados em um valor ou entre aspas, são ignorados.
Os pares de valores de palavras-chave devem ser separados por ponto-e-vírgula (;). Se um ponto-e-vírgula fizer parte de um valor, ele também deverá estar entre aspas.
Não há suporte para seqüências de escape.
O tipo de valor é irrelevante.
Os nomes não diferenciam maiúsculas de minúsculas.
Se o nome de uma propriedade ocorrer mais de uma vez na cadeia de caracteres de conexão, será usado o valor associado à última ocorrência.
Os valores podem ser delimitados por aspas simples ou duplas (por exemplo, name='valor' ou name="valor"). Aspas simples ou duplas podem ser usadas em uma cadeia de caracteres de conexão, usando o outro delimitador. Por exemplo, seguem os usos válidos das aspas em um cadeia de caracteres de conexão:
```
"data source='MyDb.sdf'; mode=Exclusive;"
'data source="MyDb.sdf"; mode=Exclusive;'
```
Mas estes exemplos não são válidos:
```
"data source="MyDb.sdf"; mode=Exclusive;"
'data source='MyDb.sdf'; mode=Exclusive;'
```

Exemplos

O exemplo a seguir cria uma SqlCeConnection e define algumas de suas propriedades na cadeia de caracteres de conexão.

Dim conn As New SqlCeConnection()

' Set some connection string properties e.g.:
' 
conn.ConnectionString = _
    "Persist Security Info = False; Data Source = 'SalesData.sdf';" & _
    "Password = '<password>'; File Mode = 'shared read'; " & _
    "Max Database Size = 256; Max Buffer Size = 1024"

conn.Open()

' You can change the database while preserving 
' the orignal connection options
'
conn.ChangeDatabase("SupportData.sdf")

SqlCeConnection conn = new SqlCeConnection();

// Set some connection string properties e.g.:
// 
conn.ConnectionString = 
    "Persist Security Info = False; Data Source = 'SalesData.sdf';" +
    "Password = '<password>'; File Mode = 'shared read'; " +
    "Max Database Size = 256; Max Buffer Size = 1024";

conn.Open();

// You can change the database while preserving 
// the orignal connection options
//
conn.ChangeDatabase("SupportData.sdf");