Tool zum Generieren und Bearbeiten von Manifesten (Mage.exe)

  • Artikel

Aktualisiert: November 2007

Bei dem Tool zum Generieren und Bearbeiten von Manifesten (Mage.exe) handelt es sich um ein Befehlszeilentool, das Sie beim Erstellen und Bearbeiten von Anwendungs- und Bereitstellungsmanifesten unterstützt. Als Befehlszeilentool kann Mage.exe von Batchskripten und anderen Windows-basierten Anwendungen ausgeführt werden, z. B. ASP.NET-Anwendungen.

Sie können auch MageUI.exe verwenden, eine grafische Anwendung, statt Mage.exe. Weitere Informationen finden Sie unter Tool zum Generieren und Bearbeiten von Manifesten, grafischer Client (MageUI.exe).

Mage.exe und MageUI.exe sind an verschiedenen Speicherorten verfügbar, einschließlich:

  • Das .NET Framework 2.0 SDK. Das .NET Framework 2.0 SDK ist als Komponente des Visual Studio 2005-Setups oder als Download bei Microsoft verfügbar.

  • Das Windows SDK für Windows Vista. Das Windows SDK für Windows Vista kann aus dem Microsoft Download Center heruntergeladen werden.

  • Visual Studio 2008. Neuere Versionen von Mage.exe und MageUI.exe sind als Komponente des Visual Studio 2008-Setups eingeschlossen.

Mage [commands] [commandOptions]

Parameter

In der folgenden Tabelle werden die von Mage.exe unterstützten Befehle angezeigt. Weitere Informationen zu den Optionen, die diese Befehle unterstützen, finden Sie unter Neue und aktualisierte Befehlsoptionen und Sign-Befehlsoptionen.

Befehl

Beschreibung

-cc, ClearApplicationCache

Löscht den heruntergeladenen Anwendungscache aller Anwendungen, die nur online ausgeführt werden.

-n, -New fileType [newOptions]

Erstellt eine neue Datei des entsprechenden Typs. Gültige Typen sind:

  • Deployment: Erstellt ein neues Bereitstellungsmanifest.

  • Application: Erstellt ein neues Anwendungsmanifest.

Wenn Sie mit diesem Befehl keine weiteren Parameter angeben, wird eine Datei des entsprechenden Typs mit den zugehörigen Standardtags und Attributwerten erstellt.

Verwenden Sie die –ToFile-Option (siehe folgende Tabelle), um den Dateinamen und Pfad der neuen Datei anzugeben.

Erstellen Sie mithilfe der Option –FromDirectory (siehe nachfolgende Tabelle) ein Anwendungsmanifest mit allen Assemblys für eine dem <dependency>-Abschnitt des Manifests hinzugefügte Anwendung.

-u, -Update [filePath] [updateOptions]

Nimmt mindestens eine Änderung an einer Manifestdatei vor. Es ist nicht erforderlich, den Typ der bearbeiteten Datei anzugeben. Mage.exe analysiert die Datei mithilfe von Heuristiken und ermittelt, ob es sich um ein Bereitstellungsmanifest oder ein Anwendungsmanifest handelt.

Wenn Sie bereits eine Datei mit einem Zertifikat signiert haben, entfernt -Update den Hauptsignaturblock. Der Grund hierfür liegt darin, dass die Hauptsignatur einen Hash für die Datei enthält, und durch Änderung der Datei wird der Hash ungültig.

Verwenden Sie die –ToFile-Option (siehe folgende Tabelle), um einen neuen Dateinamen und Pfad anzugeben, anstatt die vorhandene Datei zu überschreiben.

-s, -Sign[signOptions]

Verwendet ein Zertifikat zum Signieren einer Datei. Signaturen werden als XML-Elemente in die Dateien eingefügt.

-h, -?, -Help[verbose]

Beschreibt alle verfügbare Befehle und die zugehörigen Optionen. Geben Sie verbose an, um ausführliche Hilfe aufzurufen.

