ASP.NET-Zusammenführungstool (Aspnet_merge.exe)

Aktualisiert: November 2007

Mit dem ASP.NET-Zusammenführungstool (Aspnet_merge.exe) können Sie Assemblys, die mit dem ASP.NET-Kompilierungstool (Aspnet_compiler.exe) erstellt wurden, kombinieren und verwalten. Das ASP.NET-Zusammenführungstool kann für Assemblys verwendet werden, die mit ASP.NET Version 2.0 oder höher erstellt wurden.

Das ASP.NET-Kompilierungstool ermöglicht Ihnen, eine Anwendung für die Bereitstellung vorzukompilieren. Das Tool erstellt für jeden Inhaltsordner in der Zielwebsite oder für jede Inhaltsdatei eine Assembly. Das ASP.NET-Zusammenführungstool bietet Ihnen zusätzliche Flexibilität bei der Bereitstellung und Versionsverwaltung. Es bietet folgende Möglichkeiten:

• Erstellen einer Assembly für die gesamte Website

• Erstellen einer Assembly für jeden Websiteordner und Hinzufügen eines Präfix zum Assemblynamen

• Erstellen einer Assembly für die Elemente der Websitebenutzeroberfläche, z. B. für Seiten und Steuerelemente

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

Argumente

Optionen

