Le fichier Instructions XML facultatif que vous créez fournit au Gestionnaire de paquets des instructions pour l'exécution personnalisée de l'installation du paquet.

Le fichier Instructions XML est composé d'un élément <instructions> racine et de plusieurs éléments enfants. Chaque élément enfant est facultatif.
  • <targetAttributes>
  • <customDirectories>
  • <shortcuts>
  • <returnCodeConventions>
  • <customExecutes>
  • <osUninstallEntry>

Nommez le fichier Instructions XML instructions, omettez l'extension de fichier et placez-le à la racine du répertoire data d'un paquet de fichiers.

Le texte suivant est un exemple de fichier d'instructions pour un Paquet de fichiers. 

<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>

Élément <targetAttributes>

L'élément <targetAttributes> fournit des instructions facultatives concernant les emplacements où le Gestionnaire de paquets installe des fichiers sur le système cible.

<targetAttributes> est un élément vide, ce qui signifie qu'il a des attributs, mais qu'il ne contient pas d'élément ou de contenu texte. Il a les attributs suivants :

Nom de l'attribut Type Valeurs possibles Détails Exemples
readOnly Énum
  • allWritable — (par défaut) Permet l'installation en écriture de tous les fichiers de paquets indépendamment de la valeur d'attribut en lecture seule du fichier source d'origine.
  • allReadOnly — Permet l'installation en lecture seule de tous les fichiers de paquets indépendamment de la valeur de l'attribut lecture seule du fichier source d'origine.
  • keepSource — Garde la valeur de l'attribut lecture seule du fichier source d'origine lors de l'installation.
    • Déclare au Gestionnaire de paquets s'il faut permettre l'installation de tous les fichiers en lecture seule, en écriture ou garder la valeur d'attribut en lecture seule à partir du fichier source d'origine.
    • La valeur par défaut est allWritable lorsque vous ne déclarez pas un attribut readOnly ou n'incluez pas un fichier d'instructions.
    		<targetAttributes readOnly="allReadOnly"/>

    Élément <customDirectories>

    L'élément <customDirectories> fournit une liste d'emplacements de chemins absolus vers lesquels le Gestionnaire de paquets installe les fichiers sur le système cible.

    <customDirectories> contient l'élément enfant <customDirectory>.

    Élément <customDirectory>

    L'élément <customDirectory> définit un chemin absolu ou réseau vers lequel le Gestionnaire de paquets installe les fichiers sur le système cible.

    Vous pouvez avoir plusieurs instances de <customDirectory> dans le fichier d'instructions.

    Nom de l'attribut Type Valeur Exemples
    name Chaîne
    Caractères valides pour un nom de répertoire Windows :
    • Ne comporter que des lettres minuscules (a-z), des chiffres (0-9), des signes plus (+) et moins (-) et des points (.)
    • Commencer par un caractère alphanumérique
    • Avoir une longueur minimale de deux caractères
    • Avoir une longueur maximale de 58 caractères
    Une erreur se produit si l'attribut de nom :
    • Est une racine cible existante
    • Commence par ni_
    • Contient des caractères non valides
    		 <customDirectory name="examplename1" path="D:\bin"/>
    path Chaîne Un chemin absolu ou réseau sur le système cible <customDirectory name="examplename2" path="\\servername\sharename\subdir"/>

    Élément <shortcuts>

    L'élément <shortcuts> fournit une liste de raccourcis que le Gestionnaire de paquets crée lors de l'installation.

    <shortcuts> contient l'élément enfant <shortcut>.

    Élément <shortcut>

    L'élément <shortcut> définit un raccourci que le Gestionnaire de paquets crée lors de l'installation.

    L'élément <shortcut> est facultatif dans le fichier Instructions, mais vous pouvez en inclure autant que nécessaire pour votre paquet. <shortcut> contient deux éléments enfants :
    • <destination>
    • <target>

    Élément <destination>

    L'élément <destination> spécifie l'emplacement où le Gestionnaire de paquets crée un fichier raccourci.

    <destination> est requis et peut avoir un ou plusieurs éléments enfants <localizedDestination> facultatifs. Il a les attributs suivants :

    Nom de l'attribut Type Valeur Exemples
    root Chaîne Une racine cible prise en charge. Les paquets présentant une architecture windows_all ne peuvent pas utiliser de racines cibles spécifiques 64 bits, comme ProgramFiles_64 ou LV2017DIR64. <destination root="Startup" path="testShortcut.lnk"/>
    path Chaîne Chemin et nom du fichier ajoutés à la cible racine. Reportez-vous à la section Règles de syntaxe XML pour les guillemets pour connaître les spécifications de syntaxe. <destination root="ProgramFiles" path="Shortcuts\test.exe"/>

    Élément <localizedDestination>

    L'élément <localizedDestination> spécifie un autre chemin localisé à utiliser pour le fichier local lors de l'installation du paquet de fichiers dans une langue donnée.

    <localizedDestination> est un élément vide, ce qui signifie qu'il a des attributs, mais qu'il ne contient pas d'élément ou de contenu texte. Il a les attributs suivants :

    Nom de l'attribut Type Valeur Exemples
    root Chaîne Une racine cible prise en charge. Les paquets présentant une architecture windows_all ne peuvent pas utiliser de racines cibles spécifiques 64 bits, comme ProgramFiles_64 ou LV2017DIR64. <localizedDestination root="ProgramMenu"/>
    path Chaîne Chemin et nom du fichier ajoutés à la cible racine. <localizedDestination root="ProgramMenu" path="Test\Verknüpfung.lnk" />
    language Chaîne

    Code de langage du chemin localisé. Valeurs possibles :

    • de
    • fr
    • ja
    • ko
    • zh-CN
    		<localizedDestination root="ProgramMenu" path="Test\Verknüpfung.lnk" language="de"/>

    Élément <target>

    L'élément <target> spécifie l'emplacement du fichier pour lequel le Gestionnaire de paquets crée un raccourci.

    <target> est un élément vide, ce qui signifie qu'il a des attributs, mais qu'il ne contient pas d'élément ou de contenu texte. Il a les attributs suivants :

    Nom de l'attribut Type Valeur Exemples
    root Chaîne Une racine cible prise en charge. Les paquets présentant une architecture windows_all ne peuvent pas utiliser de racines cibles spécifiques 64 bits, comme ProgramFiles_64 ou LV2017DIR64. <target root="Startup" path="testShortcut.lnk"/>
    path Chaîne Chemin et nom du fichier ajoutés à la cible racine après sa résolution. Reportez-vous à la section Règles de syntaxe XML pour les guillemets pour connaître les spécifications de syntaxe. <target root="ProgramFiles" path="Shortcuts\test.exe"/>
    arguments Chaîne Arguments facultatifs transmis au fichier cible. Reportez-vous à la section Règles de syntaxe XML pour les guillemets pour connaître les spécifications de syntaxe. <target root="ProgramFiles" path="Shortcuts\test.exe" arguments="--argument1"/>

    Élément <returnCodeConventions>

    L'élément <returnCodeConventions> fournit une liste de conventions de codes de retour personnalisées que le Gestionnaire de paquets peut utiliser pour effectuer des actions personnalisées sur ce paquet.

    <returnCodeConventions> est facultatif dans le fichier d'instructions, mais peut contenir un ou plusieurs éléments <returnCodeConvention> enfants.

    Élément <returnCodeConvention>

    L'élément <returnCodeConvention> définit l'interprétation d'un code de retour pour une ou plusieurs exécutions personnalisées de ce paquet.

    <returnCodeConvention> peut avoir un ou plusieurs éléments <returnCode> enfants facultatifs. Les règles de <returnCode> sont évaluées dans l'ordre dans lequel elles sont définies.

    Nom de l'attribut Type Valeur Exemples
    name Chaîne Nom unique de cette convention de code de retour. Une exécution personnalisée dans ce paquet peut utiliser ce nom dans son champ returnCodeConvention pour s'associer à cette convention de code de retour. <returnCodeConvention name="alwaysReboot" defaultResult="rebootRequired"/>
    defaultResult Énum Indique le résultat sémantique d'un code de retour qui ne correspond à aucune règle existante de mappage de code de retour.
    • success
    • failure
    • rebootRequired
    		 <returnCodeConvention name="ignore" defaultResult="success"/>

    Élément <returnCode>

    L'élément <returnCode> définit une règle de mappage de code de retour pour son élément <returnCodeConvention> parent.

    <returnCode> est un élément vide, ce qui signifie qu'il dispose d'attributs, mais qu'il ne contient pas d'éléments ou de contenu texte. Il a les attributs suivants :

    Nom de l'attribut Type Valeur Exemples
    min Entier Indique la limite inférieure d'une gamme de codes de retour correspondant à cette règle. Ne peut pas être combiné avec l'attribut value. <returnCode min="0" max="1024" result="success"/>
    max Entier Indique la limite supérieure d'une gamme de codes de retour correspondant à cette règle. Ne peut pas être combiné avec l'attribut value. <returnCode min="-50" max="-1" result="success"/>
    value Entier Indique un code de retour unique correspondant à cette règle. Ne peut pas être combiné avec les attributs min ou max. <returnCode value="1641" result="rebootRequired"/>
    result Énum Indique le résultat sémantique d'un code de retour correspondant à cette règle. <returnCode value="3010" result="rebootRequired"/>

    Élément <customExecutes>

    L'élément <customExecutes> fournit une liste d'actions personnalisées que le Gestionnaire de paquets effectue sur le paquet.

    <customExecutes> contient l'élément enfant <customExecute>.

    Élément <customExecute>

    L'élément <customExecute> définit une action personnalisée effectuée par le Gestionnaire de paquets sur le paquet.

    L'élément <customExecute> est facultatif dans le fichier Instructions, mais vous pouvez en inclure autant que nécessaire pour votre paquet. <customExecute> est un élément vide, ce qui signifie qu'il dispose d'attributs, mais ne contient pas d'éléments ou de contenu texte. Il a les attributs suivants :

    Nom de l'attribut Type Requis Valeur Description Exemples
    root Chaîne Oui Chemin racine vers l'exécutable. Les paquets présentant une architecture windows_all ne peuvent pas utiliser de racines cibles spécifiques 64 bits, comme ProgramFiles_64 ou LV2017DIR64. Spécifie le chemin racine vers l'exécutable.

    Une racine cible prise en charge. Reportez-vous à Racines cibles d'installation pour voir les racines cibles supportées.

    Remarque Pour lancer un fichier exécutable, vous devez d'abord installer le paquet qui comprend ce fichier. Vous pouvez configurer un paquet pour qu'il installe temporairement l'exécutable en définissant le chemin racine cible sur NIPkgMgrTempUnique et l'attribut schedule sur post. Le Gestionnaire de paquets installe ensuite le paquet dans le répertoire NIPkgMgrTempUnique et lance l'exécutable à partir de cet emplacement avant de supprimer les fichiers du répertoire.
    		 <customExecute root="Documents" exeName="executable.exe"/>
    exeName Chaîne Oui Nom de fichier de l'exécutable. Spécifie le nom de fichier de l'exécutable.

    Peut inclure un chemin relatif à la racine. Reportez-vous à la section Règles de syntaxe XML pour les guillemets pour connaître les spécifications de syntaxe.

    		 <customExecute root="ProgramData" exeName="actions\executable.exe"/>
    arguments Chaîne Non Arguments de ligne de commande à passer à l'exécutable. Spécifie les arguments de ligne de commande que le Gestionnaire de paquets doit passer à l'exécutable.
    La valeur est formatée. Vous pouvez inclure une racine cible prise en charge et/ou les arguments suivants :
    Remarque Les arguments ne sont pas sensibles à la casse. Reportez-vous à la section Règles de syntaxe XML pour les guillemets pour connaître les spécifications de syntaxe.
  • %REBOOTPENDING%—Passe les informations relatives au redémarrage en instance. Si un redémarrage est nécessaire à la fin de la transaction, le Gestionnaire de paquets remplace %REBOOTPENDING% par 1. Sinon, le Gestionnaire de paquets remplace %REBOOTPENDING% par 0. Vous ne pouvez utiliser cet argument que si la valeur de l'attribut schedule est postall.
  • %NIPMLANGUAGECODE%—Spécifie la langue dans laquelle le Gestionnaire de paquets s'exécute à l'aide du code de langue ISO. Valeurs possibles : en, de, fr, ko, ja ou zh-CN.
    		•
    • <customExecute root="ProgramData" exeName="executable1.exe" arguments="-open %desktop%\file.txt"/>
    • <customExecute root="ProgramData" exeName="executable2.exe" arguments="-reboot %rebootpending%" schedule=postall/>
    • <customExecute root="ProgramData" exeName="executable3.exe" arguments="-language %nipmlanguagecode%"/>
    step Énum Non
  • install —(par défaut) Le Gestionnaire de paquets lance l'exécutable lors de l'installation du paquet.
  • uninstall —Le Gestionnaire de paquets lance l'exécutable lors de la suppression du paquet.
  • reinstall —Le Gestionnaire de paquets lance l'exécutable lors de la réparation du paquet.
    		• Spécifie l'étape de transaction au cours de laquelle le Gestionnaire de paquets lance l'exécutable.
    • Pour exécuter le même exécutable en plusieurs étapes, par exemple installer, désinstaller et réparer, répertoriez un élément <customExecute> pour chaque étape.
    • Si vous omettez cet attribut, le Gestionnaire de paquets utilise sa valeur par défaut.
    Remarque Pendant le développement d'un paquet, si vous définissez la valeur step sur uninstall, définissez la valeur ignoreErrors sur y pour éviter que le Gestionnaire de paquets ne puisse supprimer un paquet du système cible.
    		 <customExecute step="uninstall" root="ProgramData" ignoreErros="y" exeName="actions\executable.exe"/>
    schedule Énum Non
    • post (valeur par défaut)
    • pre
    • postall
    		Spécifie le point relatif dans les étapes de transaction auquel le Gestionnaire de paquets lance l'exécutable.

    Si vous omettez cet attribut, le Gestionnaire de paquets utilise sa valeur par défaut.

    		 <customExecute step="install" schedule="post" root="ProgramData" exeName="executable.exe"/>
    wait Booléen Non
    • n (valeur par défaut)
    • y
    		Spécifie si l'action personnalisée est synchrone, c'est-à-dire que le Gestionnaire de paquets doit attendre qu'elle soit terminée avant de continuer, ou si elle est asynchrone, auquel cas le Gestionnaire de paquets ne doit pas attendre que l'action soit terminée.

    Si vous omettez cet attribut, le Gestionnaire de paquets utilise sa valeur par défaut.

    		 <customExecute root="ProgramData" exeName="executable.exe" wait="n"/>
    ignoreErrors Booléen Non
    • n (valeur par défaut)
    • y
    		Spécifie si le Gestionnaire de paquets signale une erreur si l'exécutable ne peut pas s'exécuter ou si l'exécutable renvoie une valeur autre que 0.
    • Vous devez définir la valeur wait sur y pour que le Gestionnaire de paquets puisse recevoir le code de retour.
    • Si vous omettez cet attribut, le Gestionnaire de paquets utilise sa valeur par défaut.
    • Cet attribut ne peut pas être utilisé avec ignoreLaunchErrors ou returnCodeConvention.
    		 <customExecute root="ProgramData" exeName="executable.exe" wait="y" ignoreErrors="y"/>
    hideConsoleWindow Booléen Non
    • n (valeur par défaut)
    • y
    		Spécifie s'il faut cacher la fenêtre de console pour les applications de console.
    • N'affiche pas les messages de la console lorsque vous exécutez des applications d'interface utilisateur graphique.
    • Les applications de la console s'exécutent toujours, mais sans fenêtre de console pour une entrée de l'utilisateur ou une sortie de message.
    • Si vous omettez cet attribut, le Gestionnaire de paquets utilise sa valeur par défaut.
    • N'empêche pas l'application de créer des fenêtres de console supplémentaires.
    		 <customExecute root="ProgramData" exeName="executable.exe" hideConsoleWindow="y"/>
    ignoreLaunchErrors Booléen Non
    • n (valeur par défaut)
    • y
    		Spécifie si le Gestionnaire de paquets signale une erreur si l'exécutable ne peut pas s'exécuter ou s'il ne peut pas trouver l'exécutable. Cet attribut ne peut pas être utilisé avec ignoreErrors. <customExecute root="ProgramData" exeName="executable.exe" ignoreLaunchErrors="y"/>
    returnCodeConvention Chaîne Non Doit correspondre au nom d'une convention prédéfinie ou d'un élément <returnCodeConvention> défini dans ce paquet. Les conventions prédéfinies suivantes sont disponibles :
    • console (valeur par défaut)
    • installer
    • ignore
    		 Indique comment interpréter les codes de retour renvoyés par l'exécutable.
    • wait doit être défini à y pour que l'agent attende le code de retour
    • Pour console, 0 = success et toute autre valeur est une erreur.
    • Pour installer, 0 = success, 1641 = reboot required, 3010 = reboot required et toute autre valeur est une erreur.
    • Pour ignore, le Gestionnaire de paquets ignore le code de retour.
    • Cet attribut peut être utilisé avec ignoreErrors.
    		 <customExecute root="ProgramData" exeName="executable.exe" returnCodeConvention="installer"/>

    Comportement des exécutables programmés en tant que Postall

    Pour les fichiers d'instructions dans lesquels vous incluez un élément <customExecute> où schedule="postall", le Gestionnaire de paquets présente des comportements spécifiques susceptibles d'affecter l'installation du paquet.

    La valeur postall indique au Gestionnaire de paquets de lancer l'exécutable une fois les étapes d'installation, de réinstallation et/ou de suppression terminées pour tous les paquets.

    • Le Gestionnaire de paquets lance les exécutables postall dans l'ordre spécifié d'installation des paquets. Les dépendances s'installent d'abord.
    • Si un seul exécutable postall du paquet échoue, le Gestionnaire de paquets considère le paquet comme installé.
    • Lorsqu'il existe plusieurs paquets avec des exécutables postall, le Gestionnaire de paquets ne lance pas les exécutables restants si l'un des exécutables postall échoue. Les paquets sont considérés comme installés en supposant qu'aucune autre erreur ne s'est produite lors de l'installation.
    • Si l'installation d'un paquet échoue, soit en raison de l'échec du fichier MSI ou de l'échec d'un exécutable programmé comme pre ou post, le Gestionnaire de paquets affiche un message d'erreur indiquant que le paquet n'a pas pu être installé. Ensuite, il lance tous les exécutables des paquets installés jusqu'au moment de l'échec de l'installation. Le Gestionnaire de paquets ne prend pas en considération le paquet endommagé installé et ne lance pas les exécutables postall de ce paquet. Tous les paquets installés avant l'échec restent inchangés et le Gestionnaire de paquets lance les exécutables postall de ces paquets.

    Règles de syntaxe XML pour les guillemets

    Consultez les règles de syntaxe XML pour les guillemets afin de respecter la syntaxe des instructions conditionnelles de Microsoft et pour mettre entre guillemets les chemins comportant des espaces.

    Vous devez placer le texte littéral entre guillemets pour respecter la syntaxe des instructions conditionnelles de Microsoft. La syntaxe Instructions XML fournit deux façons de respecter cette spécification :

    • Utilisez des guillemets simples pour délimiter la chaîne XML. Cela permet l'utilisation de guillemets doubles à l'intérieur de la chaîne. Par exemple :
      <customExecute condition='IEDETECTED~="Yes" AND VersionNT64 = 601 AND NIRUNNINGINSILENTMODE'/>
    • Utilisez le caractère d'échappement XML pour les guillemets doubles, &quot;, pour délimiter le texte littéral dans la chaîne XML. Avec le caractère d'échappement XML, vous pouvez utiliser des guillemets doubles ou des guillemets simples pour délimiter la chaîne XML. Par exemple :
      <customExecute condition="IEDETECTED~=&quot;Yes&quot; AND VersionNT64 = 601 AND NIRUNNINGINSILENTMODE"/>

    Vous devez placer les chemins contenant des espaces entre guillemets. Les guillemets simples ne sont pas autorisés dans le chemin :

    • Utilisez le caractère d'échappement XML pour les guillemets doubles, &quot;, pour entourer le chemin dans la chaîne XML. Par exemple :
      <customExecute exeName="&quot;VC RunTime Installer.exe&quot;" arguments="/q /norestart" inPackage="y"/>

    Exemples CustomExecute

    Ce qui suit appelle un script PowerShell que le paquet pourrait avoir installé et transmet deux arguments après l'installation.

    <customExecute root="BootVolume" exeName="Windows\System32\WindowsPowerShell\v1.0\powershell.exe" arguments="-File &quot;%ProgramData%\My App Name\MyInstallScript.ps1&quot; &quot;argument 1&quot; &quot;argument 2&quot;" step="install" schedule="post" wait="y" ignoreErrors="n" hideConsoleWindow="y" />

    Élément <osUninstallEntry>

    L'élément <osUninstallEntry> fournit des instructions facultatives afin de faire apparaître le paquet dans l'interface Ajout/Suppression de programmes.

    <osUninstallEntry> est un élément vide. Cela signifie qu'il dispose d'attributs mais ne contient pas d'éléments ou de contenu texte. <osUninstallEntry> présente les attributs suivants :

    Nom de l'attribut Type Valeurs possibles Détails Exemples
    ux Énum
  • ni —(valeur par défaut) Affiche les éléments normaux de l'interface du Gestionnaire de paquets pendant une opération de modification ou de désinstallation.
  • oem —Masque l'intégralité du texte de boîte de dialogue et les liens faisant référence à NI pendant une opération de modification ou de désinstallation.
    		• Pour les paquets tiers, la valeur oem permet de faire apparaître le paquet comme un élément de première classe dans la liste des applications installées. Lors des opérations de modification et de désinstallation, l'interface Ajout/Suppression de programmes fait uniquement référence au paquet nommé. <osUninstallEntry ux="oem"/>