ASP.NET Merge Tool, outil (Aspnet_merge.exe)

Mise à jour : novembre 2007

L'outil ASP.NET Merge Tool (Aspnet_merge.exe) vous permet d'associer et de gérer des assemblys créés par l'outil ASP.NET Compilation Tool (Aspnet_compiler.exe). L'outil ASP.NET Merge Tool fonctionne sur des assemblys créés à l'aide d'ASP.NET version 2.0 ou ultérieure.

Vous pouvez utiliser l'outil ASP.NET Compilation Tool pour précompiler une application pour son déploiement. L'outil crée un assembly pour chaque dossier de contenu dans le site Web cible ou il crée un assembly pour chaque fichier de contenu. L'outil ASP.NET Merge Tool vous offre une flexibilité supplémentaire pour le déploiement et la gestion des versions. Il vous permet d'effectuer les opérations suivantes :

• Créer un assembly pour le site Web entier.

• Créer un assembly pour chaque dossier du site Web et ajouter un préfixe au nom de l'assembly.

• Créer un assembly unique simplement pour les éléments de l'interface utilisateur du site Web, tels que les pages et les contrôles.

aspnet_merge     [-?]
                                  applicationPath
                 [-keyfile filename [-delaysign]]
                 [-o assemblyname | -w assemblyname | -prefix prefix]
                 [-copyattrs [assemblyfile]]
                 [-debug]
                 [-nologo]
                 [-errorstack]
                 [-r]
                 [-xmldocs]
                 [-a]
                 [-logfile logfile]
                 [-allowattrs textfile]

Arguments

Options