Option	Beschreibung
-keyfile filename	Gibt an, dass das AssemblyKeyFileAttribute-Attribut auf die kompilierte Assembly angewendet werden soll. Das Attribut kennzeichnet den Namen der Datei mit dem öffentlichen/privaten Schlüsselpaar, das zum Generieren eines starken Namens verwendet wird. Wenn die Eingabeassemblys signiert sind und das Zusammenführungstool Assemblys nicht signiert, wird eine Warnung angezeigt, dass die Schlüssel entfernt wurden. Wenn kein Schlüsseldateiname angegeben wurde und eine Assembly einen öffentlichen Schlüssel enthält und eine andere Assembly nicht, schlägt das Zusammenführungstool fehl.
-delaysign	Gibt an, dass das AssemblyDelaySignAttribute-Attribut auf die generierte Assembly angewendet werden soll. Dieses Attribut kennzeichnet, dass eine Assembly statt mit dem öffentlichen/privaten Schlüsselpaar nur mit dem öffentlichen Schlüsseltoken signiert werden soll. Diese Option muss mit der -keyfile-Option kombiniert werden. Wenn das Attribut bereits in Codedateien auf die Assembly angewendet wurde, löst das Zusammenführungstool eine Ausnahme aus. Wenn Sie die delaysign-Option verwenden und die Überprüfung mit starkem Namen nicht aktiviert ist, kann der von dem Zusammenführungstool erzeugte Code ausgeführt werden, bevor der Code signiert wurde. Stellen Sie bei Deaktivierung der Überprüfung mit starkem Namen sicher, dass der Code bis zum Abschluss des Signaturvorgangs nicht anfällig gegenüber Angriffen durch böswillige Benutzer ist.
-o assemblyname	Gibt den Namen einer einzelnen, zusammengeführten Assembly für den gesamten Inhalt der Webbenutzeroberfläche und für Assemblys der obersten Ebene an. Alle Dateien mit der Dateinamenerweiterung .compiled werden geändert, um auf die einzelne Assembly zu verweisen. (Dateien mit der Erweiterung .compiled werden aus dem Inhalt kompiliert, z. B. aus .aspx-, .master- und .ascx-Dateien.) Diese Option kann nicht mit der w-Option oder der prefix-Option kombiniert werden. Der assemblyname-Parameter ist erforderlich.
-w assemblyname	Gibt den Namen einer einzelnen, zusammengeführten Assembly für den gesamten Inhalt der Webbenutzeroberfläche an (Seiten und Benutzersteuerelemente). Alle kompilierten ASPX-, MASTER- und ASCX-Dateien werden geändert, so dass sie auf die einzelne Assembly verweisen. Dies ermöglicht Ihnen, Benutzeroberflächenelemente getrennt vom Code zu aktualisieren. Assemblys der obersten Ebene für lokale und globale Ressourcen werden nicht zusammengeführt. Diese Option kann nicht mit der o-Option oder der prefix-Option kombiniert werden. Der assemblyname-Parameter ist erforderlich.
-prefix prefix	Gibt ein Präfix für die Namen von Assemblys an. Die Stammordnerassembly verwendet nur den prefix-Parameter als Namen der Assembly. Unterordnerassemblys nutzen den prefix-Parameter zusammen mit dem Unterordnernamen. Wenn der Name eines Unterordners beispielsweise Admin lautet, würde die resultierende Assembly prefix.Admin.dll heißen. Bei Websites, die nicht aktualisiert werden können, kompiliert das Kompilierungstool Designs und lokale Ressourcen in separaten Assemblys im Ordner Bin. Bei Websites, die eine Aktualisierung zulassen, werden Designs und lokale Ressourcen nicht in Assemblys im Ordner Bin kompiliert. Sie verbleiben stattdessen in den ursprünglichen Ordnern innerhalb der Anwendung. Das Zusammenführungstool ändert bei aktualisierbaren Sites darüber hinaus die ASPX-, MASTER- und ASCX-Dateien, so dass diese auf die neue, zusammengeführte Assembly und den Ordner, in dem die Dateien gespeichert sind, verweisen. Diese Option kann nicht mit der o-Option oder der w-Option kombiniert werden. Der prefix-Parameter ist erforderlich.
-copyattrs assemblyfile	Gibt an, dass der zusammengeführten Assembly die gleichen Assemblyattribute wie der genannten Assembly zugewiesen werden sollen. Wenn assemblyFile nicht angegeben wird, wird die App_Code-Assembly verwendet. Dies ist auch dann der Fall, wenn die Assembly der obersten Ebene, App_Code.dll, in der zusammengeführten Ausgabe nicht enthalten ist. Bei Attributinkonsistenzen zwischen einer zusammenzuführenden Assembly und der assemblyFile-Assembly wird ein Fehler ausgegeben. Verwenden Sie die a-Option, um die Überprüfung auf inkonsistente Attribute zu umgehen, oder die allowattrs-Option, um ein Attribut anzugeben, das aus der Überprüfung ausgeschlossen werden soll. Weitere Informationen zu Attributen, die nicht in die Konsistentprüfung eingeschlossen sind, finden Sie in der Beschreibung zur allowattrs-Option in der Tabelle.
-debug	Gibt an, dass die Debugausgabe in der zusammengeführten Assembly beibehalten werden soll.
-nologo	Unterdrückt die Copyrightmeldung.
-errorstack	Gibt an, dass das Tool bei fehlgeschlagener Kompilierung der Anwendung Stapelüberwachungsinformationen berücksichtigen soll.
-r	Entfernt die COMPILED-Dateien für die Hauptcodeassembly (Code im Ordner App_Code). Verwenden Sie diese Option nicht, wenn die Anwendung einen expliziten Typverweis auf die Hauptcodeassembly enthält.
-xmldocs	Führt XML-Dokumentationsdateien zusammen, die den Eingabeassemblys zugeordnet sind. Eine XML-Datei ist im Ordner Bin der zusammengeführten Site enthalten.
-a	Erzwingt die Zusammenführung von Assemblys durch das Zusammenführungstool, auf die das AllowPartiallyTrustedCallersAttribute nicht durchgehend angewendet wurde oder die inkonsistente Attribute aufweisen. Das AllowPartiallyTrustedCallersAttribute ermöglicht, dass nicht voll vertrauenswürdige Aufrufer auf eine Assembly zugreifen. Es wird während der Kompilierung durch das Kompilierungstool angegeben. Wichtiger Hinweis: Bei Verwendung der a-Option werden zusammengeführte Assemblys mit AllowPartiallyTrustedCallersAttribute gekennzeichnet, wenn Sie nicht zuvor angegeben haben, dass teilweise vertrauenswürdige Aufrufer zulässig sind. Dies kann dazu führen, dass die Assembly durch teilweise vertrauenswürdigen Code aufgerufen werden kann.
-log logfile	Schreibt Meldungen in die angegebene Datei.
-allowattrs textfile	Gibt eine Datei mit Attributen an, die beim Überprüfen der Konsistenz von Attributen in zusammengeführten Assemblys durch das Tool ausgeschlossen werden sollen. Die einzelnen Zeilen in der Datei enthalten entweder den vollständig qualifizierten Namen des Attributs oder den vollständig qualifizierten Namespace. Wenn ein Namespace angegeben wird, werden alle in diesem Namespace enthaltenen Attribute ausgeschlossen. Jedes Attribut bzw. jeder Namespace muss in einer separaten Zeile angegeben werden. Einige Attribute müssen nicht explizit angegeben werden. Das Zusammenführungstool gibt eine Warnung aus, wenn die folgenden Attribute gefunden werden, und setzt die Verarbeitung anschließend fort. System.CodeDom.Compiler.GeneratedCodeAttribute System.Runtime.CompilerServices.CompilationRelaxationsAttribute System.Runtime.CompilerServices.RuntimeCompatibilityAttribute System.Diagnostics.DebuggableAttribute Microsoft.JScript.ReferenceAttribute
-?	Zeigt die Befehlssyntax und -optionen für das Tool an.