Neue und aktualisierte Befehlsoptionen

In der folgenden Tabelle werden die Optionen aufgeführt, die von dem –New-Befehl und dem –Update-Befehl unterstützt werden.

Optionen

Standardwert

Gilt für

Beschreibung

-appc, -AppCodeBasemanifestReference

Bereitstellungsmanifeste.

Fügt einen URL oder einen Dateipfadverweis in die Anwendungsmanifestdatei ein. Bei der Datei muss es sich um den vollständigen Pfad zum Anwendungsmanifest handeln.

-appm, -AppManifestmanifestPath

Bereitstellungsmanifeste.

Fügt einen Verweis auf das Anwendungsmanifest einer Bereitstellung in das Bereitstellungsmanifest ein.

Die von manifestPath angegebene Datei muss vorhanden sein, andernfalls gibt Mage.exe einen Fehler aus. Wenn die Datei, auf die von manifestPath verwiesen wird, kein Anwendungsmanifest ist, gibt Mage.exe einen Fehler aus.

-cf, -CertFilefilePath

Alle Dateitypen.

Gibt den Speicherort eines digitalen Zertifikats zum Signieren eines Manifests an. Diese Option kann in Verbindung mit der Option –Password verwendet werden, wenn für das Zertifikat ein Kennwort erforderlich ist.

-ch, -CertHashhashSignature

Alle Dateitypen.

Der Hash eines im persönlichen Zertifikatsspeicher des Clientcomputers gespeicherten Zertifikats. Dieser entspricht der Zeichenfolge für den Daumenabdruck eines digitalen Zertifikats, das in der Windows-Zertifikatskonsole angezeigt wird.

hashSignature kann groß- oder kleingeschrieben und als einzelne Zeichenfolge oder so angegeben werden, dass die einzelnen Oktette des Daumenabdrucks durch Leerzeichen getrennt sind und der vollständige Daumenabdruck in Anführungszeichen eingeschlossen ist.

-fd, -FromDirectorydirectoryPath

Anwendungsmanifeste.

Füllt das Anwendungsmanifest mit Beschreibungen aller Assemblys und Dateien im directoryPath, wobei directoryPath das Verzeichnis ist, das die bereitzustellenden Anwendung enthält. Bei jeder Datei im Verzeichnis legt Mage.exe fest, ob es sich bei der Datei um eine Assembly oder eine statische Datei handelt. Bei einer Assembly wird der Anwendung ein <dependency>-Tag und ein installFrom-Attribut mit dem Assemblynamen, der CodeBase und der Version hinzugefügt. Bei einer statischen Datei wird ein <file>-Tag hinzugefügt. Mage.exe verwendet zudem einige einfache Heuristiken zum Ermitteln der zentralen ausführbaren Datei für die Anwendung und kennzeichnet diese als Einstiegspunkt der ClickOnce-Anwendung im Manifest.

Mage.exe markiert nie automatisch eine Datei als "Daten"-Datei. Sie müssen dies manuell durchführen. Weitere Informationen hierzu finden Sie unter Gewusst wie: Einschließen einer Datendatei in eine ClickOnce-Anwendung.

Mage.exe generiert zudem einen Hash für jede Datei auf Grundlage ihrer Größe. ClickOnce verwendet diese Hashes, um sicherzustellen, dass die Dateien der Bereitstellung seit Erstellung des Manifests nicht manipuliert wurden. Falls sich Dateien in der Bereitstellung ändern, können Sie Mage.exe mit dem Befehl –Update und der Option –FromDirectory ausführen. Auf diese Weise werden die Hashes und die Assemblyversionen aller Dateien, auf die verwiesen wird, aktualisiert.

-FromDirectory schließt alle Dateien in allen Unterverzeichnissen ein, die im directoryPath gefunden werden.

Wenn Sie –FromDirectory mit dem Befehl –Update verwenden, entfernt Mage.exe alle Dateien im Anwendungsmanifest, die im Verzeichnis nicht mehr vorhanden sind.

