Chaînes de connexion (Entity Framework)

Article
08/23/2008

Une chaîne de connexion contient des informations d'initialisation qui sont passées en tant que paramètre d'un fournisseur de données à une source de données. La syntaxe dépend du fournisseur de données et la chaîne de connexion est analysée lors de la tentative d'ouverture d'une connexion. Les chaînes de connexion utilisées par Entity Framework contiennent des informations utilisées pour la connexion au fournisseur de données ADO.NET sous-jacent qui prend en charge Entity Framework. Elles contiennent également des informations sur le mappage et les métadonnées EDM (Entity Data Model) requis.

La chaîne de connexion est utilisée par le fournisseur EntityClient lors de l'accès au mappage et aux métadonnées EDM et de la connexion à la source de données. Il est possible d'accéder à cette chaîne ou de la définir via la propriété ConnectionString de EntityConnection. La classe EntityConnectionStringBuilder peut être utilisée pour construire par programme des paramètres dans la chaîne de connexion ou y accéder par programme. Pour plus d'informations, voir Procédure : générer une chaîne de connexion pour EntityConnection (Entity Framework).

Les outils Entity Data Model génèrent une chaîne de connexion qui est stockée dans le fichier de configuration de l'application. ObjectContext récupère automatiquement ces informations de connexion lors de la création de requêtes d'objet. Il est possible d'accéder au EntityConnection utilisé par une instance de ObjectContext à partir de la propriété Connection. Pour plus d'informations, voir Gestion des connexions dans Object Services (Entity Framework).

Paramètres de chaîne de connexion

Le format d'une chaîne de connexion est une liste délimitée par des points-virgules de paires de paramètres clé/valeur :

keyword1=value; keyword2=value;

Le signe égal (=) sert de lien entre chaque mot clé et sa valeur. Les mots clés ne respectent pas la casse et les espaces entre les paires clé/valeur sont ignorés. Toutefois, des valeurs peuvent respecter la casse, en fonction de la source de données. Toute valeur qui contient un point-virgule ou des guillemets simples ou des guillemets doubles doit être placée entre des guillemets doubles. Le tableau suivant répertorie les noms valides pour les valeurs de mots clés dans la propriété ConnectionString.

Mot clé	Description
Provider	Obligatoire si le mot clé Name n'est pas spécifié. Nom du fournisseur, utilisé pour récupérer l'objet DbProviderFactory du fournisseur sous-jacent. Cette valeur est constante. Lorsque le mot clé Name n'est pas inclus dans une chaîne de connexion de l'entité, une valeur non vide pour le mot clé Provider est requise. Ce mot clé et le mot clé Name s'excluent mutuellement.
Provider Connection String	Facultatif. Spécifie la chaîne de connexion spécifique au fournisseur passée à la source de données sous-jacente. Cette chaîne de connexion est exprimée à l'aide de paires mot clé/valeur valides pour le fournisseur de données. Un mot clé Provider Connection String non valide provoque une erreur d'exécution lors de son évaluation par la source de données. Ce mot clé et le mot clé Name s'excluent mutuellement. La valeur du mot clé Provider Connection String doit être placée entre guillemets. Voici un exemple : `Provider Connection String ="Server=serverName; User ID = userID";` L'exemple suivant est incorrect : `Provider Connection String =Server=serverName; User ID = userID`
Metadata	Obligatoire si le mot clé Name n'est pas spécifié. Liste de répertoires, de fichiers et d'emplacements de ressources délimitée par des barres verticales (\|) dans laquelle rechercher les informations de métadonnées et de mappage. Voici un exemple : `Metadata=` `c:\model \| c:\model\sql\mapping.msl;` Les espaces situés de part et d'autre de la barre verticale sont ignorés. Ce mot clé et le mot clé Name s'excluent mutuellement.
Name	L'application peut éventuellement spécifier le nom de la connexion dans un fichier de configuration d'application qui fournit les valeurs de chaîne de connexion mot clé/valeur requises. Dans ce cas, vous ne pouvez pas les fournir directement dans la chaîne de connexion. Le mot clé Name n'est pas autorisé dans un fichier de configuration. Lorsque le mot clé Name n'est pas inclus dans la chaîne de connexion, des valeurs non vides pour le mot clé Provider sont requises. Ce mot clé est incompatible avec tous les autres mots clés de chaîne de connexion, et inversement.