Hinweise

ASP.NET-Webanwendungen können direkt kompiliert oder für die Bereitstellung an einem Zielort, z. B. auf einem Produktionsserver, vorkompiliert werden. Die direkte Kompilierung einer Anwendung wird als dynamische Kompilierung bezeichnet und ist in schnellen Entwicklungsszenarios nützlich. Um eine Anwendung für die Bereitstellung vorzukompilieren, stehen zwei Methoden zur Auswahl:

• Das Kompilieren und Entfernen aller Quelldateien, z. B. Code-Behind- und Markupdateien

• Das Kompilieren und Beibehalten der Markupdateien, so dass sie aktualisiert werden können

Das ASP.NET-Zusammenführungstool bietet beim Vorkompilieren der Website eine höhere Flexibilität als das ASP.NET-Kompilierungstool.

Das ASP.NET-Zusammenführungstool führt die Ausgabe des ASP.NET-Kompilierungstools zusammen, um Assemblys zu erzeugen. Diese zusammengeführten Assemblys verbessern die Versionsverwaltung und Bereitstellung für große Websites. Sie können das ASP.NET-Zusammenführungstool auf drei Arten verwenden:

• Zusammenführen der gesamten Ausgabe in einer einzelnen Assembly

• Zusammenführen des Webbenutzeroberflächeninhalts (Webseiten, Designs usw.) jedes Ordners in einer separaten Assembly

• Zusammenführen des gesamten Webbenutzeroberflächeninhalts der Site in einer einzelnen Assembly

In den folgenden Abschnitten werden diese Szenarien beschrieben. Beispiele für die Verwendung des ASP.NET-Zusammenführungstools finden Sie auf der MSDN-Website unter Managing ASP.NET Precompiled Output for Deployment Using the aspnet_merge.exe Command.

Das ASP.NET-Zusammenführungstool ist im Lieferumfang von Visual Studio Web Deployment Projects enthalten. Mit diesem Add-In für Visual Studio können Sie Buildkonfigurationen verwalten, Präbuild- und Postbuildaufgaben festlegen und Assemblys zusammenführen. Weitere Informationen finden Sie unter Using Web Deployment Projects with Visual Studio 2005.

Assemblygruppen

Das Kompilierungstool erstellt Assemblys abhängig vom Typ der Quelldatei und vom Ordner. Die Ausgabe des Kompilierungstools kann in zwei Assemblygruppen klassifiziert werden. Das Zusammenführungstool führt diese zwei Assemblygruppen jeweils unterschiedlich zusammen.

Die zwei Assemblygruppen sind:

• Assemblys mit Webbenutzeroberflächeninhalt, die aus ASPX-, ASCX-, MASTER-, ASHX-, SKIN- und lokalen RESX-Dateien generiert werden (im Ordner App_LocalResources). Wie diese Assemblys zusammengeführt werden, hängt davon ab, ob die vorkompilierte Site aktualisiert werden kann, was durch die u-Option des Kompilierungstools festgelegt wird. Ist eine kompilierte Site aktualisierbar, kann der Benutzeroberflächeninhalt ohne Neukompilierung der Site aktualisiert werden. Bei aktualisierbaren Websites bleiben die Inhaltsdateien in den ursprünglichen Ordnern, und es werden nur die zugehörigen Codedateien zusammengeführt. Wenn die Site nicht aktualisiert werden kann, werden die ASCX-, MASTER- und SKIN-Inhaltsdateien aus dem Originalordner gelöscht. ASP.NET-ASPX-Dateien werden durch eine Markerdatei ersetzt, die keinen Inhalt hat. Benutzeroberflächeninhalt und Code werden in diesem Fall zusammengeführt.