-i, -InstallwillInstall

true

Bereitstellungsmanifeste.

Gibt an, ob die ClickOnce-Anwendung auf dem lokalen Computer installiert oder ob sie über das Web ausgeführt werden soll. Wenn eine Anwendung installiert wird, wird diese im Startmenü von Windows angezeigt. Gültige Werte sind "true" oder "t" und "false" oder "f".

Wenn Sie die –MinVersion-Option angeben und ein Benutzer eine ältere Version als -MinVersion installiert hat, wird unabhängig von dem von Ihnen an -Install übergebenen Wert die Installation der Anwendung erzwungen.

Diese Option kann nicht mit der Option -BrowserHosted verwendet werden. Wenn Sie beide Optionen für das gleiche Manifest angeben, wird ein Fehler ausgelöst.

-mv, -MinVersion [version]

Die im ClickOnce-Bereitstellungsmanifest aufgeführte Version, wie im -Version-Flag angegeben.

Bereitstellungsmanifeste.

Die Version dieser Anwendung, die ein Benutzer mindestens ausführen muss. Dieses Flag macht die genannte Version der Anwendung zu einem erforderlichen Update. Wenn Sie eine Version Ihres Produkts mit einer wichtigen Änderung oder einer Korrektur eines schwerwiegenden Sicherheitsmangels freigeben, können Sie mithilfe dieses Flags angeben, dass die Aktualisierung installiert werden muss und der Benutzer keine früheren Versionen mehr ausführen kann.

version weist dieselbe Semantik wie das Argument für das -Version-Flag auf.

-n, -NamenameString

Bereitstellen

Alle Dateitypen.

Der Name, der zum Angeben der Anwendung verwendet wird. ClickOnce verwendet diesen Namen zum Identifizieren der Anwendung im Startmenü (wenn die Anwendung so konfiguriert ist, dass sie sich selbst installiert) und in Dialogfeldern zum Ausweiten von Berechtigungen.

-pwd, -Passwordpasswd

Alle Dateitypen.

Das Kennwort, das zum Signieren eines Manifests mit einem digitalen Zertifikat verwendet wird. Muss zusammen mit der Option –CertFile verwendet werden.

-p, ProcessorprocessorValue

msil

Anwendungsmanifeste.

Bereitstellungsmanifeste.

Die Mikroprozessorarchitektur, auf der diese Verteilung ausgeführt wird. Dieser Wert muss angegeben werden, wenn Sie eine oder mehrere Installationen vorbereiten, deren Assemblys für einen bestimmten Mikroprozessor vorkompiliert wurden. Gültige Werte sind msil, x86, ia64 und amd64. msil steht für Microsoft Intermediate Language. Das bedeutet, dass alle Assemblys plattformunabhängig sind und die Common Language Runtime (CLR) eine Just-In-Time-Kompilierung durchführt, wenn die Anwendung zum ersten Mal ausgeführt wird.

-pu,-ProviderUrlurl

Bereitstellungsmanifeste.

Gibt den URL an, den ClickOnce auf Anwendungsaktualisierungen überprüft.

-pub, -PublisherpublisherName

Anwendungsmanifeste.

Bereitstellungsmanifeste.

Neu in .NET Framework 3.5.

Fügt den Herausgebernamen zum Beschreibungselement des Bereitstellungs- oder Anwendungsmanifests hinzu. Bei Verwendung mit einem Anwendungsmanifest muss -UseManifestForTrust mit dem Wert "true" oder "t" angegeben werden. Andernfalls verursacht dieser Parameter einen Fehler.

-ti, -TimestampUriuri

Anwendungsmanifeste.

Bereitstellungsmanifeste.