Voici un exemple de chaîne de connexion pour le modèle de vente AdventureWorks Sales Model stocké dans le fichier de configuration de l'application :

<connectionStrings>
    <add name="AdventureWorksEntities" 
         connectionString="metadata=.\AdventureWorks.csdl|.\AdventureWorks.ssdl|.\AdventureWorks.msl;
         provider=System.Data.SqlClient;provider connection string='Data Source=localhost;
         Initial Catalog=AdventureWorks;Integrated Security=True;Connection Timeout=60;
         multipleactiveresultsets=true'" providerName="System.Data.EntityClient" />
    <add name="NorthwindEntities" connectionString="metadata=.\Northwind.csdl|.\Northwind.ssdl.\Northwind.msl;
         provider=System.Data.SqlClient;provider connection string='Data Source=localhost;
         Initial Catalog=Northwind;Integrated Security=True;MultipleActiveResultSets=True'" 
         providerName="System.Data.EntityClient" />
</connectionStrings>

Emplacement du mappage et des métadonnées EDM

Le paramètre Metadata contient une liste d'emplacements pour le fournisseur EntityClient dans lesquels rechercher des fichiers de métadonnées et de mappage EDM. Les fichiers de métadonnées et de mappage sont souvent déployés dans le même répertoire que le fichier exécutable de l'application. Ces fichiers peuvent être déployés également dans un emplacement spécifique ou inclus en tant que ressource incorporée dans l'application.

Les ressources incorporées sont spécifiées comme suit :

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

Les options suivantes permettent de définir l'emplacement d'une ressource incorporée :

Option

Description

assemblyFullName

Nom complet d'un assembly avec la ressource incorporée. Ce nom inclut le nom simple, le nom de la version, la culture prise en charge et la clé publique, comme suit :

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

Il est possible d'incorporer des ressources dans n'importe quel assembly accessible par l'application.

Si vous spécifiez un caractère générique (*) pour assemblyFullName, le runtime Entity Framework recherche des ressources dans les emplacements suivants, dans cet ordre :

L'assembly appelant.
Les assemblys référencés.
Les assemblys situés dans le répertoire bin d'une application.

Si les fichiers ne se trouvent pas dans l'un de ces emplacements, une exception est levée.

Remarque
Lorsque vous utilisez un caractère générique (*), Entity Framework doit rechercher les ressources portant le nom correct dans tous les assemblys. Pour améliorer les performances, spécifiez le nom de l'assembly plutôt que le caractère générique.

resourceName

Nom de la ressource incluse, par exemple AdvendtureWorksModel.csdl. Les services de métadonnées recherchent uniquement les fichiers ou les ressources ayant l'une des extensions suivantes : csdl, .ssdl ou .msl. Si resourceName n'est pas spécifié, toutes les ressources EDM sont chargées. Les ressources doivent avoir des noms uniques dans un assembly. Si plusieurs fichiers portant le même nom sont définis dans différents répertoires de l'assembly, l'option resourceName doit inclure la structure de dossiers avant le nom de la ressource, par exemple NomDossier.NomFichier.csdl.

resourceName n'est pas requis lorsque vous spécifiez un caractère générique (*) pour assemblyFullName.

Remarque
Pour améliorer les performances, incorporez les ressources dans l'assembly appelant, excepté dans les scénarios non Web dans lesquels il n'y a aucune référence aux fichiers de mappage et de métadonnées sous-jacents dans l'assembly appelant.

L'exemple suivant charge tous les artefacts des métadonnées EDM dans l'assembly appelant, dans les assemblys référencés et dans d'autres assemblys situés dans le répertoire bin d'une application.

Metadata=res://*/

L'exemple suivant charge le fichier model.csdl à partir de l'assembly AdventureWorks, et charge les fichiers model.ssdl et model.msl à partir du répertoire par défaut de l'application en cours d'exécution.

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

L'exemple suivant charge les trois ressources spécifiées à partir de l'assembly spécifique.

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

L'exemple suivant charge toutes les ressources incorporées ayant les extensions .csdl, .msl et .ssdl à partir de l'assembly.

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

L'exemple suivant charge toutes les ressources se trouvant dans le chemin d'accès relatif plus « datadir\metadata\ » à partir de l'emplacement de l'assembly chargé.