• Assemblys der obersten Ebene, die aus Anwendungsordnern wie App_Code, App_GlobalResources, App_WebReferences generiert werden. Assemblys der obersten Ebene werden zudem für spezielle Dateien generiert, z. B. für Global.asax. Assemblys der obersten Ebene werden immer im Ordner Bin der Bereitstellungssite kompiliert. Die endgültige Bereitstellungssite enthält keinen Ordner App_Code, App_GlobalResources oder App_WebReferences und keine Datei Global.asax. Stattdessen enthält die endgültige Bereitstellungssite eine oder mehrere Assemblys im Verzeichnis Bin, je nachdem, welche Optionen Sie mit dem Zusammenführungstool verwendet haben. Zudem werden immer benutzerdefinierte Ordner kompiliert. Die endgültige Bereitstellungssite behält die benutzerdefinierten Ordner bei, wenn diese Benutzeroberflächeninhaltsdateien enthalten. Weitere Informationen zu reservierten Ordnern finden Sie unter ASP.NET-Websitelayout.

Statischer Inhalt, z. B. Dateien mit den Erweiterungen .css, .gif, .htm, .html, .jpg oder .js, bleiben in der kompilierten Verzeichnisstruktur am ursprünglichen Speicherort erhalten. Sie werden vom Zusammenführungstool weder verschoben, noch geändert.

Kompilierungs- und Zusammenführungsszenarios

Mit ASP.NET 2.0 können Sie eine Kombination aus dynamischer Kompilierung, Vorkompilierung mit dem Kompilierungstool und Zusammenführung mit dem Zusammenführungstool nutzen, um Ihre Anforderungen an Bereitstellung und Versionsverwaltung zu erfüllen. Die folgende Tabelle enthält verschiedene Kompilierungs- und Zusammenführungsszenarios und kennzeichnet, wenn das Zusammenführungstool verwendet werden sollte.

Zusammenführen einer Anwendung zur Bereitstellung

Sie führen die Assemblys für eine Website zusammen, indem Sie das Zusammenführungstool ausführen und den Speicherort der vorkompilierten Site mit dem applicationPath-Parameter angeben. Das ASP.NET-Zusammenführungstool führt eine vorkompilierte Site direkt zusammen. Es wird keine neue zusammengeführte Kopie der vorkompilierten Site erstellt. Der endgültige Speicherort für die Webanwendung kann durch den applicationPath-Parameter angegeben werden. Alternativ kann die kompilierte Anwendung jedoch auch anderweitig bereitgestellt werden, z. B. durch das Kopieren des Verzeichnisses.

Wenn Sie mit dem Zusammenführungstool eine vorkompilierte Site zusammenführen, wird der Speicherort der dynamischen Dateien beibehalten, der bei der Vorkompilierung angegeben wurde. Der Inhalt dynamischer Dateien wird durch das Zusammenführungstool lediglich im Hinblick auf die @ Page-, @ Control- und @ Master-Direktiven geändert. So wird sichergestellt, dass Dateien mit diesen Direktiven von der korrekten zusammengeführten Assembly im Ordner Bin erben. Weitere Informationen darüber, wie das Kompilierungstool Dateitypen verarbeitet, finden Sie im Abschnitt "Hinweise" unter ASP.NET-Kompilierungstool (Aspnet_compiler.exe).

Bei Assemblys, die aus benutzerdefinierten Ordnern (einschließlich des Stammordners) abgeleitet wurden, werden durch bestimmte Zusammenführungsoptionen ggf. Namen erzeugt, die von den Namen in der vorkompilierten Site abweichen. Die folgende Tabelle enthält die Namen zusammengeführter Assemblys, wenn im Zusammenführungstool keine Optionen verwendet werden. Der Assemblyname für benutzerdefinierte Ordner lautet App_Web_nnnn.dll, wobei nnnn ein intern generierter Hashwert ist.

Die folgende Tabelle enthält die Namen zusammengeführter Assemblys, wenn Sie die prefix-Option und den NewName-Parameter verwenden.

Designs werden in einer zusammengeführten Site, die nicht aktualisierbar ist, anders verarbeitet. Die vorkompilierte, nicht zusammengeführte Site enthält eine separate Assembly für jedes Design. Der Name der einzelnen Assemblys lautet App_Theme_ThemeName.dll. Die zusammengeführte Site enthält eine Assembly mit dem Namen Theme.dll. Wenn die vorkompilierte Site aktualisierbar ist, beinhaltet der zusammengeführte Ordner Bin keine Assemblys, die auf Designs basieren.

Beheben von Fehlern im Zusammenführungsprozess

Der Pfad einer Assembly kann beim Kompilieren und Zusammenführen einer Website relativ lang werden und die in Microsoft Windows maximal zulässige Pfadlänge überschreiten. Wenn Sie in diesem Fall eine Ressource aus der zusammengeführten Assembly abfragen, wird ein HttpException-Fehler ausgegeben, demzufolge die Ressource nicht vorkompiliert wurde und nicht abgerufen werden kann.

