ASP.NET Compilation Tool, outil (Aspnet_compiler.exe)
Mise à jour : novembre 2007
L'outil ASP.NET Compilation Tool (Aspnet_compiler.exe) vous permet de compiler une application Web ASP.NET, soit sur place soit pour le déploiement vers un emplacement cible tel qu'un serveur de production. La compilation sur place aide l'exécution de l'application, car les utilisateurs finaux ne rencontrent pas de retard lors de la première demande à l'application pendant la compilation de l'application.
La compilation pour le déploiement peut être exécutée de deux façons : supprimer tous les fichiers sources, tels que des fichiers code-behind et de balisage, ou conserver les fichiers de balisage.
.gif "Remarque") Remarque : |
|---|
ASP.NET Compilation Tool n'est pas disponible avec les versions d'ASP.NET antérieures à la version 2.0. |
aspnet_compiler [-?]
[-m metabasePath | -v virtualPath [-p physicalPath]]
[[-u] [-f] [-d] [-fixednames] targetDir]
[-c]
[-errorstack]
[-nologo]
[[-keyfile file | -keycontainer container ] [-aptca] [-delaysign]]
Options
Option |
Description |
|---|---|
-m metabasePath |
Spécifie le chemin d'accès complet à la métabase IIS de l'application à compiler. La métabase IIS est une banque d'informations hiérarchique qui est utilisée pour configurer les services IIS. Par exemple, le chemin d'accès de la métabase pour le site Web IIS par défaut est LM/W3SVC/1/ROOT. Cette option ne peut pas être combinée avec les options -v ou -p. |
-v virtualPath |
Spécifie le chemin d'accès virtuel de l'application à compiler. Si -p est également spécifié, la valeur du paramètre physicalPath qui l'accompagne est utilisée pour localiser l'application à compiler. Sinon, la métabase IIS est utilisée, et l'outil suppose que les fichiers sources sont situés sous le site Web par défaut (spécifié dans le nœud de métabase LM/W3SVC/1/ROOT). Cette option ne peut pas être combinée avec l'option -m. |
-p physicalPath |
Spécifie le chemin d'accès réseau complet ou le chemin d'accès du disque local du répertoire racine qui contient l'application à compiler. Si -p n'est pas spécifié, la métabase IIS est utilisée pour rechercher le répertoire. Cette option doit être combinée avec l'option -v et ne peut pas être combinée avec l'option -m. |
-u |
Spécifie que Aspnet_compiler.exe doit créer une application précompilée qui autorise des mises à jour ultérieures de contenus tels que les pages .aspx. Si cette option est omise, l'application résultante contient uniquement des fichiers compilés et ne peut pas être mise à jour sur le serveur de déploiement. Vous pouvez mettre à jour l'application uniquement en modifiant les fichiers de balisage source et en effectuant une recompilation. Le paramètre targetDir doit être inclus. |
-f |
Spécifie que l'outil doit remplacer les fichiers existants dans le répertoire targetDir et ses sous-répertoires. |
-d |
Substitue les paramètres définis dans les fichiers de configuration source de l'application pour forcer l'intégration des informations de débogage dans l'application compilée. Sinon, aucune sortie de débogage n'est émise. Vous ne pouvez pas utiliser l'option -d pour la compilation sur place ; celle-ci honore des paramètres de configuration pour les options de débogage. |
targetDir |
Chemin d'accès réseau ou chemin d'accès du disque local vers le répertoire racine qui contiendra l'application compilée. Si le paramètre targetDir n'est pas inclus, l'application est compilée sur place. |
-c |
Spécifie que l'application à compiler doit être complètement régénérée. Les composants qui ont déjà été compilés sont de nouveau compilés. Si cette option est omise, l'outil génère uniquement les parties de l'application qui ont été modifiées depuis la dernière exécution de la compilation. |
-errorstack |
Spécifie que l'outil doit inclure des informations sur la trace de pile s'il ne parvient pas à compiler l'application. |
-keyfile file |
Spécifie que l'AssemblyKeyFileAttribute, qui indique le nom du fichier contenant la paire de clés publique/privée utilisée pour générer un nom fort, doit être appliqué à l'assembly compilé. Cette option ne peut pas être combinée avec l'option -aptca. Si l'attribut est déjà appliqué à l'assembly dans les fichiers de code, Aspnet_compiler.exe lève une exception. |
-keycontainer container |
Spécifie que l'AssemblyKeyNameAttribute, qui indique le nom du conteneur pour la paire de clés publique/privée utilisée afin de générer un nom fort, doit être appliqué à l'assembly compilé. Cette option ne peut pas être combinée avec l'option -aptca. Si l'attribut est déjà appliqué à l'assembly dans les fichiers de code, Aspnet_compiler.exe lève une exception. |
-aptca |
Spécifie que l'AllowPartiallyTrustedCallersAttribute, qui autorise l'accès à un assembly à des appelants d'un niveau de confiance partiel, doit être appliqué à l'assembly avec un nom fort qu'Aspnet_compiler.exe génère. Cette option doit être combinée avec l'option -keyfile ou -keycontainer. Si l'attribut est déjà appliqué à l'assembly dans les fichiers de code, Aspnet_compiler.exe lève une exception. |
-delaysign |
Spécifie que l'AssemblyDelaySignAttribute, qui indique qu'un assembly doit être signé uniquement avec le jeton de clé publique plutôt qu'avec la paire de clés publique/privée, doit s'appliquer à l'assembly généré. Cette option doit être combinée avec l'option -keyfile ou -keycontainer. Si l'attribut est déjà appliqué à l'assembly dans les fichiers de code, Aspnet_compiler.exe lève une exception. Lorsque vous utilisez l'option -delaysign, le code produit par Aspnet_compilier.exe peut être exécuté avant la signature du code. Vous devez vérifier que le code est protégé contre tout utilisateur malveillant avant la fin de la signature. |
-fixednames |
Spécifie qu'un assembly doit être généré pour chaque page dans l'application. Chaque assembly est nommé avec le chemin d'accès virtuel de la page d'origine, à moins que le nom dépasse la limite du système d'exploitation pour les noms de fichiers, auquel cas un hachage est généré et utilisé pour le nom de l'assembly. Vous ne pouvez pas utiliser l'option -fixednames pour la compilation sur place ; celle-ci honore des paramètres de configuration pour le mode batch de compilation. |
-nologo |
Supprime le message de copyright. |
-? |
Affiche la syntaxe et les options de commande de l'outil. |
Notes
ASP.NET Compilation Tool peut être utilisé de deux façons : pour la compilation sur place ainsi que la compilation pour le déploiement, où un répertoire de sortie cible est spécifié. Les rubriques suivantes décrivent ces scénarios :
Compilation d'une application sur place
ASP.NET Compilation Tool peut compiler une application sur place, c'est-à-dire qu'il reproduit le comportement consistant à faire plusieurs demandes à l'application, provoquant ainsi la compilation normale. Les utilisateurs d'un site précompilé ne rencontreront pas de délai provoqué par la compilation de la page lors d'une première demande.
Notez que si vous utilisez un compte emprunté, ce compte et le compte utilisateur d'ouverture de session doivent tous deux avoir accès en écriture à la cible pour que la précompilation réussisse.
Lorsque vous précompilez un site sur place, les éléments suivants s'appliquent :
Le site conserve ses fichiers et sa structure de répertoire.
Vous devez posséder des compilateurs pour tous les langages de programmation utilisés par le site sur le serveur.
Si la compilation pour un fichier échoue, la compilation pour le site entier échoue.
Vous pouvez également recompiler une application sur place après lui avoir ajouté de nouveaux fichiers sources. L'outil compile uniquement les fichiers nouveaux ou modifiés, à moins que vous incluiez l'option -c.
| Remarque : |
|---|
La compilation d'une application qui contient une application imbriquée ne compile pas l'application imbriquée. L'application imbriquée doit être compilée séparément. |
| Remarque : |
|---|
Lorsque vous compilez une application Web qui inclut des pages maîtres, la compilation peut échouer si vous compilez l'application en tant que site pouvant être mis à jour et un conflit de noms se produit. Le conflit peut se produire si le nom de la page maître correspond au nom de l'espace de noms pour une page de contenu qui dérive de la page maître. (La relation d'héritage est établie par l'attribut Inherits de la directive @ Page). Pour contourner ce problème, vous pouvez modifier le nom de la classe de la page maître ou modifier le nom de l'espace de noms, ou vous pouvez compiler l'application comme une application ne pouvant pas être mise à jour. |
Compilation d'une application pour déploiement
Vous compilez une application pour le déploiement (compilation vers un emplacement cible) en spécifiant le paramètre targetDir. Le targetDir peut être le dernier emplacement pour l'application Web, ou l'application compilée peut être encore déployée.
L'utilisation de l'option -u compile l'application d'une telle façon que vous pouvez apporter des modifications à certains fichiers dans l'application compilée sans la recompiler. Aspnet_compiler.exe fait une distinction entre les types de fichiers statiques et dynamiques, et les traite différemment lors de la création de l'application résultante.
Les types de fichier statiques sont ceux qui n'ont pas de compilateur ou de fournisseur de générations associé, tels que les fichiers dont les noms ont les extensions .css, .gif, .htm, .html, .jpg, .js, etc. Ces fichiers sont simplement copiés vers l'emplacement cible, et leurs places relatives dans la structure de répertoire sont conservées.
Les types de fichier dynamiques sont ceux qui ont un compilateur ou un fournisseur de générations associé, y compris les fichiers avec les extensions de nom de fichier spécifiques à ASP.NET telles que .asax, .ascx, .ashx, .aspx, .browser, .master, etc. ASP.NET Compilation Tool génère des assemblys à partir de ces fichiers. Si l'option -u est omise, l'outil crée également des fichiers avec l'extension de nom de fichier .COMPILED qui mappe les fichiers sources d'origine à leur assembly. Pour garantir que la structure de répertoire de la source d'application est stockée, l'outil génère des fichiers d'espace réservé dans les emplacements correspondants dans l'application cible.
Vous devez utiliser l'option -u pour indiquer que le contenu de l'application compilée peut être modifié. Sinon, les modifications ultérieures sont ignorées ou provoquent des erreurs d'exécution.
Le tableau suivant décrit comment l'outil ASP.NET Compilation Tool gère des types de fichier différents lorsque l'option -u est incluse.
Type de fichier |
Action de compilateur |
||
|---|---|---|---|
.aspx, .ascx, .master |
Ces fichiers sont répartis entre le balisage et le code source, qui inclut les fichiers code-behind. Le code source est compilé dans des assemblys, avec des noms dérivés d'un algorithme de hachage, et les assemblys sont placés dans le répertoire Bin. Tout code incorporé, c'est-à-dire du code placé entre les éléments <script runat="server">, est inclus avec le balisage et n'est pas compilé. De nouveaux fichiers avec le même nom que les fichiers sources sont créés pour contenir le balisage et sont placés dans les répertoires de sortie correspondants. |
||
.ashx, .asmx |
Ces fichiers ne sont pas compilés et sont déplacés tels quels vers les répertoires de sortie, sans être compilés. Si vous souhaitez que le code de gestionnaire soit compilé, placez le code dans les fichiers de code source dans le répertoire App_Code. |
||
.cs, .vb, .jsl, .cpp (les fichiers code-behind pour les types de fichier répertoriés précédemment ne sont pas compris) |
Ces fichiers sont compilés et inclus en tant que ressource dans les assemblys qui les référencent. Les fichiers sources ne sont pas copiés vers le répertoire de sortie. Si un fichier de code n'est pas référencé, il n'est pas compilé. |
||
Types de fichier personnalisés |
Ces fichiers ne sont pas compilés. Ils sont copiés vers les répertoires de sortie correspondants. |
||
Fichiers de code source dans le sous-répertoire App_Code |
Ces fichiers sont compilés dans des assemblys et placés dans le répertoire Bin.
|
||
Fichiers .resx et .resource dans le sous-répertoire App_GlobalResources |
Ces fichiers sont compilés dans des assemblys et placés dans le répertoire Bin. Aucun sous-répertoire App_GlobalResources n'est créé sous le répertoire de sortie principal, et aucun fichier .resx ou .resources situé dans le répertoire source n'est copié vers les répertoires de sortie.
|
||
Fichiers .resx et .resource dans le sous-répertoire App_LocalResources |
Ces fichiers ne sont pas compilés et sont copiés vers les répertoires de sortie correspondants. |
||
Fichiers .skin dans le sous-répertoire App_Themes |
Les fichiers .skin et les fichiers de thème statiques ne sont pas compilés et sont copiés vers les répertoires de sortie correspondants. |
||
.browser Web.config Types de fichier statiques Assemblys déjà présents dans le répertoire Bin |
Ces fichiers sont copiés tels quels dans les répertoires de sortie. |
Le tableau suivant décrit comment l'outil ASP.NET Compilation Tool gère des types de fichier différents lorsque l'option -u est omise.
| Remarque : |
|---|
Aucun avertissement n'est émis pour vous empêcher de modifier le code source d'une application compilée. |
Type de fichier |
Action de compilateur |
||
|---|---|---|---|
.aspx, .asmx, .ashx, .master |
Ces fichiers sont répartis entre le balisage et le code source, qui inclut les fichiers code-behind et tout code placé entre les éléments <script runat="server">. Le code source est compilé dans des assemblys, avec des noms dérivés d'un algorithme de hachage. Les assemblys résultants sont placés dans le répertoire Bin. Tout code incorporé, c'est-à-dire du code placé entre les crochets <% et %>, est inclus avec le balisage et n'est pas compilé. Le compilateur crée de nouveaux fichiers pour contenir le balisage avec le même nom que les fichiers sources. Ces fichiers résultants sont placés dans le répertoire Bin. Le compilateur crée également des fichiers avec le même nom que les fichiers sources, mais avec l'extension .COMPILED, qui contiennent des informations de mappage. Les fichiers .COMPILED sont placés dans les répertoires de sortie qui correspondent à l'emplacement d'origine des fichiers sources. |
||
.ascx |
Ces fichiers sont répartis entre le balisage et le code source. Le code source est compilé dans des assemblys et placé dans le répertoire Bin, avec des noms qui sont dérivés d'un algorithme de hachage. Aucun fichier de balisage n'est généré. |
||
.cs, .vb, .jsl, .cpp (les fichiers code-behind pour les types de fichier répertoriés précédemment ne sont pas compris) |
Le code source qui est référencé par les assemblys générés à partir de fichiers .ascx, .ashx ou .aspx, est compilé dans des assemblys et placé dans le répertoire Bin. Aucun fichier source n'est copié. |
||
Types de fichier personnalisés |
Ces fichiers sont compilés comme des fichiers dynamiques. Selon le type de fichier sur lequel ils sont basés, le compilateur peut placer des fichiers de mappage dans les répertoires de sortie. |
||
Fichiers dans le sous-répertoire App_Code |
Les fichiers de code source dans ce sous-répertoire sont compilés dans des assemblys et placés dans le répertoire Bin.
|
||
Fichiers dans le sous-répertoire App_GlobalResources |
Ces fichiers sont compilés dans des assemblys et placés dans le répertoire Bin. Aucun sous-répertoire App_GlobalResources n'est créé sous le répertoire de sortie principal. Si le fichier de configuration spécifie appliesTo="All", les fichiers .resx et .resources sont copiés vers les répertoires de sortie. Ils ne sont pas copiés s'ils sont référencés par un BuildProvider. |
||
Fichiers .resx et .resource dans le sous-répertoire App_LocalResources |
Ces fichiers sont compilés dans des assemblys avec des noms uniques et sont placés dans le répertoire Bin. Aucun fichier .resx ou .resource n'est copié vers les répertoires de sortie. |
||
Fichiers .skin dans le sous-répertoire App_Themes |
Les thèmes sont compilés dans des assemblys et placés dans le répertoire Bin. Les fichiers stub sont créés pour les fichiers .skin et sont placés dans le répertoire de sortie correspondant. Les fichiers statiques (tels que .css) sont copiés vers les répertoires de sortie. |
||
.browser Web.config Types de fichier statiques Assemblys déjà présents dans le répertoire Bin |
Ces fichiers sont copiés tels quels dans le répertoire de sortie. |
Noms d'assemblys fixes
Certains scénarios, tels que le déploiement d'une application Web à l'aide du MSI Windows Installer, requièrent l'utilisation de noms de fichiers et de contenus cohérents, ainsi que de structures de répertoire cohérentes afin d'identifier des assemblys ou des paramètres de configuration pour les mises à jour. Dans ces situations, vous pouvez utiliser l'option -fixednames pour spécifier que l'outil ASP.NET Compilation Tool doit compiler un assembly pour chaque fichier source au lieu d'utiliser la méthode où plusieurs pages sont compilées dans des assemblys. Cette opération pouvant générer un grand nombre d'assemblys, vous devez utiliser cette option avec prudence si vous accordez de l'importance à l'évolutivité.
Compilation avec nom fort
Les options -aptca, -delaysign, -keycontainer et -keyfile sont fournies afin que vous puissiez utiliser Aspnet_compiler.exe pour créer des assemblys avec des noms forts sans utiliser l'Outil Strong Name Tool (Sn.exe) séparément. Ces options correspondent respectivement à AllowPartiallyTrustedCallersAttribute, AssemblyDelaySignAttribute, AssemblyKeyNameAttribute et AssemblyKeyFileAttribute. Étant donné que chaque option applique l'attribut correspondant à l'assembly compilé, et que les attributs sont marqués avec un AttributeUsageAttribute dont la propriété AllowMultiple a la valeur false, l'utilisation de ces clés sur le code source déjà marqué avec l'un de ces attributs provoque l'échec de la compilation.
Classes ASP.NET associées
Plusieurs classes dans l'espace de noms System.Web.Compilation permettent à votre code d'accéder à Aspnet_compiler.exe ou de l'appeler en dehors de l'environnement IIS. La classe ClientBuildManager fournit la méthode PrecompileApplication pour compiler une application. La classe ClientBuildManager fonctionne également avec la classe ClientBuildManagerParameter, qui vous permet de spécifier PrecompilationFlags qui correspond aux options utilisées par cet outil, et de la même façon, de spécifier des clés de nom fort.
Exemples
La commande suivante compile l'application WebApplication1 sur place :
Aspnet_compiler -v /WebApplication1
La commande suivante compile l'application WebApplication1 sur place, et l'outil ajoute des informations sur la trace de la pile s'il doit rapporter des erreurs.
Aspnet_compiler -v /WebApplication1 -errorstack
La commande suivante compile l'application WebApplication1 pour le déploiement, à l'aide du chemin d'accès physique au répertoire. Elle ajoute également deux attributs aux assemblys de sortie. Elle utilise l'option -keyfile pour ajouter un attribut AssemblyKeyFileAttribute qui spécifie que le fichier Key.sn contient les informations de la paire de clés publique/privée que l'outil doit utiliser pour fournir des noms forts aux assemblys générés. La commande utilise également l'option -aptca pour ajouter un attribut AllowPartiallyTrustedCallersAttribute aux assemblys générés. L'application Web compilée est créée dans le répertoire c:\applicationTarget.
Aspnet_compiler -v /WebApplication1 -p "c:\Documents and Settings\Default\My Documents\MyWebApplications\WebApplication1" -keyfile "c:\Documents and Settings\Default\My Documents\Key.sn" -aptca c:\applicationTarget
La commande suivante compile le service WebService2 sous le chemin d'accès de métabase par défaut, en remplaçant le répertoire cible SampleWebService avec l'application compilée.
Aspnet_compiler -m /LM/W3SVC/1/ROOT/WebService2 -f c:\InetPub\wwwroot\SampleWebService
Voir aussi
Concepts
Temporisation de signature d'un assembly
Référence
AllowPartiallyTrustedCallersAttribute