Metadata=datadir\metadata\

L'exemple suivant charge toutes les ressources se trouvant dans le chemin d'accès relatif à partir de l'emplacement de l'assembly chargé.

Metadata=.\

Prise en charge de la chaîne de substitution |DataDirectory| et de l'opérateur de racine de l'application Web (~)

DataDirectory et l'opérateur ~ sont utilisés dans la propriété ConnectionStringen tant que partie des mots clés Metadata et Provider Connection String. L'objet EntityConnection transfère le DataDirectory et l'opérateur ~ à l'objet MetadataWorkspace et au fournisseur de magasins, respectivement.

Terme Description

Terme	Description
\|DataDirectory\|	Correspond à un chemin d'accès relatif d'un mappage et de fichiers de métadonnées. Il s'agit de la valeur définie via la méthode `AppDomain.SetData("DataDirectory", objValue)`. La chaîne de substitution DataDirectory doit être placée entre des barres verticales et il ne doit y avoir aucun espace entre son nom et les barres verticales. Le nom DataDirectory ne respecte pas la casse. Si un répertoire physique nommé « DataDirectory » doit être passé comme membre de la liste des chemins d'accès aux métadonnées, ajoutez un espace soit avant ou après le nom, soit de chaque côté, par exemple : `Metadata="DataDirectory1 \| DataDirectory \| DataDirectory2"`. Une application ASP.NET fait correspondre \|DataDirectory\| au dossier « <racine de l'application>/app_data ».
~	Correspond à la racine de l'application Web. Le caractère ~ placé en première position est toujours interprété comme l'opérateur de racine de l'application Web (~), même s'il peut représenter un sous-répertoire local valide. Pour faire référence à un tel sous-répertoire local, l'utilisateur doit passer explicitement `./~`.

|DataDirectory|

Correspond à un chemin d'accès relatif d'un mappage et de fichiers de métadonnées. Il s'agit de la valeur définie via la méthode AppDomain.SetData("DataDirectory", objValue). La chaîne de substitution DataDirectory doit être placée entre des barres verticales et il ne doit y avoir aucun espace entre son nom et les barres verticales. Le nom DataDirectory ne respecte pas la casse.

Si un répertoire physique nommé « DataDirectory » doit être passé comme membre de la liste des chemins d'accès aux métadonnées, ajoutez un espace soit avant ou après le nom, soit de chaque côté, par exemple : Metadata="DataDirectory1 | DataDirectory | DataDirectory2". Une application ASP.NET fait correspondre |DataDirectory| au dossier « <racine de l'application>/app_data ».

Correspond à la racine de l'application Web. Le caractère ~ placé en première position est toujours interprété comme l'opérateur de racine de l'application Web (~), même s'il peut représenter un sous-répertoire local valide. Pour faire référence à un tel sous-répertoire local, l'utilisateur doit passer explicitement ./~.

DataDirectory et l'opérateur ~ doivent être spécifiés uniquement au début d'un chemin d'accès ; ils ne sont pas résolus s'ils se trouvent à toute autre position. Entity Framework essaiera de résoudre ~/data, mais il traitera /data/~ comme un chemin d'accès physique.

Un chemin d'accès qui commence par le DataDirectory ou par l'opérateur ~ ne peut pas correspondre à un chemin d'accès physique à l'extérieur de la branche du DataDirectory et de l'opérateur ~. Par exemple, les chemins d'accès suivants seront résolus : ~ , ~/data , ~/bin/Model/SqlServer. Les chemins d'accès suivants ne seront pas résolus : ~/.., ~/../other.

DataDirectory et l'opérateur ~ peuvent être étendus pour inclure des sous-répertoires, comme suit : |DataDirectory|\Model, ~/bin/Model

La résolution de la chaîne de substitution DataDirectory et de l'opérateur ~ est non récursive. Par exemple, lorsque DataDirectory inclut le caractère ~, une exception se produit. Cela empêche une récurrence infinie.

Voir aussi

Concepts

Points à prendre en considération pour le déploiement (Entity Framework)
Gestion des connexions dans Object Services (Entity Framework)

Autres ressources

Services d'entités et fournisseurs de données (Entity Framework)
Gestion des connexions et des transactions (Tâches Entity Framework)
Chaînes de connexion (ADO.NET)

Partager via