Die maximale Länge für Dateipfade in Microsoft Windows beträgt 260 Zeichen. Überschreitet der Pfad einer Assembly diesen Grenzwert, müssen Sie den Pfad der Website oder der Unterordner kürzen. Weiterhin kann es erforderlich sein, Schattenkopien in der Datei Web.config mithilfe der ShadowCopyBinAssemblies-Eigenschaft des hostingEnvironment-Elements zu deaktivieren. Weitere Informationen zu Dateinamen finden Sie auf der MSDN-Website unter Naming a File.

Wenn Sie mithilfe des Zusammenführungstools und der o-Option eine einzelne Assembly für die Site erstellen und der Zusammenführungsprozess Zirkelverweise erzeugt, wird ein Fehler ausgegeben. Es gibt zwei Lösungen für diese Situation:

• Verwenden Sie stattdessen die w-Option, damit die Quelldatei mit dem Zirkelverweis als externer Verweis erhalten bleibt und nicht zusammengeführt wird.

• Trennen Sie die Steuerelemente, die in einen Zirkelverweis verwickelt sind, mithilfe separater Verzeichnisse.

Wenn Sie Assemblys mit inkonsistenten Attributen zusammenführen, stellen Sie anhand der folgenden Richtlinien sicher, dass die Zusammenführung erfolgreich durchgeführt wird.

• Listen Sie inkonsistente Attribute mithilfe der allowattrs-Option auf.

• Verwenden Sie die copyattrs-Optionen, und stellen Sie sicher, dass alle zusammenzuführenden Assemblys übereinstimmende Attribute aufweisen.

• Verwenden Sie die a-Option.

Signieren von Assemblys

Die delaysign-Option und die keyfile-Option ermöglichen, dass Sie mit dem Zusammenführungstool Assemblys mit starken Namen erstellen, ohne dass Sie das Strong Name-Tool (Sn.exe) verwenden. Die delaysign-Option entspricht dem AssemblyDelaySignAttribute-Attribut, und die keyfile-Option entspricht dem AssemblyKeyFileAttribute-Attribut.

Beide Optionen wenden das entsprechende Attribut auf die zusammengeführte Assembly an. Die angewendeten Attribute werden mit einem AttributeUsageAttribute-Attribut gekennzeichnet, für dessen AllowMultiple-Eigenschaft der Wert false festgelegt ist. Wenn Sie daher für Assemblys, die bereits mit einem der Attribute markiert sind, diese Optionen verwenden, schlägt das Zusammenführen fehl.

Beispiele

Durch den folgenden Befehl werden die Assemblys der vorkompilierten Site im Verzeichnis C:\PrecompiledSite zusammengeführt.

Aspnet_merge C:\PrecompiledSite

Durch den folgenden Befehl werden die Assemblys einer vorkompilierten Site im Verzeichnis C:\PrecompiledSite zusammengeführt, und die zusammengeführten Assemblys werden mithilfe der Datei KeyFile.snk signiert. Die zusammengeführte Site verfügt über eine Assembly für jeden vorkompilierten Siteordner.

Aspnet_merge C:\PrecompiledSite -keyfile KeyFile.snk

Durch den folgenden Befehl werden alle Assemblys der vorkompilierten Site im Verzeichnis C:\PrecompiledSite in einer Assembly zusammengeführt, und der resultierenden Assembly wird der Name MyApp.dll zugeordnet. Die zusammengeführte Site verfügt über eine Assembly für den gesamten Inhalt der Websitebenutzeroberfläche.

Aspnet_merge C:\PrecompiledSite -w MyApp.dll

Durch den folgenden Befehl werden alle Assemblys der vorkompilierten Site im Verzeichnis C:\PrecompiledSite in einer Assembly zusammengeführt, und der resultierenden Assembly wird der Name MyApp.dll zugeordnet.

Aspnet_merge C:\PrecompiledSite -o MyApp.dll

Siehe auch

Konzepte

Verzögertes Signieren einer Assembly

Assemblys mit starkem Namen

Referenz

AssemblyKeyFileAttribute

AssemblyKeyNameAttribute

AssemblyDelaySignAttribute

AllowPartiallyTrustedCallersAttribute

.NET Framework-Tools

Strong Name-Tool (Sn.exe)

ASP.NET-Kompilierungstool (Aspnet_compiler.exe)