Cadeias de conexão no ADO.NET Entity Framework

  • Artigo

Uma cadeia de conexão contém informações de inicialização que são passadas como parâmetros de um provedor de dados para uma fonte de dados. A sintaxe depende do provedor de dados, e a cadeia de conexão é analisada durante a tentativa de abrir uma conexão. As cadeias de conexão usadas por Entity Framework contêm informações usadas para conectar ao provedor de dados ADO.NET subjacente que dá suporte a Entity Framework. Elas também contêm informações sobre os arquivos de modelo e de mapeamento necessários.

A cadeia de conexão é usada pelo provedor EntityClient ao acessar metadados de modelo e de mapeamento e ao se conectar à fonte de dados. A cadeia de conexão pode ser acessada ou definida por meio da propriedade ConnectionString de EntityConnection. A classe EntityConnectionStringBuilder pode ser usada para construir ou acessar programaticamente parâmetros na cadeia de conexão.

As ferramentas do Modelo de Dados de Entidade geram uma cadeia de conexão que é armazenada no arquivo de configuração do aplicativo. O ObjectContext recupera essas informações de conexão automaticamente ao criar consultas de objeto. O EntityConnection usado por uma instância ObjectContext pode ser acessado a partir da propriedade Connection.

Sintaxe da cadeia de conexão

Para saber mais sobre a sintaxe geral para cadeias de conexão, consulte Sintaxe da cadeia de conexão | Cadeias de conexão no ADO.NET.

Parâmetros de cadeia de conexão

A tabela a seguir lista os nomes válidos para valores de palavra-chave na propriedade ConnectionString.

Palavra-chave Descrição
Provider Necessária quando a palavra-chave Name não é especificada. O nome do provedor, que é usado para recuperar o objeto DbProviderFactory do provedor subjacente. Esse valor é constante.

Quando a palavra-chave Name não é incluída em uma cadeia de conexão de entidade, um valor não vazio para a palavra-chave Provider é necessário. Essa palavra-chave é mutuamente excludente com a palavra-chave Name.
Provider Connection String Opcional. Especifica a cadeia de conexão específica ao provedor que é passada para a fonte de dados subjacente. Essa cadeia de conexão contém pares de palavra-chave/valor válidos para o provedor de dados. Uma palavra-chave Provider Connection String inválida produzirá um erro em tempo de execução ao ser avaliada pela fonte de dados.

Essa palavra-chave é mutuamente excludente com a palavra-chave Name.

Verifique o escape do valor de acordo com a sintaxe geral de Cadeias de conexão ADO.NET. Considere, por exemplo, a seguinte cadeia de conexão: Server=serverName; User ID = userID. Deve ser de escape porque contém um ponto e vírgula. Como não contém aspas duplas, podem ser usadas para o escape:

Provider Connection String ="Server=serverName; User ID = userID";
Metadata Necessária quando a palavra-chave Name não é especificada. Uma lista de diretórios, arquivos e locais de recursos delimitados por pipe na qual procurar informações de metadados e mapeamento. A seguir, é mostrado um exemplo:

Metadata=

c:\model | c:\model\sql\mapping.msl;

Os espaços em branco em cada lado do separador de pipe são ignorados.

Essa palavra-chave é mutuamente excludente com a palavra-chave Name.
Name O aplicativo pode, opcionalmente, especificar o nome da conexão em um arquivo de configuração do aplicativo que forneça os valores de cadeia de conexão de palavra-chave-valor necessários. Nesse caso, não é possível fornecê-los diretamente na cadeia de conexão. A palavra-chave Name não é permitida em um arquivo de configuração.

Quando a palavra-chave Name não é incluída na cadeia de conexão, um valor não vazio para a palavra-chave Provider é necessário.

Essa palavra-chave é mutuamente excludente com todos as outras palavras-chave de cadeia de conexão.

Locais de arquivos de modelo e de mapeamento

O parâmetro Metadata contém uma lista de locais para que o provedor EntityClient pesquise arquivos de modelo e de mapeamento. Os arquivos de modelo e de mapeamento geralmente são implantados no mesmo diretório que o arquivo executável do aplicativo. Esses arquivos também podem ser implantados em um local específico ou ser incluídos como um recurso inserido no aplicativo.

Os recursos inseridos são especificados como a seguir:

Metadata=res://<assemblyFullName>/<resourceName>

As seguintes opções estão disponíveis para definir o local de um recurso inserido:

Opção Descrição
assemblyFullName O nome completo de um assembly com o recurso inserido. O nome inclui o nome simples, o nome da versão, a cultura com suporte e a chave pública, como a seguir:

ResourceLib, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null

Os recursos podem ser inseridos em qualquer assembly que seja acessível pelo aplicativo.

Se você especificar um curinga (*) para assemblyFullName, o runtime do Entity Framework pesquisará os recursos nos seguintes locais, nesta ordem:

1. Assembly de chamada.
2. Assemblies referenciados.
3. Assemblies no diretório bin de um aplicativo.

