Anweisungs-XML für Dateipakete
- Aktualisiert2024-09-30
- 10 Minute(n) Lesezeit
Mit Hilfe der von Ihnen erstellten optionalen Anweisungs-XML-Datei werden dem Paketmanager Anweisungen für die benutzerdefinierte Ausführung der Paketinstallation bereitgestellt.
- <targetAttributes>
- <customDirectories>
- <shortcuts>
- <returnCodeConventions>
- <customExecutes>
- <osUninstallEntry>
Geben Sie der Anweisungs-XML-Datei den Namen instructions, lassen Sie die Dateierweiterung weg und fügen Sie sie in das Stammverzeichnis des data-Verzeichnisses eines Dateipakets ein.
Im Folgenden finden Sie ein Beispiel für eine Anweisungsdatei für ein Dateipaket.
<instructions> <targetAttributes readOnly="allReadOnly"/> <customDirectories> <customDirectory name="customDir1" path="D:\subdir"/> <customDirectory name="customDir2" path="\\myserver\subdir"/> </customDirectories> <shortcuts> <shortcut> <destination root="ProgramMenu" path="Test\Shortcut.lnk"> <localizedDestination root="ProgramMenu" path="Test\Verknüpfung.lnk" language="de"/> <localizedDestination root="ProgramMenu" path="Test\Raccourci.lnk" language="fr"/> <localizedDestination root="ProgramMenu" path="Test\ショートカット.lnk" language="ja"/> <localizedDestination root="ProgramMenu" path="Test\바로가기.lnk" language="ko"/> <localizedDestination root="ProgramMenu" path="Test\快捷方式.lnk" language="zh-CN"/> </destination> <target root="Program Files" path="Shortcuts\executable.exe"/> </shortcut> </shortcuts> <customExecutes> <customExecute root="Documents" exeName="executable.exe"/> </customExecutes> </instructions>
<targetAttributes>-Element
Das Element <targetAttributes> enthält optionale Anweisungen zu Speicherorten, in denen der Paketmanager Dateien auf dem Zielsystem installiert.
Das Element <targetAttributes> ist leer. Das heißt, es hat Attribute, enthält jedoch weder Elemente noch Text. Die folgenden Attribute sind enthalten:
Attributname | Typ | Mögliche Werte | Details | Beispiele |
---|---|---|---|---|
readOnly | Enum |
|
|
<targetAttributes readOnly="allReadOnly"/> |
<customDirectories>-Element
Das <customDirectories>-Element bietet eine Liste von Speicherorten für absolute Pfade, unter denen der Paketmanager Dateien auf dem Zielsystem installiert.
Unterelemente von <customDirectories> werden mittels <customDirectory> aufgeführt.
<customDirectory>-Element
Das <customDirectory>-Element definiert einen absoluten Pfad oder Netzwerkpfad, unter dem der Paketmanager Dateien auf dem Zielsystem installiert.
In der Anweisungsdatei können mehrere Instanzen von <customDirectory> vorkommen.
Attributname | Typ | Wert | Beispiele |
---|---|---|---|
name | String |
Für einen Windows-Verzeichnisnamen gültige Zeichen:
|
<customDirectory name="examplename1" path="D:\bin"/> |
path | String | Ein absoluter Pfad oder Netzwerkpfad auf dem Zielsystem | <customDirectory name="examplename2" path="\\servername\sharename\subdir"/> |
<shortcuts>-Element
Das <shortcuts>-Element stellt eine Liste der Verknüpfungen bereit, die der Paketmanager während der Installation erstellt.
Unterelemente von <shortcuts> werden mittels <shortcut> aufgeführt.
<shortcut>-Element
Das <shortcut>-Element definiert eine Verknüpfung, die der Paketmanager während der Installation erstellt.
- <destination>
- <target>
<destination>-Element
Das Element <destination> gibt den Speicherort an, an dem der Paketmanager eine Verknüpfung erzeugen soll.
<destination> ist erforderlich und kann ein oder mehrere optionale Unterelemente des Typs <localizedDestination> haben. Es hat die folgenden Attribute:
Attributname | Typ | Wert | Beispiele |
---|---|---|---|
root | String | Ein unterstütztes Ziel-Stammverzeichnis. Pakete mit einer windows_all-Architektur können keine 64-Bit-spezifischen Ziel-Stammverzeichnisse verwenden, wie z. B. ProgramFiles_64 oder LV2017DIR64. | <destination root="Startup" path="testShortcut.lnk"/> |
path | String | Der dem Ziel-Stammverzeichnis folgende Pfad und Dateiname. Informationen zur Syntax finden Sie im Abschnitt XML-Syntaxregeln für Anführungszeichen. | <destination root="ProgramFiles" path="Shortcuts\test.exe"/> |
<localizedDestination>-Element
Das Element <localizedDestination> gibt einen alternativen lokalisierten Pfad für die Verknüpfungsdatei an, wenn das Dateipaket in einer bestimmten Sprache installiert wird.
<localizedDestination> ist ein leeres Element. Das heißt, es besitzt Attribute, enthält aber weder Elemente noch Textinhalte. Die folgenden Attribute sind enthalten:
Attributname | Typ | Wert | Beispiele |
---|---|---|---|
root | String | Ein unterstütztes Ziel-Stammverzeichnis. Pakete mit windows_all-Architektur können keine 64-Bit-spezifischen Ziel-Stammverzeichnisse wie ProgramFiles_64 oder LV2017DIR64 verwenden. | <localizedDestination root="ProgramMenu"/> |
path | String | Der dem Ziel-Stammverzeichnis folgende Pfad und Dateiname. | <localizedDestination root="ProgramMenu" path="Test\Verknüpfung.lnk" /> |
language | String |
Sprachcode des lokalisierten Pfads. Mögliche Werte:
|
<localizedDestination root="ProgramMenu" path="Test\Verknüpfung.lnk" language="de"/> |
<target>-Element
Das Element <target> gibt den Speicherort der Datei an, für die der Paketmanager eine Verknüpfung erzeugen soll.
Das Element <target> ist leer. Das heißt, es hat Attribute, enthält jedoch weder Elemente noch Text. Es hat die folgenden Attribute:
Attributname | Typ | Wert | Beispiele |
---|---|---|---|
root | String | Ein unterstütztes Ziel-Stammverzeichnis. Pakete mit einer windows_all-Architektur können keine 64-Bit-spezifischen Ziel-Stammverzeichnisse verwenden, wie z. B. ProgramFiles_64 oder LV2017DIR64. | <target root="Startup" path="testShortcut.lnk"/> |
path | String | Der dem Ziel-Stammverzeichnis folgende Pfad und Dateiname. Informationen zur Syntax finden Sie im Abschnitt XML-Syntaxregeln für Anführungszeichen. | <target root="ProgramFiles" path="Shortcuts\test.exe"/> |
arguments | String | Optionale Argumente, die an die Zieldatei übergeben werden. Informationen zur Syntax finden Sie im Abschnitt XML-Syntaxregeln für Anführungszeichen. | <target root="ProgramFiles" path="Shortcuts\test.exe" arguments="--argument1"/> |
<returnCodeConventions>-Element
Das <returnCodeConventions>-Element enthält eine Liste benutzerdefinierter Ausgabecodekonventionen, die der Paketmanager beim Ausführen benutzerdefinierter Aktionen für dieses Paket verwenden kann.
<returnCodeConventions> ist in der Anweisungsdatei optional, kann aber ein oder mehrere <returnCodeConvention>-Unterelemente enthalten.
<returnCodeConvention>-Element
Das <returnCodeConvention>-Element definiert, wie ein Ausgabecode für eine oder mehrere benutzerdefinierte Ausführungen in diesem Paket interpretiert wird.
<returnCodeConvention> kann ein oder mehrere optionale <returnCode>-Unterelemente enthalten. <returnCode>-Regeln werden in der Reihenfolge ausgewertet, in der sie definiert sind.
Attributname | Typ | Wert | Beispiele |
---|---|---|---|
name | String | Ein eindeutiger Name für diese Ausgabecodekonvention. Eine benutzerdefinierte Ausführung in diesem Paket kann diesen Namen im Feld „returnCodeConvention“ verwenden, um sich mit dieser Ausgabecodekonvention zu verknüpfen. | <returnCodeConvention name="alwaysReboot" defaultResult="rebootRequired"/> |
defaultResult | Enum | Zeigt das semantische Ergebnis eines Ausgabecodes an, der keinen bestehenden Regeln für die Zuordnung von Ausgabecode entspricht.
|
<returnCodeConvention name="ignore" defaultResult="success"/> |
<returnCode>-Element
Das <returnCode>-Element definiert eine Ausgabecodezuordnungsregel für sein übergeordnetes Element <returnCodeConvention>.
<returnCode> ist ein leeres Element. Das heißt, es besitzt Attribute, enthält aber weder Elemente noch Textinhalte. Die folgenden Attribute sind enthalten:
Attributname | Typ | Wert | Beispiele |
---|---|---|---|
min | Integer | Gibt die Untergrenze eines Bereichs von Ausgabecodes an, auf den diese Regel zutrifft. Kann nicht mit dem value-Attribut kombiniert werden. | <returnCode min="0" max="1024" result="success"/> |
max | Integer | Gibt die Obergrenze eines Bereichs von Ausgabecodes an, auf den diese Regel zutrifft. Kann nicht mit dem value-Attribut kombiniert werden. | <returnCode min="-50" max="-1" result="success"/> |
value | Integer | Gibt einen einzelnen Ausgabecode an, auf den diese Regel zutrifft. Kann nicht mit den Attributen min oder max kombiniert werden. | <returnCode value="1641" result="rebootRequired"/> |
result | Enum | Gibt das semantische Ergebnis eines Ausgabecodes an, der dieser Regel entspricht. | <returnCode value="3010" result="rebootRequired"/> |
<customExecutes>-Element
Das <customExecutes>-Element enthält eine Liste der benutzerdefinierten Aktionen für den Paketmanager, die an einem Paket ausgeführt werden sollen.
Unterelemente von <customExecutes> werden mittels <customExecute> aufgeführt.
<customExecute>-Element
Das Element <customExecute> definiert eine benutzerdefinierte Aktion, die der Paketmanager am Paket ausführt.
Das Element <customExecute> ist in der Anweisungsdatei optional, Sie können aber so viele Elemente hinzufügen, wie für Ihr Paket benötigt werden. <customExecute> ist ein leeres Element. Das heißt, es besitzt Attribute, enthält aber weder Elemente noch Textinhalte. Die folgenden Attribute sind enthalten:
Attributname | Typ | Erforderlich | Wert | Beschreibung | Beispiele |
---|---|---|---|---|---|
root | String | Ja | Der Pfad zum Stammverzeichnis der ausführbaren Datei. Pakete mit windows_all-Architektur können keine 64-Bit-spezifischen Ziel-Stammverzeichnisse wie ProgramFiles_64 oder LV2017DIR64 verwenden. | Gibt den Pfad zum Stammverzeichnis der ausführbaren Datei an. Ein unterstütztes Ziel-Stammverzeichnis. Unter Ziel-Stammverzeichnisse finden Sie die unterstützten Zielstammverzeichnisse. Hinweis Zum Ausführen einer Anwendung müssen Sie zuerst das Paket installieren, welches die ausführbare Datei enthält. Sie können ein Paket so konfigurieren, dass die ausführbare Datei vorübergehend installiert wird, indem Sie den Pfad zum Ziel-Stammverzeichnis auf NIPkgMgrTempUnique und das Attribut „schedule“ auf post setzen. Der Paketmanager installiert das Paket dann im Verzeichnis NIPkgMgrTempUnique und führt die ausführbare Datei von dort aus aus, bevor Dateien im Verzeichnis gelöscht werden. |
<customExecute root="Documents" exeName="executable.exe"/> |
exeName | String | Ja | Der Dateiname der ausführbaren Datei. | Gibt den Dateinamen der ausführbaren Datei an. Diese Angabe kann einen zum Stammverzeichnis relativ angegebenen Pfad enthalten. Informationen zur Syntax finden Sie im Abschnitt XML-Syntaxregeln für Anführungszeichen. |
<customExecute root="ProgramData" exeName="actions\executable.exe"/> |
arguments | String | Nein | Kommandozeilenargumente, die an die ausführbare Datei übergeben werden. | Gibt Kommandozeilenargumente an, die der Paketmanager an die ausführbare Datei übergeben soll. Der Wert ist formatiert. Sie können ein unterstütztes Ziel-Stammverzeichnis und/oder die folgenden Argumente angeben: Hinweis Bei allen Argumenten muss die Groß-/Kleinschreibung beachtet werden. Informationen zur Syntax finden Sie im Abschnitt XML-Syntaxregeln für Anführungszeichen. |
|
step | Enum | Nein |
|
Gibt den Arbeitsschritt an, in dem der Paketmanager die ausführbare Datei startet.
Hinweis Wenn Sie während der Entwicklung eines Pakets den Wert von step auf uninstall setzen, sollten Sie den Wert von ignoreErrors auf y setzen, um zu vermeiden, dass der Paketmanager ein Paket nicht aus dem Zielsystem entfernen kann. |
<customExecute step="uninstall" root="ProgramData" ignoreErros="y" exeName="actions\executable.exe"/> |
schedule | Enum | Nein |
|
Gibt den relativen Punkt innerhalb der Arbeitsschritte an, an dem die ausführbare Datei gestartet werden soll. Wenn Sie dieses Attribut weglassen, arbeitet der Paketmanager mit der Standardeinstellung. |
<customExecute step="install" schedule="post" root="ProgramData" exeName="executable.exe"/> |
wait | Boolesch | Nein |
|
Gibt an, ob die benutzerdefinierte Aktion synchron oder asynchron ist. Synchron bedeutet, dass der Paketmanager das Ende der Aktion abwarten soll, bevor er fortfährt. Asynchron bedeutet, dass der Paketmanager das Ende der Aktion nicht abwarten muss. Wenn Sie dieses Attribut weglassen, arbeitet der Paketmanager mit der Standardeinstellung. |
<customExecute root="ProgramData" exeName="executable.exe" wait="n"/> |
ignoreErrors | Boolesch | Nein |
|
Gibt an, ob der Paketmanager einen Fehler melden soll, wenn sich die ausführbare Datei nicht starten lässt oder einen anderen Wert als 0 ausgibt.
|
<customExecute root="ProgramData" exeName="executable.exe" wait="y" ignoreErrors="y"/> |
hideConsoleWindow | Boolesch | Nein |
|
Gibt an, ob das Konsolenfenster für Konsolenanwendungen ausgeblendet werden soll.
|
<customExecute root="ProgramData" exeName="executable.exe" hideConsoleWindow="y"/> |
ignoreLaunchErrors | Boolesch | Nein |
|
Gibt an, ob der Paketmanager einen Fehler melden soll, wenn die ausführbare Datei fehlt oder nicht ausführbar ist. Dieses Attribut kann nicht zusammen mit ignoreErrors verwendet werden. | <customExecute root="ProgramData" exeName="executable.exe" ignoreLaunchErrors="y"/> |
returnCodeConvention | String | Nein | Muss mit dem Namen einer vordefinierten Konvention oder eines in diesem Paket definierten <returnCodeConvention>-Elements übereinstimmen. Folgende vordefinierte Konventionen sind verfügbar:
|
Gibt an, wie die Ausgabecodes der ausführbaren Datei interpretiert werden sollen.
|
<customExecute root="ProgramData" exeName="executable.exe" returnCodeConvention="installer"/> |
Funktionsweise von ausführbaren Dateien die als "Postall" ausgeführt werden sollen
Für Anweisungsdateien, in denen ein <customExecute>-Element enthalten ist, wobei schedule="postall", verfügt der Paketmanager über bestimmte Funktionsweisen, die sich auf die Paketinstallation auswirken können.
Der postall-Wert weist den Paketmanager an, die ausführbare Datei zu starten, nachdem die Schritte für das Installieren, Neuinstallieren und/oder Entfernen für alle Pakete abgeschlossen sind.
- Der Paketmanager führt ausführbare postall-Dateien in der angegebenen Reihenfolge der Paketinstallation aus. Abhängige Komponenten dabei werden zuerst installiert.
- Wenn nur die Installation einer Datei fehlschlägt, die als postall ausgeführt wird, wird das Paket als installiert angesehen.
- Wenn mehrere Pakete mit Dateien vorhanden sind, die als postall ausgeführt werden, werden die restlichen ausführbaren Dateien nicht gestartet, wenn die Installation einer der postall-Dateien fehlschlägt. Pakete gelten als installiert, wenn keine anderen Fehler während der Installation aufgetreten sind.
- Wenn die Installation eines Pakets fehlschlägt, entweder durch einen MSI-Fehler oder durch einen Fehler in einer Datei, die als pre oder post ausgeführt werden soll, wird im Paketmanager eine Fehlermeldung darüber angezeigt, dass das Paket nicht installiert werden konnte. Als nächstes werden alle ausführbaren Dateien von Paketen ausgeführt, die bis zu dem Punkt installiert wurden, an dem die Installation fehlgeschlagen ist. Der Paketmanager ignoriert das beschädigte installierte Paket und führt die postall-Anwendungen des defekten Pakets nicht aus. Alle vor dem Auftreten des Fehlers installierten Pakete bleiben installiert, und der Paketmanager führt die postall-Anwendungen dieser Pakete aus.
XML-Syntaxregeln für Anführungszeichen
Lesen Sie die XML-Syntaxregeln für Anführungszeichen, um der Microsoft-Syntax für bedingte Anweisungen zu entsprechen und um Pfade mit Leerzeichen in Anführungszeichen zu setzen.
Die Syntax für bedingte Anweisungen von Microsoft sieht vor, dass literaler Text in Anführungszeichen zu setzen ist. Die Syntax für Anweisungs-XML bietet zwei Möglichkeiten zur Einhaltung dieser Vorschrift:
- Ein XML-String wird durch Apostrophe (einfache Anführungszeichen) abgegrenzt. So können reguläre Anführungszeichen innerhalb des Strings vorkommen. Beispiel:
<customExecute condition='IEDETECTED~="Yes" AND VersionNT64 = 601 AND NIRUNNINGINSILENTMODE'/>
- Verwenden Sie das XML-Escape-Zeichen für Anführungszeichen, ", um den literalen Text im XML-String abzugrenzen. Mit dem XML-Escape-Zeichen können Sie Anführungszeichen oder Apostrophe verwenden, um XML-Strings abzugrenzen. Beispiel:
<customExecute condition="IEDETECTED~="Yes" AND VersionNT64 = 601 AND NIRUNNINGINSILENTMODE"/>
Pfade, die Leerzeichen enthalten, müssen in Anführungszeichen gesetzt werden. Einfache Anführungszeichen sind in Pfaden unzulässig.
- Verwenden Sie das XML-Escape-Zeichen für Anführungszeichen, ", um den Pfad im XML-String abzugrenzen. Beispiel:
<customExecute exeName=""VC RunTime Installer.exe"" arguments="/q /norestart" inPackage="y"/>
Beispiele für benutzerdefinierte Ausführung
Folgendes ruft ein PowerShell-Skript auf (welches das Paket potenziell installiert hat). Nach der Installation werden zwei Argumente übergeben.
<customExecute root="BootVolume" exeName="Windows\System32\WindowsPowerShell\v1.0\powershell.exe" arguments="-File "%ProgramData%\My App Name\MyInstallScript.ps1" "argument 1" "argument 2"" step="install" schedule="post" wait="y" ignoreErrors="n" hideConsoleWindow="y" />
<osUninstallEntry>-Element
Das Element <osUninstallEntry> enthält optionale Anweisungen für die Anzeige des Pakets in der Schnittstelle Programme hinzufügen/entfernen.
<osUninstallEntry> ist ein leeres Element. Das heißt, es besitzt Attribute, enthält aber weder Elemente noch Textinhalte. <osUninstallEntry> besitzt die folgenden Attribute:
Attributname | Typ | Mögliche Werte | Details | Beispiele |
---|---|---|---|---|
ux | Enum |
|
Bei Paketen von Drittanbietern ermöglicht der Wert oem die Anzeige des Pakets als erstklassiges Objekt in der Liste der installierten Anwendungen. Bei Änderungen und Deinstallationen bezieht sich die Schnittstelle „Programme hinzufügen/entfernen“ nur auf das angegebene Paket. | <osUninstallEntry ux="oem"/> |
Verwandte Inhalte
- Stammverzeichnisse auf Zielsystemen für Dateipakete
Beim Erzeugen von Paketen enthalten die Verzeichnisse, die Sie innerhalb des Datenordners erstellen, Angaben darüber, wo die Dateien vom Paketmanager installiert werden sollen.