Création d'assemblys satellites

Article
08/21/2008

Mise à jour : novembre 2007

Le modèle "hub and spoke" décrit dans la rubrique Empaquetage et déploiement de ressources est l'implémentation de design recommandée pour le développement d'applications avec des ressources.

Le modèle "hub and spoke" requiert que vous placiez les ressources dans des emplacements spécifiques, afin qu'elles soient facilement trouvées et utilisées. Si vous ne compilez pas et ne nommez pas les ressources comme prévu ou si vous ne les placez pas aux endroits corrects, le Common Language Runtime ne sera pas en mesure de les trouver. C'est pourquoi, il utilisera l'ensemble de ressources par défaut. Pour plus d'informations sur les noms de ressources, consultez CultureInfo, classe ou Empaquetage et déploiement de ressources.

Compilation d'assemblys satellites

Utilisez l'utilitaire Assembly Linker (Al.exe) pour compiler les fichiers .resources en assemblys satellites. Al.exe crée un assembly à partir des fichiers .resources que vous spécifiez. Par définition, les assemblys satellites ne contiennent que des ressources. Ils ne peuvent pas contenir du code exécutable.

La commande suivante de Al.exe crée un assembly satellite pour l'application MyApp à partir du fichier strings.de.resources.

al /t:lib /embed:strings.de.resources /culture:de /out:MyApp.resources.dll

La commande suivante de Al.exe crée également un assembly satellite pour l'application MyApp à partir du fichier strings.de.resources. L'option /template fait en sorte que l'assembly satellite hérite des métadonnées d'assembly de l'assembly parent MyApp.dll.

al /t:lib /embed:strings.de.resources /culture:de /out:MyApp.resources.dll
/template:MyApp.dll

Le tableau suivant explique en détail les options de Al.exe utilisées dans ces exemples.

Option	Description
/t:lib	L'option /t spécifie que votre assembly satellite est compilé dans un fichier .dll. Un assembly satellite ne peut pas être exécuté, car il ne contient pas de code et n'est pas un assembly principal de l'application. C'est pourquoi, vous devez enregistrer les assemblys satellites en tant que DLL.
/embed:strings.de.resources	L'option /embed spécifie le nom du fichier source à utiliser lorsque Al.exe compile l'assembly. Vous pouvez incorporer plusieurs fichiers .resources dans un assembly satellite. Cependant, si vous suivez le modèle "hub and spoke", vous devez compiler un assembly satellite pour chaque culture. Vous pouvez, cependant, créer des fichiers .resources séparés pour des chaînes et des objets.
/culture:de	L'option /culture spécifie la culture de la ressource à compiler. Le runtime utilise ces informations lorsqu'il recherche les ressources pour une culture spécifique. Si vous omettez cette option, Al.exe compile quand même la ressource, mais le runtime n'est pas en mesure de la trouver lorsqu'un utilisateur la demande.
/out:MyApp.resources.dll	L'option /out spécifie le nom du fichier de sortie. Ce nom doit suivre les conventions d'appellation standard nomdebase.resources.extension, où nomdebase est le nom de l'assembly principal, et extension est une extension valide (telle que .dll). Le runtime n'est pas en mesure de déterminer la culture d'un assembly satellite en fonction du nom de son fichier de sortie. C'est pourquoi, il est important de spécifier une culture avec l'option /culture décrite ci-dessus.
/template:nom_fichier	L'option /template spécifie un assembly à partir duquel hériter toutes les métadonnées de l'assembly, à l'exception du champ culture. L'assembly dont hérite l'assembly satellite doit avoir un nom fort.

Pour obtenir une liste complète des options disponibles avec Al.exe, consultez Assembly Linker (Al.exe).

Compilation d'assemblys satellites avec des noms forts

Si vous souhaitez installer des assemblys satellites dans le Global Assembly Cache, ils doivent avoir des noms forts. Les assemblys avec nom fort sont signés avec une paire de clés publique/privée valide. Pour plus d'informations sur les noms forts, consultez Assemblys avec nom fort.

Lorsque vous développez une application, il est peu probable que vous puissiez accéder à la paire de clés publique/privée finale. Afin d'installer un assembly satellite dans le Global Assembly Cache et de vous assurer qu'il fonctionne comme prévu, vous pouvez utiliser une technique appelée signature différée. Lorsque vous différez la signature d'un assembly, vous réservez un espace dans le fichier pour la signature de nom fort au moment de la compilation. La signature réelle est différée jusqu'à une date ultérieure lorsque la paire de clés publique/privée finale est disponible.

Obtention de la clé publique