Der URL eines digitalen timestamping-Diensts. Der Zeitstempel verhindert, dass Sie ein Manifest neu signieren müssen, wenn das digitale Zertifikat abläuft, bevor Sie die nächste Version der Anwendung bereitstellen. Derzeit unterstützt nur Verisign den timestamping-Dienst. Der als Argument angegebene URI muss "http://timestamp.verisign.com/scripts/timstamp.dll" lauten.

-tr, -TrustLevellevel

Intranet

Anwendungsmanifeste.

Die Vertrauensebene, die der Anwendung auf Clientcomputern gewährt wird. Zu den gültigen Werten zählen "Internet", "Intranet" und "FullTrust".

-t, -ToFilefilePath

  • Neu:

  • Bereitstellung: deploy.application

  • Anwendung: application.exe.manifest

  • Aktualisieren:

  • Die Eingabedatei.

Alle Dateitypen.

Gibt den Ausgabepfad der Datei an, die erstellt oder geändert wurde.

Wenn –ToFile bei Verwendung von –New nicht angegeben wird, wird die Ausgabe in das aktuelle Arbeitsverzeichnis geschrieben. Wenn –ToFile bei Verwendung von –Update nicht angegeben wird, schreibt Mage.exe die Datei zurück in die Eingabedatei.

-u, -UseManifestForTrustwillUseForTrust

false

Anwendungsmanifeste.

Neu in .NET Framework 3.5.

Gibt an, ob für Entscheidungen über die Vertrauenswürdigkeit die digitale Signatur des Anwendungsmanifests verwendet wird, wenn die Anwendung auf dem Client ausgeführt wird. Wenn Sie "true" oder "t" angeben, wird das Anwendungsmanifest für Entscheidungen über die Vertrauenswürdigkeit verwendet. Bei Angabe von "false" oder "f" wird die Signatur des Bereitstellungsmanifests verwendet.

-v, -VersionversionNumber

1.0.0.0

Anwendungsmanifeste.

Bereitstellungsmanifeste.

Die Version der Bereitstellung. Das Argument muss eine gültige Versionszeichenfolge im Format "N.N.N.N" sein, wobei "N" eine 32-Bit-Ganzzahl ohne Vorzeichen sein muss.

-wpf, -WPFBrowserApp isWPFApp

false

Anwendungsmanifeste.

Bereitstellungsmanifeste.

Neu in .NET Framework 3.5.

Verwenden Sie diesen Flag nur für Windows Presentation Foundation-Anwendungen (WPF), die in Internet Explorer gehostet werden, nicht für eigenständige EXE-Dateien. Gültige Werte sind "true" oder "t" und "false" oder "f".

Fügt für Anwendungsmanifeste das hostInBrowser-Attribut unter dem entryPoint-Element des Anwendungsmanifests ein.

Legt für Bereitstellungsmanifeste für das install-Attribut im deployment-Element den Wert "false" fest und speichert das Bereitstellungsmanifest mit der Erweiterung .xbap. Wenn Sie dieses Argument zusammen mit dem -Install-Argument angeben, wird ein Fehler ausgelöst, da die browserbasierte Anwendung keine installierte Offlineanwendung sein darf.

Sign-Befehlsoptionen

In der folgenden Tabelle werden die Optionen angezeigt, die vom –Sign-Befehl unterstützt werden und für alle Typen der Dateien gültig sind.

Optionen

Beschreibung

-cf, -CertFilefilePath

Gibt den Speicherort eines digitalen Zertifikats zum Signieren eines Manifests an. Diese Option kann zusammen mit der –Password-Option verwendet werden.

-ch, -CertHashhashSignature

Der Hash eines im persönlichen Zertifikatsspeicher des Clientcomputers gespeicherten Zertifikats. Dieser entspricht der Eigenschaft für den Daumenabdruck eines digitalen Zertifikats, das in der Windows-Zertifikatskonsole angezeigt wird.

hashSignature kann groß- oder kleingeschrieben und als einzelne Zeichenfolge oder so angegeben werden, dass die einzelnen Oktette des Daumenabdrucks durch Leerzeichen getrennt sind und der vollständige Daumenabdruck in Anführungszeichen eingeschlossen ist.