Option	Description
-keyfile filename	Spécifie que l'attribut AssemblyKeyFileAttribute doit être appliqué à l'assembly compilé. Cet attribut spécifie le nom du fichier qui contient la paire de clés publique et privée utilisée pour générer un nom fort. Si les assemblys d'entrée sont signés et que l'outil de fusion ne signe pas les assemblys, vous recevez un message qui vous prévient que les clés ont été supprimées. Si aucun nom de fichier de clés n'est spécifié, l'outil de fusion échoue si un assembly a une clé publique alors qu'un autre assembly n'en a pas.
-delaysign	Spécifie que l'attribut AssemblyDelaySignAttribute doit être appliqué à l'assembly généré. Cet attribut spécifie qu'un assembly doit être signé uniquement avec le jeton de clé publique, et non pas avec la paire de clés publique/privée. Cette option doit être associée avec l'option -keyfile. Si l'attribut est déjà appliqué à l'assembly dans les fichiers de code, l'outil de fusion lève une exception. Lorsque vous utilisez l'option delaysign, si la vérification des noms forts n'est pas activée, le code produit par l'outil de fusion peut s'exécuter avant que le code soit signé. Si la vérification des noms forts n'est pas activée, assurez-vous que le code n'est pas vulnérable à une attaque menée par des utilisateurs malveillants avant que la signature soit terminée.
-o assemblyname	Spécifie le nom d'un assembly fusionné unique pour tout le contenu de l'interface utilisateur Web et tous les assemblys de niveau supérieur. Tous les fichiers qui présentent l'extension de nom de fichier .compiled sont modifiés pour faire référence à l'assembly unique. (Les fichiers avec l'extension .compiled sont compilés à partir de contenu tel que des fichiers .aspx, .master et .ascx.) Cette option ne peut pas être associée avec les options w ni prefix. Le paramètre assemblyname est obligatoire.
-w assemblyname	Spécifie le nom d'un assembly fusionné unique pour tout le contenu de l'interface utilisateur Web (pages et contrôles utilisateur). Tous les fichiers .aspx, .master et .ascx compilés sont modifiés pour faire référence à l'assembly unique. Cela vous permet de mettre à jour les éléments de l'interface utilisateur séparément du code. Les assemblys de niveau supérieur pour les ressources locales et globales ne sont pas fusionnés. Cette option ne peut pas être associée avec les options o ni prefix. Le paramètre assemblyname est obligatoire.
-prefix prefix	Spécifie un préfixe pour les noms des assemblys. L'assembly du dossier racine possède uniquement le paramètre prefix comme nom de l'assembly. Les assemblys des sous-dossiers ont le paramètre prefix associé au nom du sous-dossier. Par exemple, si un sous-dossier est nommé Admin, l'assembly résultant serait nommé prefix.Admin.dll. Pour les sites Web qui ne peuvent pas être mis à jour, l'outil de compilation compile les thèmes et les ressources locales dans des assemblys distincts, dans le dossier Bin. Pour les sites Web qui peuvent être mis à jour, les thèmes et les ressources locales ne sont pas compilés dans des assemblys, dans le dossier Bin. À la place, ils sont conservés dans leurs dossiers d'origine, dans l'application. En outre, pour les sites pouvant faire l'objet d'une mise à jour, l'outil de fusion modifie les fichiers .aspx, .master et .ascx pour pointer sur le nouvel assembly fusionné du dossier dans lequel les fichiers résident. Cette option ne peut pas être associée avec les options o ni w. Le paramètre prefix est obligatoire.
-copyattrs assemblyfile	Indique que les mêmes attributs d'assembly doivent être assignés à l'assembly ou aux assemblys fusionnés qu'à l'assembly spécifié. Si assemblyFile n'est pas spécifié, l'assembly App_Code est utilisé, même si l'assembly de niveau supérieur App_Code.dll n'est pas inclus dans la sortie fusionnée. S'il existe un attribut incohérent entre un assembly à fusionner et l'assembly assemblyFile, une erreur est levée. Utilisez l'option a pour ignorer la vérification de l'attribut incohérent ou utilisez l'option allowattrs pour spécifier l'attribut à exclure de la vérification. Pour les attributs qui ne sont pas inclus dans la vérification de la cohérence, consultez la description de l'option allowattrs ailleurs dans la table.
-debug	Spécifie que la sortie de débogage doit être conservée dans l'assembly fusionné.
-nologo	Supprime le message de copyright.
-errorstack	Spécifie que l'outil doit inclure des informations sur la trace de la pile s'il ne parvient pas à compiler l'application.
-r	Supprime les fichiers .compiled de l'assembly de code principal (code dans le dossier App_Code). N'utilisez pas cette option si votre application contient une référence de type explicite à l'assembly de code principal.
-xmldocs	Fusionne les fichiers de documentation XML associés aux assemblys d'entrée. Un fichier XML est inclus dans le dossier Bin du site fusionné.
-a	Force l'outil de fusion à fusionner des assemblys qui n'ont pas tous le AllowPartiallyTrustedCallersAttribute appliqué ou qui ont des attributs incohérents. AllowPartiallyTrustedCallersAttribute autorise l'accès d'appelants d'un niveau de confiance partiel à un assembly et est spécifié pendant la compilation par l'outil de compilation. Remarque importante : Lorsque vous utilisez l'option a, les assemblys fusionnés qui n'étaient pas marqués précédemment comme autorisant des appelants d'un niveau de confiance partiel sont marqués avec AllowPartiallyTrustedCallersAttribute. Cela peut conduire à permettre au code de niveau de confiance partiel d'appeler l'assembly.
-log logfile	Écrit les messages dans le fichier spécifié.
-allowattrs textfile	Spécifie un fichier qui contient les attributs à exclure lorsque l'outil vérifie la cohérence d'attributs dans des assemblys fusionnés. Chaque ligne du fichier peut correspondre au nom qualifié complet d'un attribut ou à un espace de noms qualifiés complets. Si un espace de noms est spécifié, tous les attributs trouvés dans cet espace de noms seront exclus. Chaque attribut ou espace de noms doit se trouver sur une ligne distincte. Certains attributs n'ont pas à être spécifiés explicitement. L'outil de fusion fournit en sortie un avertissement s'il rencontre les attributs ci-dessous, puis continue le traitement. System.CodeDom.Compiler.GeneratedCodeAttribute System.Runtime.CompilerServices.CompilationRelaxationsAttribute System.Runtime.CompilerServices.RuntimeCompatibilityAttribute System.Diagnostics.DebuggableAttribute Microsoft.JScript.ReferenceAttribute
-?	Affiche la syntaxe et les options de commande de l'outil.

Notes

Les applications Web ASP.NET peuvent être compilées sur place ou elles peuvent être précompilées pour leur déploiement à un emplacement cible, tel qu'un serveur de production. La compilation d'une application sur place est appelée compilation dynamique et elle est utile dans les scénarios de développement rapide. La précompilation d'une application pour son déploiement peut être exécutée de deux façons différentes :

• en compilant et en supprimant tous les fichiers sources, tels que les fichiers code-behind et de balisage ;

• en compilant et en conservant les fichiers de balisage afin qu'ils puissent être mis à jour.

L'outil ASP.NET Merge Tool fournit une flexibilité supplémentaire lorsque vous précompilez le site Web au delà de ce que vous pouvez accomplir avec l'outil ASP.NET Compilation Tool seul.

L'outil ASP.NET Merge Tool fusionne la sortie de l'outil ASP.NET Compilation Tool pour produire des assemblys. Ces assemblys fusionnés peuvent améliorer la gestion des versions et le déploiement des sites Web de grande taille. Vous pouvez utiliser l'outil ASP.NET Merge Tool de trois manières différentes :

• pour fusionner toutes les sorties dans un assembly unique ;

• pour fusionner le contenu de l'interface utilisateur Web (pages Web, apparences, etc.) de chaque dossier dans son propre assembly ;

• pour fusionner tout le contenu de l'interface utilisateur Web du site dans un assembly unique.

Les rubriques suivantes décrivent ces scénarios : Pour voir des exemples de l'utilisation de l'outil ASP.NET Merge Tool, consultez Managing ASP.NET Precompiled Output for Deployment Using the aspnet_merge.exe Command sur le site Web MSDN.

L'outil ASP.NET Merge Tool est inclus dans Visual Studio Web Deployment Projects, un complément pour Visual Studio qui vous permet de gérer des configurations de génération, de spécifier des tâches avant et après génération, ainsi que de fusionner des assemblys. Pour plus d'informations, consultez Using Web Deployment Projects with Visual Studio 2005.

Groupes d'assemblys

L'outil de compilation crée des assemblys différemment selon le type du dossier et du fichier source. La sortie de l'outil de compilation peut être classée dans deux groupes d'assemblys. L'outil de fusion fusionne les deux groupes d'assemblys différemment.

Les deux groupes d'assemblys sont les suivants :

• Les assemblys de contenu de l'interface utilisateur Web, générés à partir de fichiers de contenu de l'interface utilisateur Web, tels que les fichiers .aspx, .ascx, .master, .ashx, .skin et .resx locaux (dans le dossier App_LocalResources). La façon dont ces assemblys sont fusionnés dépend de ce que le site précompilé peut être mis à jour ou non, ce qui est déterminé par l'option u de l'outil de compilation. Si un site compilé peut être mis à jour, le contenu de l'interface utilisateur peut être mis à jour sans recompiler le site. Lorsqu'un site Web peut être mis à jour, les fichiers de contenu restent dans leurs dossiers d'origine et seuls les fichiers de code associés sont fusionnés. Si le site ne peut pas être mis à jour, les fichiers de contenu .ascx, .master et .skin sont supprimés de leur dossier d'origine. Les fichiers ASP.NET .aspx sont remplacés par un fichier de marquage sans contenu. Dans ce cas, le contenu de l'interface utilisateur et le code sont fusionnés.

• Les assemblys de niveau supérieur, générés à partir de dossiers d'application tels qu'App_Code, App_GlobalResources et App_WebReferences. Les assemblys de niveau supérieur sont également générés pour des fichiers spéciaux tels que Global.asax. Ils sont toujours compilés dans le dossier Bin du site de déploiement. Le site de déploiement final n'aura pas de dossier App_Code, App_GlobalResources ni App_WebReferences, ni de fichier Global.asax. À la place, le site de déploiement final aura un ou plusieurs assemblys dans le répertoire Bin, selon les options utilisées avec l'outil de fusion. Les dossiers définis par l'utilisateur sont toujours compilés également, si ce n'est que le site de déploiement final conserve le dossier défini par l'utilisateur lorsqu'il contient des fichiers de contenu de l'interface utilisateur. Pour plus d'informations sur les dossiers réservés, consultez Disposition des sites Web ASP.NET.

Le contenu statique, tel que les fichiers ayant une extension de nom de fichier telle que .css, .gif, .htm, .html, .jpg, ou .js, est conservé à son emplacement dans la structure de répertoires précompilée. L'outil de fusion ne déplace pas et ne modifie pas ce contenu.

Scénarios de compilation et de fusion

Avec ASP.NET 2.0, vous pouvez associer la compilation dynamique, la précompilation à l'aide de l'outil de compilation et la fusion à l'aide de l'outil de fusion en fonction de vos objectifs de déploiement et de gestion des versions. Le tableau ci-dessous répertorie différents scénarios de compilation et de fusion, et met en évidence le moment où l'outil de fusion doit être utilisé.

Fusion d'une application pour son déploiement

Vous fusionnez les assemblys d'un site Web en exécutant l'outil de fusion et en spécifiant l'emplacement du site précompilé avec le paramètre applicationPath. L'outil ASP.NET Merge Tool fusionne un site précompilé sur place. En d'autres termes, il ne crée pas une nouvelle copie fusionnée du site précompilé. Le paramètre applicationPath peut constituer l'emplacement final pour l'application Web. Le déploiement de l'application compilée peut être également poursuivi, par exemple en copiant le répertoire.

Lorsque l'outil de fusion fusionne un site précompilé, il conserve l'emplacement des fichiers dynamiques tel qu'il apparaît dans la phase précompilée. La seule modification que l'outil de fusion apporte au contenu des fichiers dynamiques consiste à modifier les directives @ Page, @ Control et @ Master. Il s'assure que les fichiers qui possèdent ces directives héritent de l'assembly fusionné correct dans le dossier Bin. Pour plus d'informations sur la façon dont l'outil de compilation traite les types de fichiers, consultez la section « Remarques » de ASP.NET Compilation Tool, outil (Aspnet_compiler.exe).

Pour les assemblys dérivés de dossiers définis par l'utilisateur (y compris le dossier de site racine), certaines options de fusion permettent de créer des noms qui diffèrent de ceux qui apparaissent dans le site précompilé. Par exemple, le tableau ci-dessous indique les noms d'assembly fusionné quand aucune option n'est utilisée avec l'outil de fusion. Le nom de l'assembly de chaque dossier défini par l'utilisateur est App_Web_nnnn.dll, où nnnn est une valeur de hachage générée en interne.

Le tableau ci-dessous indique les noms des assemblys fusionnés lorsque vous utilisez l'option prefix et le paramètre NewName.

Les thèmes sont traités différemment dans un site fusionné ne pouvant pas être mis à jour. Dans le site précompilé, non fusionné, il existe un assembly distinct pour chaque thème. Chaque assembly est nommé App_Theme_NomThème.dll. Dans le site fusionné, il existe un assembly nommé Theme.dll. Si le site précompilé peut être mis à jour, il n'existe pas d'assembly basé sur des thèmes dans le dossier Bin fusionné.

Dépannage du processus de fusion

Lorsqu'un site Web est en cours de compilation ou de fusion, la longueur du chemin d'accès d'un assembly peut dépasser la longueur maximale prévue pour un chemin d'accès de fichier dans Microsoft Windows. Dans ce cas, lorsque vous demandez une ressource à partir de l'assembly fusionné, une erreur HttpException est levée qui indique que la ressource n'a pas été précompilée et ne peut pas être demandée.

La longueur maximale du chemin d'accès d'un fichier dans Microsoft Windows est de 260 caractères. Si le chemin d'accès d'un assembly dépasse cette limite, vous devez raccourcir le chemin d'accès du site Web ou de ses sous-dossiers. Vous pouvez également être amené à désactiver les clichés instantanés dans le fichier Web.config en utilisant la propriété ShadowCopyBinAssemblies de l'élément hostingEnvironment. Pour plus d'informations sur les noms de fichiers, consultez Naming a File sur le site Web MSDN.

Lorsque vous utilisez l'outil de fusion avec l'option o pour créer un assembly unique pour le site, une erreur se produit si le processus de fusion crée des références circulaires. Il existe deux solutions de contournement pour cette situation :

• utiliser l'option w à la place, afin que le fichier source qui contient la référence circulaire reste une référence externe et ne soit pas fusionné ;

• séparer les contrôles impliqués dans une référence circulaire en différents répertoires.

Lorsque vous fusionnez des assemblys qui ont des attributs incohérents, utilisez les instructions suivantes pour vous assurer du succès de l'opération de fusion :

• Répertoriez les attributs incohérents en utilisant l'option allowattrs.

• Utilisez les options copyattrs et assurez-vous que tous les assemblys à fusionner ont des attributs appropriés.

• Utilisez l'option a.

Signatures des assemblys

Les options delaysign et keyfile vous permettent d'utiliser l'outil de fusion pour créer des assemblys à nom fort sans utiliser l'outil Strong Name Tool (Sn.exe). L'option delaysign correspond à l'attribut AssemblyDelaySignAttribute et l'option keyfile correspond à l'attribut AssemblyKeyFileAttribute.

Chaque option applique l'attribut correspondant à l'assembly fusionné. Les attributs appliqués sont marqués avec un attribut AttributeUsageAttribute dont la propriété AllowMultiple a la valeur false. Par conséquent, si vous utilisez ces options lorsque vous fusionnez des assemblys qui sont déjà marqués avec l'un des attributs, la fusion échoue.

Exemples

La commande suivante fusionne les assemblys du site précompilé dans le répertoire C:\PrecompiledSite.

Aspnet_merge C:\PrecompiledSite

La commande ci-dessous fusionne les assemblys d'un site précompilé dans le répertoire C:\PrecompiledSite et signe les assemblys fusionnés à l'aide du fichier KeyFile.snk. Le site fusionné aura un assembly pour chaque dossier du site précompilé.

Aspnet_merge C:\PrecompiledSite -keyfile KeyFile.snk

La commande ci-dessous fusionne tous les assemblys du site précompilé dans le répertoire C:\PrecompiledSite dans un assembly unique et nomme l'assembly résultant MyApp.dll. Le site fusionné aura un assembly pour tout le contenu de l'interface utilisateur du site Web.

Aspnet_merge C:\PrecompiledSite -w MyApp.dll

La commande ci-dessous fusionne tous les assemblys du site précompilé dans le répertoire C:\PrecompiledSite dans un assembly unique et nomme l'assembly résultant MyApp.dll.

Aspnet_merge C:\PrecompiledSite -o MyApp.dll

Voir aussi

Concepts

Temporisation de signature d'un assembly

Assemblys avec nom fort

Référence

AssemblyKeyFileAttribute

AssemblyKeyNameAttribute

AssemblyDelaySignAttribute

AllowPartiallyTrustedCallersAttribute

Outils du .NET Framework

Outil Strong Name Tool (Sn.exe)

ASP.NET Compilation Tool, outil (Aspnet_compiler.exe)