Pour différer la signature d'un assembly, vous devez avoir accès à la clé publique. Vous pouvez soit obtenir la clé publique réelle à partir de l'organisation dans votre société qui effectuera la signature, soit créer une clé publique en utilisant l'outil Strong Name Tool (Sn.exe).

La commande Sn.exe suivante crée une paire de clés publique/privée de test et l'enregistre dans le fichier TestKeyPair.snk. L'option –k spécifie à Sn.exe de créer une nouvelle paire de clés et de l'enregistrer dans le fichier spécifié.

sn –k TestKeyPair.snk

Vous pouvez extraire la clé publique du fichier contenant la paire de clés de test. La commande suivante extrait la clé publique de TestKeyPair.snk et la stocke dans PublicKey.snk.

sn –p TestKeyPair.snk PublicKey.snk

Signature différée d'un assembly

Une fois que vous avez obtenu ou créé la clé publique, servez-vous de l'utilitaire Assembly Linker (Al.exe) pour compiler l'assembly et spécifier la signature différée.

La commande suivante de Al.exe crée un assembly satellite avec nom fort pour l'application MyApp à partir du fichier strings.ja.resources.

al /t:lib /embed:strings.ja.resources /culture:ja /out:MyApp.resources.dll /delay+ /keyfile:PublicKey.snk

L'option /delay+ indique la signature différée de l'assembly. L'option /keyfile: spécifie le nom du fichier de clé contenant la clé publique à utiliser pour différer la signature de l'assembly.

Pour plus d'informations sur la signature différée, consultez Signature différée d'un assembly.

Les assemblys avec nom fort contiennent des informations de version que le runtime utilise pour déterminer l'assembly à utiliser afin de répondre à la demande de liaison. Pour plus d'informations sur cette rubrique, consultez Versioning des assemblys.

Nouvelle signature d'un assembly

Ultérieurement, un assembly satellite dont la signature a été différée doit être signé de nouveau avec la paire de clés réelle. Vous pouvez effectuer cette action à l'aide de Sn.exe.

La commande Sn.exe suivante signe MyApp.resources.dll avec la vraie paire de clés stockée dans le fichier RealKeyPair.snk. L'option –R spécifie à Sn.exe de signer à nouveau un assembly déjà signé ou dont la signature a été différée.

sn –R MyApp.resources.dll RealKeyPair.snk

Installation d'un assembly satellite dans le Global Assembly Cache

Le Global Assembly Cache est le premier emplacement dans lequel le runtime recherche les ressources dans le processus de secours pour les ressources. Pour plus d'informations, consultez la sous-rubrique « Processus de secours pour les ressources » de la rubrique Empaquetage et déploiement de ressources. Par conséquent, il est important de savoir comment installer des ressources dans le Global Assembly Cache. Un assembly satellite que vous avez compilé avec un nom fort est prêt à l'installation dans le Global Assembly Cache. L'installation des assemblys dans le cache peut se faire à l'aide de l'outil Global Assembly Cache Tool (Gacutil.exe).

La commande Gacutil.exe suivante installe MyApp.resources.dll dans le Global Assembly Cache.

gacutil /i:MyApp.resources.dll

L'option /i spécifie à Gacutil.exe d'installer l'assembly spécifié dans le Global Assembly Cache. À la suite de cette commande, une entrée est placée dans le cache, ce qui permet l'accès aux entrées contenues dans ce fichier .resources. Après avoir été installé dans le cache, la ressource spécifiée est disponible à toutes les applications qui sont conçues pour l'utiliser.

Emplacement des répertoires d'assemblys satellites non installés dans le Global Assembly Cache

Après avoir compilé vos assemblys satellites, ils ont tous le même nom. Le runtime les différencie en fonction de la culture spécifiée au moment de la compilation à l'aide de l'option /culture de Al.exe et en fonction de l'emplacement du répertoire de chaque assembly. Vous devez placer vos assemblys satellites aux emplacements attendus.

L'illustration suivante propose un exemple de structure de répertoires et de la configuration requise pour les emplacements des applications que vous n'installez pas dans le Global Assembly Cache. Les éléments avec les extensions de fichier .txt et .resources ne seront pas fournis avec l'application finale. Il s'agit des fichiers de ressources intermédiaires utilisés pour créer des assemblys de ressources satellites finaux. Dans cet exemple, vous pouvez remplacer les fichiers .resx par des fichiers .txt. Les fichiers .resx sont les seuls types de fichiers de ressources intermédiaires qui peuvent contenir des objets.

Répertoire de l'assembly satellite

Assemblys satellites

Remarque :
Si votre application comprend des ressources pour les sous-cultures, placez chaque sous-culture dans son propre répertoire. Ne placez pas les sous-cultures dans des sous-répertoires du répertoire de la culture principale.