-p, -Passwordpasswd

Das Kennwort, das zum Signieren eines Manifests mit einem digitalen Zertifikat verwendet wird. Muss zusammen mit der Option –CertFile verwendet werden.

-t, -ToFilefilePath

Gibt den Ausgabepfad der Datei an, die erstellt oder geändert wurde.

Hinweise

Bei allen Argumenten für Mage.exe wird zwischen Groß- und Kleinschreibung unterschieden. Befehlen und Optionen kann ein Bindestrich (-) oder ein Schrägstrich (/) als Präfix vorangestellt werden.

Alle mit dem –Sign-Befehl verwendeten Argumente können jederzeit mit dem –New-Befehl oder dem –Update-Befehl verwendet werden. Folgende Befehle sind gleichwertig.

mage –Sign c:\HelloWorldDeployment\HelloWorld.deploy –CertFile cert.pfx
mage –Update c:\HelloWorldDeployment\HelloWorld.deploy –CertFile cert.pfx

Das Signieren sollte zum Schluss erfolgen, da ein signiertes Dokument einen Hash der Datei verwendet, um zu überprüfen, ob die Signatur für das Dokument gültig ist. Wenn Sie Änderungen an einer signierten Datei vornehmen, müssen Sie sie erneut signieren. Wenn Sie ein Dokument signieren, das bereits signiert wurde, ersetzt Mage.exe die alte Signatur durch die neue Signatur.

Wenn Sie ein Bereitstellungsmanifest mithilfe der Option –AppManifest auffüllen, geht Mage.exe davon aus, dass sich das Anwendungsmanifest im selben Verzeichnis wie das Bereitstellungsmanifest befindet, und zwar in einem Unterverzeichnis, das nach der aktuellen Bereitstellungsversion benannt ist. Das Bereitstellungsfest wird dann entsprechend konfiguriert. Wenn sich das Anwendungsmanifest in einem anderen Verzeichnis befindet, verwenden Sie die Option –AppCodeBase, um das andere Verzeichnis festzulegen.

Das Bereitstellungs- und das Anwendungsmanifest müssen signiert werden, bevor Sie die Anwendung bereitstellen. Anweisungen zum Signieren von Manifesten finden Sie unter Überblick über die Bereitstellung vertrauenswürdiger Anwendungen.

Die Option –TrustLevel für Anwendungsmanifeste beschreibt den Berechtigungssatz, der für eine Anwendung erforderlich ist, damit sie auf dem Clientcomputer ausgeführt wird. Standardmäßig wird Anwendungen auf Grundlage der Zone, in der sich der zugehörige URL befindet, eine Vertrauensebene zugewiesen. Anwendungen, die über ein Unternehmensnetzwerk bereitgestellt werden, werden i. d. R. in der Intranetzone platziert. Anwendungen, die über das Internet bereitgestellt werden, werden normalerweise in der Internetzone platziert. Beide Sicherheitszonen legen Einschränkungen für den Zugriff der Anwendung auf lokale Ressourcen fest, wobei die Intranetzone etwas flexibler ist als die Internetzone. Die FullTrust-Zone gewährt Anwendungen den vollständigen Zugriff auf die lokalen Ressourcen eines Computers. Wenn Sie mithilfe der Option –TrustLevel eine Anwendung in dieser Zone platzieren, fordert die Trust-Manager-Komponente der CLR den Benutzer auf, anzugeben, ob diese höhere Vertrauensebene gewährt werden soll. Bei Bereitstellung der Anwendung über ein Unternehmensnetzwerk, können Sie die Vertrauensebene der Anwendung mithilfe der Bereitstellung vertrauenswürdiger Anwendungen erhöhen, ohne dazu den Benutzer auffordern zu müssen.