Se os arquivos não estiverem em um desses locais, será gerada uma exceção. Observação: ao usar um caractere curinga (*), o Entity Framework pesquisará os recursos com o nome correto em todos os assemblies. Para melhorar o desempenho, especifique o nome do assembly, em vez do curinga.
resourceName O nome do recurso incluído, como AdventureWorksModel.csdl. Os serviços de metadados só procuram arquivos ou recursos com uma das seguintes extensões: .csdl, .ssdl ou .msl. Se a palavra-chave resourceName não for especificada, todos os recursos de metadados serão carregados. Os recursos devem ter nomes exclusivos em um assembly. Se vários arquivos com o mesmo nome forem definidos em diferentes diretórios no assembly, a palavra-chave resourceName deverá incluir a estrutura de pastas antes do nome do recurso, por exemplo, FolderName.FileName.csdl.

resourceName não é necessária quando você especifica um curinga (*) para assemblyFullName.

Observação

Para melhorar o desempenho, insira recursos no assembly de chamada, exceto em cenários não projetados para a Web, onde não há referências a arquivos subjacentes de mapeamento e de metadados no assembly de chamada.

O exemplo a seguir carrega todos os arquivos de modelo e de mapeamento no assembly de chamada, em assemblies referenciados e em outros assemblies no diretório bin de um aplicativo.

Metadata=res://*/

O exemplo a seguir carrega o arquivo model.csdl do assembly AdventureWorks e carrega os arquivos model.ssdl e model.msl do diretório padrão do aplicativo em execução.

Metadata=res://AdventureWorks, 1.0.0.0, neutral, a14f3033def15840/model.csdl|model.ssdl|model.msl

O exemplo a seguir carrega os três recursos especificados do assembly específico.

Metadata=res://AdventureWorks, 1.0.0.0, neutral, a14f3033def15840/model.csdl|
res://AdventureWorks, 1.0.0.0, neutral, a14f3033def15840/model.ssdl|
res://AdventureWorks, 1.0.0.0, neutral, a14f3033def15840/model.msl

O exemplo a seguir carrega todos os recursos inseridos com as extensões .csdl, .msl e .ssdl do assembly.

Metadata=res://AdventureWorks, 1.0.0.0, neutral, a14f3033def15840/

O exemplo a seguir carrega todos os recursos no caminho de arquivo relativo, além de "datadir\metadata\" do local do assembly carregado.

Metadata=datadir\metadata\

O exemplo a seguir carrega todos os recursos no caminho de arquivo relativo do local do assembly carregado.

Metadata=.\

Suporte para |DataDirectory| Cadeia de caracteres e substituição e operador raiz do aplicativo Web (~)

DataDirectory e o operador ~ são usados no ConnectionString como parte das palavras-chave Metadata e Provider Connection String. EntityConnection encaminha DataDirectory e o operador ~ para MetadataWorkspace e para o provedor de armazenamento, respectivamente.

Termo Descrição
&#124;DataDirectory&#124; Resolve como um caminho relativo a arquivos de mapeamento e metadados. Este é o valor que é definido por meio do método AppDomain.SetData("DataDirectory", objValue). A cadeia de caracteres de substituição DataDirectory deve estar entre os caracteres de pipe e sem espaços em branco entre o nome e os caracteres de pipe. O nome DataDirectory não diferencia maiúsculas de minúsculas.

Se um diretório físico chamado "DataDirectory" precisar ser passado como membro da lista de caminhos de metadados, adicione espaço em branco a um ou ambos os lados do nome. Por exemplo: Metadata="DataDirectory1 &#124; DataDirectory &#124; DataDirectory2". Um aplicativo ASP.NET resolve |DataDirectory| como a pasta "<raiz do aplicativo>/app_data".
~ Resolve como a raiz do aplicativo Web. O caractere ~ em uma posição à esquerda é sempre interpretado como o operador raiz do aplicativo Web (~), embora possa representar um subdiretório local válido. Para fazer referência a um subdiretório local, o usuário deve passar ./~ explicitamente.

DataDirectory e o operador ~ devem ser especificados somente no início de um caminho; eles não são resolvidos em nenhuma outra posição. O Entity Framework tentará resolver ~/data, mas tratará /data/~ como um caminho físico.

Um caminho que começa com DataDirectory ou com o operador ~ não pode ser resolvido como um caminho físico fora da ramificação de DataDirectory e do operador ~. Por exemplo, os seguintes caminhos serão resolvidos: ~, ~/data, ~/bin/Model/SqlServer. Os seguintes caminhos não serão resolvidos: ~/.., ~/../other.

DataDirectory e o operador ~ podem ser estendidos para incluir subdiretórios, conforme a seguir: |DataDirectory|\Model, ~/bin/Model

A resolução da cadeia de caracteres de substituição DataDirectory e do operador ~ é não recursiva. Por exemplo, quando DataDirectory incluir o caractere ~, será gerada uma exceção. Isso evita uma recursão infinita.

Confira também