Anwendungsmanifeste unterstützen auch benutzerdefinierte Trust-Abschnitte. Auf diese Weise kann die Anwendung das Sicherheitsprinzip der geringsten Berechtigung einhalten, da Sie das Manifest so konfigurieren können, dass nur genau die Berechtigungen angefordert werden, die zum Ausführen der Anwendung erforderlich sind. Mage.exe bietet keine direkte Unterstützung für das Hinzufügen eines benutzerdefinierten Trust-Abschnitts. Sie können einen solchen Abschnitt mit einem Texteditor, mit einem XML-Parser oder mit dem grafischen Tool MageGUI.exe hinzufügen. Weitere Informationen zum Hinzufügen benutzerdefinierter Trust-Abschnitte mit MageGUI.exe finden Sie unter Tool zum Generieren und Bearbeiten von Manifesten, grafischer Client (MageUI.exe).

Beispiele

Im folgenden Beispiel wird die Benutzeroberfläche von Mage (MageUI.Exe) geöffnet.

mage

Die folgenden Beispiele erstellen ein Standardbereitstellungsmanifest und ein Standardanwendungsmanifest. Diese Dateien werden alle im aktuellen Arbeitsverzeichnis unter den Namen deploy.application bzw. application.exe.manifest erstellt.

mage –New Deployment
mage –New Application
mage –New TrustLicense

Im folgenden Beispiel wird ein mit allen Assemblys und Ressourcendateien aus dem HelloWorld-Anwendungsverzeichnis aufgefülltes Anwendungsmanifest erstellt.

mage –New Application –FromDirectory \bin -Version 1.0.0.0

Im folgenden Beispiel wird das vorherige Beispiel fortgesetzt, indem der Bereitstellungsname und der Zielmikroprozessor angegeben werden. Zudem gibt es einen URL an, unter dem ClickOnce nach Updates sucht.

mage –New Application –FromDirectory \bin -Name "Hello, World! Application" –Version 1.0.0.0 –Processor "x86" –ProviderUrl http://internalserver/HelloWorld/

Das folgende Beispiel veranschaulicht, wie Sie ein Manifestpaar für die Bereitstellung einer WPF-Anwendung erstellen, die in Internet Explorer gehostet wird.

mage –New Application –FromDirectory \bin -Version 1.0.0.0 -WPFBrowserApp true
mage -New Deployment -AppManifest 1.0.0.0\application.manifest -WPFBrowserApp true

Im folgenden Beispiel wird ein Bereitstellungsmanifest mit Informationen aus einem Anwendungsmanifest aktualisiert. Dann wird die CodeBase für den Speicherort des Anwendungsmanifests festgelegt.

mage –Update HelloWorld.deploy –AppManifest 1.0.0.0\application.manifest –AppCodeBase http://internalserver/HelloWorld.deploy

Im folgenden Beispiel wird das Bereitstellungsmanifest so bearbeitet, dass eine Aktualisierung der installierten Version des Benutzers erzwungen wird.

mage –Update c:\HelloWorldDeployment\HelloWorld.deploy –MinVersion 1.1.0.0

Im folgenden Beispiel wird das Bereitstellungsmanifest angewiesen, das Anwendungsmanifest aus einem anderen Verzeichnis abzurufen.

mage –Update HelloWorld.deploy –AppCodeBase http://anotherserver/HelloWorld/1.1.0.0/

Im folgenden Beispiel wird ein vorhandenes Bereitstellungsmanifest mithilfe eines digitalen Zertifikats im aktuellen Arbeitsverzeichnis signiert.

mage –Sign deploy.application –CertFile cert.pfx –Password <passwd>

Siehe auch

Aufgaben

Exemplarische Vorgehensweise: Manuelles Bereitstellen einer ClickOnce-Anwendung

Konzepte

Überblick über die Bereitstellung vertrauenswürdiger Anwendungen

Referenz

Tool zum Generieren und Bearbeiten von Manifesten, grafischer Client (MageUI.exe)

SDK-Eingabeaufforderung