Bibliothèque d’éléments XML

Vue d’ensemble

Cette rubrique décrit les éléments XML et les fonctions d’assistance à votre disposition pour créer des fichiers .xml de migration qui seront utilisés avec l’Outil de migration utilisateur (USMT). Vous êtes supposé connaître les bases du langage XML. .

Dans cette rubrique

Outre les éléments XML et les fonctions d’assistance, cette rubrique décrit comment spécifier des emplacements et des modèles d’emplacements encodés et présente les fonctions réservées à l’usage interne de l’Outil de migration utilisateur (USMT), ainsi que les balises de version que vous pouvez utiliser avec les fonctions d’assistance.

• Éléments et fonctions d’assistance

• Annexe

  • Spécification d’emplacements

  • Fonctions internes de l’Outil de migration utilisateur (USMT)

  • Balises de version valides

Éléments et fonctions d’assistance

Le tableau suivant décrit les éléments XML et les fonctions d’assistance que vous pouvez utiliser avec l’Outil de migration utilisateur (USMT).

<addObjects>

L’élément <addObjects> émule l’existence d’un ou plusieurs objets sur l’ordinateur source. Les éléments <object> enfants fournissent les détails des objets émulés. Si le contenu est un élément <script>, le résultat de l’appel sera un tableau d’objets.

• Nombre d’occurrences : illimité

• Éléments parents : <rules>

• Éléments enfants requis : <object>. Vous devez aussi spécifier <location> et <attributes> comme éléments enfants de cet élément <object>.

• Éléments enfants facultatifs : <conditions>, <condition>, <script>

Syntaxe :

<addObjects>

<addObjects>

L’exemple suivant est extrait du fichier MigApp.xml :

<addObjects>
   <object>
      <location type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [UpgradeVersion]</location>
      <attributes>DWORD</attributes>
      <bytes>0B000000</bytes>
   </object>
   <object>
      <location type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [Lang]</location>
      <attributes>DWORD</attributes>
      <bytes>00000000</bytes>
   </object>
</addObjects>

<attributes>

L’élément <attributes> définit les attributs d’une clé de Registre ou d’un fichier.

• Nombre d’occurrences : une fois pour chaque élément <object>

• Éléments parents : <object>

• Éléments enfants : aucun

Syntaxe :

<attributes>contenu</attributes>

L’exemple suivant est extrait du fichier MigApp.xml :

<object>
   <location type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [Lang]</location>
   <attributes>DWORD</attributes>
   <bytes>00000000</bytes>
</object> 

<bytes>

Vous devez spécifier l’élément <bytes> uniquement pour les fichiers car, si <location> correspond à une clé de Registre ou à un répertoire, <bytes> est alors ignoré.

• Nombre d’occurrences : zéro ou une

• Éléments parents : <object>

• Éléments enfants : aucun

Syntaxe :

<bytes string="Yes|No" expand="Yes|No">contenu</bytes>

L’exemple suivant est extrait du fichier MigApp.xml :

<object>
   <location type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [Lang]</location>
   <attributes>DWORD</attributes>
   <bytes>00000000</bytes>
</object> 

<commandLine>

Vous voudrez peut-être utiliser l’élément <commandLine> si vous voulez démarrer ou arrêter un service ou une application avant ou après avoir exécuté les outils ScanState et LoadState.

• Nombre d’occurrences : illimité

• Éléments parents : <externalProcess>

• Éléments enfants : aucun

Syntaxe :

<commandLine>chaîne_ligne_commande</commandLine>

<component>

L’élément <component> est requis dans un fichier .xml personnalisé. Cet élément définit la construction la plus simple d’un fichier .xml de migration. Par exemple, dans le fichier MigApp.xml, « Microsoft® Office 2003 » est un composant contenant un autre composant, « Microsoft Office Access® 2003 ». Vous pouvez utiliser les éléments enfants pour définir ce composant.

Un composant peut être imbriqué dans un autre composant ; autrement dit, l’élément <component> peut être un enfant de l’élément <role> à l’intérieur de l’élément <component> dans deux cas : 1) lorsque l’élément <component> parent est un conteneur ou 2) si l’élément <component> enfant a le même rôle que l’élément <component> parent.

• Nombre d’occurrences : illimité

• Éléments parents : <migration>, <role>

• Éléments enfants requis : <role>, <displayName>

• Éléments enfants facultatifs : <manufacturer>, <version>, <description>, <paths>, <icon>, <environment>, <extensions>

Syntaxe :

<component type="System|Application|Device|Documents" context="User|System|UserAndSystem" defaultSupported="TRUE|FALSE|YES|NO"

hidden="Yes|No">

<component>

Pour obtenir un exemple, voir l’un des fichiers .xml de migration par défaut.

<condition>

Bien que l’élément <condition> soit pris en charge sous les éléments <detect>, <objectSet> et <addObjects>, nous vous recommandons de ne pas l’utiliser. Cet élément sera vraisemblablement déconseillé dans les versions futures de l’Outil de migration utilisateur (USMT), ce qui vous contraindra à réécrire vos scripts. Si vous avez besoin d’utiliser une condition dans les éléments <objectSet> et <addObjects>, nous vous recommandons d’utiliser l’élément <conditions> plus puissant qui vous permet de formuler des instructions booléennes complexes.

L’élément <condition> a un résultat booléen. Vous pouvez utiliser cet élément pour spécifier les conditions dans lesquelles l’élément parent sera évalué. Si l’une des conditions présentes renvoie la valeur FALSE, l’élément parent ne sera pas évalué.

• Nombre d’occurrences : illimité

• Éléments parents : <conditions>, <detect>, <objectSet>, <addObjects>

• Éléments enfants : aucun

• Fonctions d’assistance : Vous pouvez utiliser les Fonctions <condition> suivantes avec cet élément : DoesOSMatch, IsNative64Bit(), IsOSLaterThan, IsOSEarlierThan, DoesObjectExist, DoesFileVersionMatch, IsFileVersionAbove, IsFileVersionBelow, IsSystemContext, DoesStringContentEqual, DoesStringContentContain, IsSameObject, IsSameContent IsSameStringContent.

Syntaxe :

<condition negation="Yes|No">nom_script</condition>

Par exemple :

Dans l’exemple de code ci-dessous, les éléments <condition>, A et B, sont reliés par l’opérateur AND car ils se trouvent dans des sections <conditions> distinctes. Exemple :

<detection>
   <conditions>
      <condition>A</condition>
   </conditions>
   <conditions operation="AND">
      <condition>B</condition>
   </conditions>
</detection>

Toutefois, dans l’exemple de code ci-dessous, les éléments <condition>, A et B, sont reliés par l’opérateur OU car ils se trouvent dans la même section <conditions>.

<detection>
   <conditions>
      <condition>A</condition>
      <condition>B</condition>
   </conditions>
</detection>

Fonctions <condition>

Les fonctions <condition> renvoient une valeur booléenne. Vous pouvez utiliser ces éléments dans des conditions <addObjects>.

• Fonctions de la version du système d’exploitation

• Fonctions du contenu des objets

Fonctions de la version du système d’exploitation

• DoesOSMatch

  Toutes les correspondances respectent la casse.

  Syntaxe : DoesOSMatch("type_système_exploitation","version_système_exploitation")

  Paramètre	Obligatoire ?	Valeur
  type_système_exploitation	Oui	La seule valeur autorisée pour ce paramètre est NT. Notez toutefois que vous devez définir ce paramètre pour que les fonctions <condition> marchent correctement.
  version_système_exploitation	Oui	La version majeure, la version mineure, le numéro de version et la version des disquettes de service, séparés par des points. Par exemple, 5.0.2600.Service Pack 1. Vous pouvez également indiquer une spécification partielle de la version avec un modèle. Par exemple, 5.0.*.

  Exemple :

  <condition>MigXmlHelper.DoesOSMatch("NT","*")</condition>

• IsNative64Bit

  La fonction IsNative64Bit renvoie TRUE si le processus de migration s’exécute comme un processus 64 bits natif ; autrement dit un processus s’exécutant sur un système 64 bits sans WOW (Windows on Windows). Sinon, FALSE est retourné.

• IsOSLaterThan

  Toutes les comparaisons respectent la casse.

  Syntaxe : IsOSLaterThan("OSType","OSVersion")

  Paramètre	Obligatoire ?	Valeur
  type_système_exploitation	Oui	Peut être 9x ou NT. Si type_système_exploitation ne correspond pas au type du système d’exploitation actuel, FALSE est retourné. Par exemple, si le système d’exploitation actuel est Windows NT et que type_système_exploitation a la valeur « 9x », le résultat est FALSE.
  version_système_exploitation	Oui	La version majeure, la version mineure, le numéro de version et la version des disquettes de service, séparés par des points. Par exemple, 5.0.2600.Service Pack 1. Vous pouvez également indiquer une spécification partielle de la version, mais aucun modèle n’est autorisé. Par exemple, 5.0. La fonction renvoie TRUE si le système d’exploitation actuel est ultérieur ou égal à version_système_exploitation.

  Exemple :

  <condition negation="Yes">MigXmlHelper.IsOSLaterThan("NT","6.0")</condition>

• IsOSEarlierThan

  Toutes les comparaisons respectent la casse.

  Syntaxe : IsOSEarlierThan("OSType","OSVersion")

  Paramètre	Obligatoire ?	Valeur
  type_système_exploitation	Oui	Peut être 9x ou NT. Si type_système_exploitation ne correspond pas au type du système d’exploitation actuel, FALSE est retourné. Par exemple, si le système d’exploitation actuel est Windows NT et que type_système_exploitation a la valeur « 9x », le résultat est FALSE.
  version_système_exploitation	Oui	La version majeure, la version mineure, le numéro de version et la version des disquettes de service, séparés par des points. Par exemple, 5.0.2600.Service Pack 1. Vous pouvez également indiquer une spécification partielle de la version, mais aucun modèle n’est autorisé. Par exemple, 5.0. La fonction IsOSEarlierThan renvoie TRUE si le système d’exploitation actuel est antérieur à version_système_exploitation.

Fonctions du contenu des objets

• DoesObjectExist

  La fonction DoesObjectExist renvoie TRUE s’il existe un objet correspondant au modèle d’emplacement Sinon, FALSE est retourné. Le modèle d’emplacement est développé avant la tentative d’énumération.

  Syntaxe : DoesObjectExist("type_objet","modèle_emplacement_encodé")

  Paramètre	Obligatoire ?	Valeur
  type_objet	Oui	Définit le type de l’objet. Peut être Fichier ou Registre.
  modèle_emplacement_encodé	Oui	Spécification d’emplacements. Les variables d’environnement sont autorisées.

  Pour obtenir un exemple de cet élément, voir le fichier MigApp.xml.

• DoesFileVersionMatch

  La vérification du modèle ne respecte pas la casse.

  Syntaxe : DoesFileVersionMatch("emplacement_fichier_encodé","balise_version","valeur_version")

  Paramètre	Obligatoire ?	Valeur
  emplacement_fichier_encodé	Oui	Spécification d’emplacements pour le fichier qui sera vérifié. Les variables d’environnement sont autorisées.
  balise_version	Oui	Valeur de Balises de version valides qui sera vérifiée.
  valeur_version	Oui	Modèle de chaîne. Par exemple, « Microsoft* ».

  Exemple :

  <condition>MigXmlHelper.DoesFileVersionMatch("%MSNMessengerInstPath%\msnmsgr.exe","ProductVersion","6.*")</condition>

  <condition>MigXmlHelper.DoesFileVersionMatch("%MSNMessengerInstPath%\msnmsgr.exe","ProductVersion","7.*")</condition>

• IsFileVersionAbove

  La fonction IsFileVersionAbove renvoie TRUE si la version du fichier est supérieure à valeur_version.

  Syntaxe : IsFileVersionAbove("emplacement_fichier_encodé","balise_version","valeur_version")

  Paramètre	Obligatoire ?	Valeur
  emplacement_fichier_encodé	Oui	Spécification d’emplacements pour le fichier qui sera vérifié. Les variables d’environnement sont autorisées.
  balise_version	Oui	Valeur de Balises de version valides qui sera vérifiée.
  valeur_version	Oui	Valeur avec laquelle effectuer la comparaison. Vous ne pouvez pas spécifier un modèle.

• IsFileVersionBelow

  Syntaxe : IsFileVersionBelow("emplacement_fichier_encodé","balise_version","valeur_version")

  Paramètre	Obligatoire ?	Valeur
  emplacement_fichier_encodé	Oui	Spécification d’emplacements pour le fichier qui sera vérifié. Les variables d’environnement sont autorisées.
  balise_version	Oui	Valeur de Balises de version valides qui sera vérifiée.
  valeur_version	Oui	Valeur avec laquelle effectuer la comparaison. Vous ne pouvez pas spécifier un modèle.

• IsSystemContext

  La fonction IsSystemContext renvoie TRUE si le contexte actuel est « System ». Sinon, FALSE est retourné.

  Syntaxe : IsSystemContext()

• DoesStringContentEqual

  La fonction DoesStringContentEqual renvoie TRUE si la représentation sous forme de chaîne de l’objet donné est identique à StringContent.

  Syntaxe : DoesStringContentEqual("type_objet","emplacement_encodé","contenu_chaîne")

  Paramètre	Obligatoire ?	Valeur
  type_objet	Oui	Définit le type d’objet. Peut être File ou Registry.
  modèle_emplacement_encodé	Oui	Spécification d’emplacements pour l’objet qui sera examiné. Vous pouvez spécifier des variables d’environnement.
  contenu_chaîne	Oui	Chaîne avec laquelle effectuer la comparaison.

  Exemple :

  <condition negation="Yes">MigXmlHelper.DoesStringContentEqual("File","%USERNAME%","")</condition>
  

• DoesStringContentContain

  La fonction DoesStringContentContain renvoie TRUE si au moins une occurrence de chaîne_à_rechercher se trouve dans la représentation sous forme de chaîne de l’objet.

  Syntaxe : DoesStringContentContain("type_objet","emplacement_encodé","chaîne_à_rechercher")

  Paramètre	Obligatoire ?	Valeur
  type_objet	Oui	Définit le type d’objet. Peut être File ou Registry.
  modèle_emplacement_encodé	Oui	Spécification d’emplacements pour l’objet qui sera examiné. Vous pouvez spécifier des variables d’environnement.
  chaîne_à_rechercher	Oui	Chaîne qui sera recherchée dans le contenu de l’objet donné.

• IsSameObject

  La fonction IsSameObject renvoie TRUE si les emplacements encodés donnés représentent le même objet physique. Sinon, FALSE est retourné.

  Syntaxe : IsSameObject("type_objet","emplacement_encodé_1","emplacement_encodé_2")

  Paramètre	Obligatoire ?	Valeur
  type_objet	Oui	Définit le type d’objet. Peut être File ou Registry.
  emplacement_encodé_1	Oui	Spécification d’emplacements pour le premier objet. Vous pouvez spécifier des variables d’environnement.
  emplacement_encodé_2	Oui	Spécification d’emplacements pour le deuxième objet. Vous pouvez spécifier des variables d’environnement.

  Exemple :

  <objectSet>
       <condition negation="Yes">MigXmlHelper.IsSameObject("File","%CSIDL_FAVORITES%","%CSIDL_COMMON_FAVORITES%")</condition>
       <pattern type="File">%CSIDL_FAVORITES%\* [*]</pattern>
  </objectSet>
  

• IsSameContent

  La fonction IsSameContent renvoie TRUE si les objets donnés ont le même contenu. Sinon, FALSE est retourné. Le contenu sera comparé octet par octet.

  Syntaxe : IsSameContent("type_objet_1","emplacement_encodé_1","type_objet_2","emplacement_encodé_2")

  Paramètre	Obligatoire ?	Valeur
  type_objet_1	Oui	Définit le type du premier objet. Peut être Fichier ou Registre.
  emplacement_encodé_1	Oui	Spécification d’emplacements pour le premier objet. Vous pouvez spécifier des variables d’environnement.
  type_objet_2	Oui	Définit le type du deuxième objet. Peut être Fichier ou Registre.
  emplacement_encodé_2	Oui	Spécification d’emplacements pour le deuxième objet. Vous pouvez spécifier des variables d’environnement.

• IsSameStringContent

  La fonction IsSameContent renvoie TRUE si les objets donnés ont le même contenu. Sinon, FALSE est retourné. Le contenu sera interprété en tant que chaîne.

  Syntaxe : IsSameStringContent("type_objet_1","emplacement_encodé_1","type_objet_2","emplacement_encodé_2")

  Paramètre	Obligatoire ?	Valeur
  type_objet_1	Oui	Définit le type du premier objet. Peut être File ou Registry.
  emplacement_encodé_1	Oui	Spécification d’emplacements pour le premier objet. Vous pouvez spécifier des variables d’environnement.
  type_objet_2	Oui	Définit le type du deuxième objet. Peut être File ou Registry.
  emplacement_encodé_2	Oui	Spécification d’emplacements pour le deuxième objet. Vous pouvez spécifier des variables d’environnement.

<conditions>

L’élément <conditions> renvoie un résultat booléen qui est utilisé pour spécifier les conditions dans lesquelles l’élément parent est évalué. L’Outil de migration utilisateur (USMT) évalue les éléments enfants, puis relie leurs résultats à l’aide des opérateurs AND ou OR, selon la valeur du paramètre operation.

• Nombre d’occurrences : illimité à l’intérieur d’un autre élément <conditions>. Limité à une occurrence dans <detection>, <rules>, <addObjects> et <objectSet>

• Éléments parents : <conditions>, <detection>, <environment>, <rules>, <addObjects> et <objectSet>

• Éléments enfants : <conditions>, <condition>

Syntaxe :

<conditions operation="AND|OR">

</conditions>

L’exemple suivant est extrait du fichier MigApp.xml :

<environment name="GlobalEnv">
   <conditions>
      <condition negation="Yes">MigXmlHelper.IsNative64Bit()</condition>
   </conditions>
   <variable name="HklmWowSoftware">
   <text>HKLM\Software</text>
   </variable>
</environment>

<content>

Vous pouvez utiliser l’élément <content> pour spécifier une liste de modèles d’objets afin d’obtenir un jeu d’objets à partir de l’ordinateur source. Chaque <objectSet> d’un élément <content> est évalué. Pour chaque liste de modèles d’objets obtenue, les objets qui correspondent à la liste sont énumérés et leur contenu est filtré en fonction du paramètre de filtre. Le tableau de chaînes obtenu est la sortie de l’élément <content>. Le script de filtrage renvoie un tableau d’emplacements. L’élément <objectSet> parent peut contenir plusieurs éléments <content> enfants.

• Nombre d’occurrences : illimité

• Éléments parents : <objectSet>

• Éléments enfants : <objectSet>

• Fonctions d’assistance : Vous pouvez utiliser les Fonctions <content> suivantes avec cet élément : ExtractSingleFile, ExtractMultipleFiles et ExtractDirectory.

Syntaxe :

<content filter="appel_script">

<content>

Fonctions <content>

Les fonctions suivantes génèrent des modèles à partir du contenu d’un objet. Ces fonctions sont appelées pour chaque objet que l’élément <ObjectSet> parent énumère.

• ExtractSingleFile

  Si la valeur de Registre est une valeur MULTI-SZ, seul le premier segment est traité. Le modèle renvoyé est l’emplacement encodé d’un fichier qui doit exister sur le système. Si la spécification est correcte dans la valeur de Registre, mais que le fichier n’existe pas, cette fonction renvoie la valeur NULL.

  Syntaxe : ExtractSingleFile(séparateurs,indications_chemin_accès)

  Paramètre	Obligatoire ?	Valeur
  séparateurs	Oui	Liste des séparateurs possibles pouvant suivre la spécification de fichier dans ce nom de valeur du Registre. Par exemple, si le contenu est « C:\Windows\Notepad.exe,-2 », le séparateur est une virgule. Vous pouvez spécifier NULL.
  indications_chemin_accès	Oui	Liste de chemins d’accès supplémentaires, séparés par des points-virgules (;), où la fonction cherche un fichier correspondant au contenu actuel. Par exemple, si le contenu est « Notepad.exe » et que le chemin d’accès est la variable d’environnement %Path%, la fonction trouve Notepad.exe dans %windir% et retourne « c:\Windows [Notepad.exe] ». Vous pouvez spécifier NULL.

  Exemple :

  <content filter="MigXmlHelper.ExtractSingleFile(',','%system%')">
  

  et

  <content filter="MigXmlHelper.ExtractSingleFile(NULL,'%CSIDL_COMMON_FONTS%')">
  

• ExtractMultipleFiles

  La fonction ExtractMultipleFiles retourne plusieurs modèles, un pour chaque fichier qui se trouve dans le contenu de la valeur de Registre donnée. Si la valeur de Registre est une valeur MULTI-SZ, le séparateur MULTI-SZ est considéré par défaut comme un séparateur. Par conséquent, pour MULTI-SZ, l’argument <Separators> doit être NULL.

  Les modèles retournés sont les emplacements encodés des fichiers qui doivent exister sur l’ordinateur source. Si la spécification est correcte dans la valeur de Registre, mais que le fichier n’existe pas, il ne figurera pas dans la liste obtenue.

  Syntaxe : ExtractMultipleFiles(séparateurs,indications_chemins_accès)

  Paramètre	Obligatoire ?	Valeur
  séparateurs	Oui	Liste des séparateurs possibles pouvant suivre la spécification de fichier dans ce nom de valeur du Registre. Par exemple, si le contenu est « C:\Windows\Notepad.exe,-2 », le séparateur est une virgule. Ce paramètre doit être NULL lors du traitement de valeurs de Registre MULTI-SZ.
  indications_chemin_accès	Oui	Liste de chemins d’accès supplémentaires, séparés par des points-virgules (;), où la fonction cherche un fichier correspondant au contenu actuel. Par exemple, si le contenu est « Notepad.exe » et que le chemin d’accès est la variable d’environnement %Path%, la fonction trouve Notepad.exe dans %windir% et retourne « c:\Windows [Notepad.exe] ». Vous pouvez spécifier NULL.

• ExtractDirectory

  La fonction ExtractDirectory renvoie un modèle qui est l’emplacement encodé d’un répertoire qui doit exister sur l’ordinateur source. Si la spécification est correcte dans la valeur de Registre, mais que le répertoire n’existe pas, cette fonction renvoie la valeur NULL. Si la valeur de Registre est une valeur MULTI-SZ, seul le premier segment est traité.

  Syntaxe : ExtractDirectory(séparateurs,niveaux_à_supprimer,suffixe_modèle)

  Paramètre	Obligatoire ?	Valeur
  séparateurs	Non	Liste des séparateurs pouvant suivre la spécification de fichier dans ce nom de valeur du Registre. Par exemple, si le contenu est « C:\Windows\Notepad.exe,-2 », le séparateur est une virgule. Ce paramètre doit être NULL pour les valeurs de Registre MULTI-SZ.
  niveaux_à_supprimer	Oui	Nombre de niveaux à supprimer à la fin de la spécification de répertoire. Utilisez cette fonction pour extraire un répertoire racine lorsque vous avez une valeur de Registre qui pointe à l’intérieur de ce répertoire racine dans un emplacement connu.
  suffixe_modèle	Oui	Modèle à ajouter à la spécification de répertoire. Par exemple, * [*].

  Exemple :

  <objectSet>
       <content filter='MigXmlHelper.ExtractDirectory (NULL, "1")'>
            <objectSet>
                 <pattern type="Registry">%HklmWowSoftware%\Classes\Software\RealNetworks\Preferences\DT_Common []</pattern>
            </objectSet>
       </content>
  </objectSet>
  

<contentModify>

L’élément <contentModify> modifie le contenu d’un objet avant son écriture sur l’ordinateur de destination. Pour chaque élément <contentModify> il peut y exister plusieurs éléments <objectSet>. Cet élément retourne le nouveau contenu de l’objet en cours de traitement.

• Nombre d’occurrences : illimité

• Éléments parents : <rules>

• Éléments enfants requis : <objectSet>

• Fonctions d’assistance : vous pouvez utiliser les Fonctions <contentModify> suivantes avec cet élément : ConvertToDWORD, ConvertToString, ConvertToBinary, KeepExisting, OffsetValue, SetValueByTable, MergeMultiSzContent et MergeDelimitedContent.

Syntaxe :

<contentModify script="appel_script">

<contentModify>

Fonctions <contentModify>

Les fonctions suivantes modifient le contenu des objets au moment de leur migration. Ces fonctions sont appelées pour chaque objet que l’élément <ObjectSet> parent énumère.

• ConvertToDWORD

  La fonction ConvertToDWORD convertit le contenu de valeurs de Registre énumérées par l’élément <ObjectSet> parent en valeurs DWORD. Par exemple, ConvertToDWORD convertit la chaîne « 1 » en valeur DWORD 0x00000001. Si la conversion échoue, la valeur de valeur_par_défaut_si_erreur est appliquée.

  Syntaxe : ConvertToDWORD(valeur_par_defaut_si_erreur)

  Paramètre	Obligatoire ?	Valeur
  valeur_par_défaut_si_erreur	Non	Valeur qui est écrite dans le nom de la valeur si la conversion échoue. Vous pouvez spécifier NULL, et 0 est écrit si la conversion échoue.

• ConvertToString

  La fonction ConvertToString convertit en chaîne le contenu des valeurs de Registre qui correspondent à l’élément <ObjectSet> parent. Elle convertit par exemple la valeur DWORD 0x00000001 en chaîne « 1 ». Si la conversion échoue, la valeur de DefaultValueOnError est appliquée.

  Syntaxe : ConvertToString(valeur_par_défaut_si_erreur)

  Paramètre	Obligatoire ?	Valeur
  DefaultValueOnError	Non	Valeur qui est écrite dans le nom de la valeur si la conversion échoue. Vous pouvez spécifier NULL, et 0 est écrit si la conversion échoue.

  Exemple :

  <contentModify script="MigXmlHelper.ConvertToString('1')">
       <objectSet>
            <pattern type="Registry">HKCU\Control Panel\Desktop [ScreenSaveUsePassword]</pattern>
       </objectSet>
  </contentModify>
  

• ConvertToBinary

  La fonction ConvertToBinary convertit en type binaire le contenu des valeurs de Registre qui correspondent à l’élément <ObjectSet> parent.

  Syntaxe : ConvertToBinary ()

• OffsetValue

  La fonction OffsetValue ajoute ou soustrait valeur de la valeur de l’objet migré, puis écrit le résultat dans la valeur de Registre sur l’ordinateur de destination. Par exemple, si l’objet migré est une valeur DWORD égale à 14 et si valeur est égale à « -2 », la valeur de Registre sera 12 sur l’ordinateur de destination.

  Syntaxe : OffsetValue(valeur)

  Paramètre	Obligatoire ?	Valeur
  Valeur	Oui	Représentation sous forme de chaîne d’une valeur numérique. Peut être positive ou négative. Par exemple, OffsetValue(2).

• SetValueByTable

  La fonction SetValueByTable fait correspondre la valeur de l’ordinateur source à la table source. Si la valeur s’y trouve, la valeur équivalente dans la table de destination est appliquée. Si elle ne s’y trouve pas ou si la table de destination n’a pas de valeur équivalente, la valeur_par_défaut_si_erreur est appliquée.

  Syntaxe : SetValueByTable(table_source,table_destination,valeur_par_défaut_si_erreur)

  Paramètre	Obligatoire ?	Valeur
  table_source	Oui	Liste des valeurs (séparées par des virgules) qui sont acceptées pour les valeurs de Registre sources.
  table_destination	Non	Liste de valeurs traduites, séparées par des virgules.
  valeur_par_défaut_si_erreur	Non	La valeur est appliquée à l’ordinateur de destination si 1) la valeur de l’ordinateur source ne correspond pas à table_source ou 2) table_destination ne contient pas de valeur équivalente. Si valeur_par_défaut_si_erreur est NULL, la valeur n’est pas modifiée sur l’ordinateur de destination.

• KeepExisting

  Vous pouvez utiliser la fonction KeepExisting en cas de conflit sur l’ordinateur de destination. Cette fonction conserve (et n’écrase pas) les attributs spécifiés pour l’objet qui se trouve sur l’ordinateur de destination.

  Syntaxe : KeepExisting("chaîne_option","chaîne_option","chaîne_option",…)

  Paramètre	Obligatoire ?	Valeur
  chaîne_option	Oui	chaîne_option peut prendre la valeur Security, TimeFields ou FileAttrib:lettre. Vous pouvez spécifier chacun des types de chaîne_option. Ne spécifiez pas plusieurs chaîne_option de la même valeur. La valeur la plus à droite serait alors conservée. Par exemple, ne spécifiez pas ("FileAttrib:H", "FileAttrib:R") car seul Lecture seule (R) sera évalué. Indiquez à la place ("FileAttrib:HR") pour que les attributs Masqué (H) et Lecture seule (R) soient tous deux conservés sur l’ordinateur de destination. Security. Conserve le descripteur de sécurité de l’objet de destination s’il existe. TimeFields. Conserve l’horodateur de l’objet de destination. Ce paramètre ne s’applique qu’aux fichiers. FileAttrib:lettre. Conserve la valeur d’attribut de l’objet de destination (On ou OFF) pour le jeu d’attributs de fichiers spécifié. Ce paramètre ne s’applique qu’aux fichiers. Les attributs suivants ne respectent pas la casse, mais USMT ignore les valeurs non valides, répétées ou comprenant un espace après "FileAttrib:". Vous pouvez indiquer toute combinaison des attributs suivants : A = Archive C = Compressé E = Chiffré H = Masqué I = Contenu non indexé O = Hors connexion R = Lecture seule S = Système T = Temporaire

• MergeMultiSzContent

  La fonction MergeMultiSzContent fusionne le contenu MULTI-SZ des valeurs de Registre qui sont énumérées par l’élément <ObjectSet> parent avec le contenu des valeurs de Registre équivalentes qui existent déjà sur l’ordinateur de destination. Instruction et String suppriment ou ajoutent du contenu à la valeur MULTI-SZ obtenue. Les éléments en double sont supprimés.

  Syntaxe : MergeMultiSzContent (instruction,chaîne,instruction,chaîne,…)

  Paramètre	Obligatoire ?	Valeur
  instruction	Oui	Peut être l’une des suivantes : Add. Ajoute la chaîne correspondante à la valeur MULTI-SZ obtenue si elle ne s’y trouve pas déjà. Remove. Supprime la chaîne correspondante de la valeur MULTI-SZ obtenue.
  chaîne	Oui	Chaîne à ajouter ou supprimer.

• MergeDelimitedContent

  La fonction MergeDelimitedContent fusionne le contenu des valeurs de Registre qui sont énumérées par l’élément <ObjectSet> parent avec le contenu des valeurs de Registre équivalentes qui existent déjà sur l’ordinateur de destination. Le contenu est considéré comme une liste d’éléments séparés par l’un des caractères du paramètre Délimiteurs. Les éléments en double seront supprimés.

  Syntaxe : MergeDelimitedContent(délimiteurs,instruction,chaîne,…)

  Paramètre	Obligatoire ?	Valeur
  délimiteurs	Oui	Caractère unique qui sera utilisé pour séparer le contenu de l’objet en cours de traitement. Le contenu sera traité comme une liste d’éléments séparés par les délimiteurs. Par exemple, « . » sépare la chaîne au niveau du point.
  instruction	Oui	Peut être l’une des suivantes : Add. Ajoute chaîne à la valeur MULTI-SZ obtenue si elle ne s’y trouve pas déjà. Remove. Supprime chaîne de la valeur MULTI-SZ obtenue.
  chaîne	Oui	Chaîne à ajouter ou supprimer.

<description>

L’élément <description> définit la description du composant mais n’affecte pas la migration.

• Nombre d’occurrences : zéro ou une

• Éléments parents : <component>

• Éléments enfants : aucun

Syntaxe :

<description>description_composant</description>

L’exemple de code suivant montre comment l’élément <description> définit la description « My custom component » :

<description>My custom component<description>

<destinationCleanup>

L’élément <destinationCleanup> supprime des objets, comme des fichiers et des clés de Registre, de l’ordinateur de destination avant d’appliquer les objets de l’ordinateur source. Cet élément est uniquement évalué lorsque l’outil LoadState est exécuté sur l’ordinateur de destination. Autrement dit, cet élément est ignoré par l’outil ScanState.

Pour chaque élément <destinationCleanup> il peut exister plusieurs éléments <objectSet>. Cet élément est souvent utilisé lorsqu’il manque une clé de Registre sur l’ordinateur source et que vous voulez vous assurer qu’un composant est migré. Dans ce cas, vous pouvez supprimer toutes les clés de Registre du composant avant de migrer les clés de Registre sources. Ainsi, si une clé est manquante sur l’ordinateur source, elle le sera aussi sur l’ordinateur de destination.

• Nombre d’occurrences : illimité

• Éléments parents : <rules>

• Éléments enfants : <objectSet> (notez que l’ordinateur de destination supprimera tous les éléments enfants.)

Syntaxe :

<destinationCleanup filter=appel_script>

<destinationCleanup>

Exemple :

<destinationCleanup>
   <objectSet>
      <pattern type="Registry">HKCU\Software\Lotus\123\99.0\DDE Preferences\* [*]</pattern>
      <pattern type="Registry">HKCU\Software\Lotus\123\99.0\Find Preferences\* [*]</pattern>
   </objectSet>
</destinationCleanup>

<detect>

Bien que l’élément <detect> soit toujours pris en charge, nous vous recommandons de ne pas l’utiliser car il sera probablement déconseillé dans les versions futures de l’Outil de migration utilisateur (USMT). et vous devrez réécrire vos scripts. Utilisez plutôt l’élément <detection>.

L’élément <detect> permet de déterminer si le composant est présent sur un système. Si tous les éléments <detect> enfants d’un élément <detect> ont la valeur TRUE, alors l’élément <detect> a la valeur TRUE. Si l’un des éléments <detect> enfants a la valeur FALSE, alors son élément <detect> a la valeur FALSE. L’absence de section <detect> laisse supposer à l’Outil de migration utilisateur (USMT) que le composant est présent.

Pour chaque élément <detect>, il peut exister plusieurs éléments <condition> ou <objectSet>, qui sont reliés de façon logique par un opérateur OR. Si au moins un élément <condition> ou <objectSet> a la valeur TRUE, l’élément <detect> a de ce fait la valeur TRUE.

• Nombre d’occurrences : illimité

• Éléments parents : <detects>, <namedElements>

• Éléments enfants requis : <condition>

• Éléments enfants facultatifs : <objectSet>

Syntaxe :

<detect name="ID" context="User|System|UserAndSystem">

<detect>

Voir les exemples de l’élément <detection>.

<detects>

Bien que l’élément <detects> soit toujours pris en charge, nous vous recommandons de ne pas l’utiliser car il sera probablement déconseillé dans les versions futures de l’Outil de migration utilisateur (USMT) et vous devrez réécrire vos scripts. Nous vous conseillons d’utiliser l’élément <detection> si l’élément parent est <role> ou <namedElements>, et l’élément <conditions> si l’élément parent est <rules>. L’élément <detection> vous permet de formuler plus clairement des instructions booléennes complexes.

L’élément <detects> est un conteneur pour un ou plusieurs éléments <detect>. Si tous les éléments <detect> enfants d’un élément <detects> ont la valeur TRUE, alors l’élément <detects> a la valeur TRUE. Si l’un des éléments <detect> a la valeur FALSE, alors l’élément <detects> a la valeur FALSE. Si vous ne souhaitez pas écrire des éléments <detects> dans un composant, vous pouvez créer l’élément <detects> sous l’élément <namedElements>, puis y faire référence. L’absence de section <detects>, laisse supposer à l’Outil de migration utilisateur (USMT) que le composant est présent. Les résultats de chaque élément <detects> sont reliés par l’opérateur OR afin de former la règle utilisée pour détecter l’élément parent.

Syntaxe :

<detects name="ID" context="User|System|UserAndSystem">

</detects>

• Nombre d’occurrences : illimité.

• Éléments parents : <role>, <rules>, <namedElements>

• Éléments enfants requis : <detect>

L’exemple suivant est extrait du fichier MigApp.xml.

<detects>
   <detect>
      <condition>MigXmlHelper.DoesFileVersionMatch("%Lotus123InstPath%\123w.exe","ProductVersion","9.*")</condition>
   </detect>
   <detect>
      <condition>MigXmlHelper.DoesFileVersionMatch("%SmartSuiteInstPath%\smartctr.exe","ProductVersion","99.*")</condition>
   </detect>
</detects>

<detection>

L’élément <detection> est un conteneur pour un élément <conditions>. Le résultat des éléments <condition> enfants, situés sous l’élément <conditions>, détermine le résultat de cet élément. Si tous les éléments <conditions> enfants de l’élément <detection> ont la valeur TRUE, alors l’élément <detection> a la valeur TRUE. Si l’un des éléments <conditions> a la valeur FALSE, alors l’élément <detection> a la valeur FALSE.

Par ailleurs, les résultats de chaque section <detection> de l’élément <role> sont reliés par l’opérateur OR pour former la règle de détection de l’élément parent. Autrement dit, si l’une des sections <detection> a la valeur TRUE, l’élément <role> est traité. Sinon, l’élément <role> n’est pas traité.

Utilisez l’élément <detection> sous l’élément <namedElements> si vous ne voulez pas l’écrire dans un composant. Incluez ensuite une section <detection> correspondante sous l’élément <role> afin de contrôler si le composant est migré. L’absence de section <detection> pour un composant, laisse supposer à l’Outil de migration utilisateur (USMT) que ce composant est présent.

• Nombre d’occurrences : illimité.

• Éléments parents : <role>, <namedElements>

• Éléments enfants : <conditions>

Syntaxe :

<detection name="ID" context="User|System|UserAndSystem">

</detection>

Exemple :

<detection name="AdobePhotoshopCS">
   <conditions>
      <condition>MigXmlHelper.DoesObjectExist("Registry","HKCU\Software\Adobe\Photoshop\8.0")</condition>
      <condition>MigXmlHelper.DoesFileVersionMatch("%PhotoshopSuite8Path%\Photoshop.exe","FileVersion","8.*")</condition>
   </conditions>
</detection>

et

<role role="Settings">
   <detection>
      <conditions>
         <condition>MigXmlHelper.DoesFileVersionMatch("%QuickTime5Exe%","ProductVersion","QuickTime 5.*")</condition>
         <condition>MigXmlHelper.DoesFileVersionMatch("%QuickTime5Exe%","ProductVersion","QuickTime 6.*")</condition>
      </conditions>
   </detection>

<displayName>

L’élément <displayName> est un champ requis dans chaque élément <component>.

• Nombre d’occurrences : une fois pour chaque composant

• Éléments parents : <component>

• Éléments enfants : aucun

Syntaxe :

<displayName _locID="ID">nom_composant</displayName>

Exemple :

<displayName>Command Prompt settings</displayName>

<environment>

L’élément <environment> est un conteneur pour les éléments <variable> dans lequel vous pouvez définir les variables à utiliser dans votre fichier .xml. Toutes les variables d’environnement définies de cette façon seront privées. Autrement dit, elles ne seront disponibles que pour leurs composants enfants et le composant dans lequel elles ont été définies. Pour obtenir deux exemples de scénarios, voir Exemples.

• Nombre d’occurrences : illimité

• Éléments parents : <role>, <component>, <namedElements>

• Éléments enfants requis : <variable>

• Éléments enfants facultatifs : <conditions>

Syntaxe :

<environment name="ID" context="User|System|UserAndSystem">

</environment>

Exemple de scénario 1

Dans ce scénario, vous voulez générer l’emplacement des objets au moment de l’exécution en fonction de la configuration de l’ordinateur de destination. Vous devez appliquer ce scénario si, par exemple, une application écrit des données dans son répertoire d’installation et que les utilisateurs peuvent installer l’application n’importe où sur l’ordinateur. Si l’application écrit une valeur de Registre hklm\software\companyname\install [path], puis met à jour cette valeur avec l’emplacement d’installation de l’application, le seul moyen pour vous de migrer correctement les données est de définir une variable d’environnement. Exemple :

<environment>
   <variable name="INSTALLPATH">
      <script>MigXmlHelper.GetStringContent("Registry","\software\companyname\install [path]")</script>
   </variable>
</environment>

Puis, vous pouvez utiliser une règle include comme suit. Vous pouvez utiliser les Fonctions <script> pour réaliser des tâches similaires.

<include>
   <objectSet>
      <pattern type="File">%INSTALLPATH%\ [*.xyz]</pattern>
   </objectSet>
</include>

Vous pouvez également filtrer les valeurs de Registre qui contiennent les données dont vous avez besoin. L’exemple suivant extrait la première chaîne (avant le séparateur « , ») de la valeur de Registre Hklm\software\companyname\application\ [Path].

<environment>
   <variable name="APPPATH">
        <objectSet>
           <content filter='MigXmlHelper.ExtractDirectory (",", "1")'>
             <objectSet>
                <pattern type="Registry">Hklm\software\companyname\application\ [Path]</pattern>
              </objectSet>
            </content>
        </objectSet>
    </variable>
</environment>

Exemple de scénario 2

Dans ce scénario, vous voulez migrer cinq fichiers nommés File1.txt, File2.txt etc. à partir de %SYSTEMDRIVE%\data\userdata\dir1\dir2\. Pour ce faire, vous devez disposer d’un fichier .xml contenant la règle <include> suivante :

<include>
   <objectSet>
      <pattern type="File">%SYSTEMDRIVE%\data\userdata\dir1\dir2 [File1.txt]</pattern>
      <pattern type="File">%SYSTEMDRIVE%\data\userdata\dir1\dir2 [File2.txt]</pattern>
      <pattern type="File">%SYSTEMDRIVE%\data\userdata\dir1\dir2 [File3.txt]</pattern>
      <pattern type="File">%SYSTEMDRIVE%\data\userdata\dir1\dir2 [File4.txt]</pattern>
      <pattern type="File">%SYSTEMDRIVE%\data\userdata\dir1\dir2 [File5.txt]</pattern>
   </objectSet>
</include>

Au lieu de taper le chemin d’accès cinq fois, vous pouvez créer une variable pour l’emplacement :

<environment>
   <variable name="DATAPATH">
      <text>%SYSTEMDRIVE%\data\userdata\dir1\dir2 </text>
      </variable>
</environment>

Vous pouvez ensuite spécifier la variable dans une règle <include> :

<include>
   <objectSet>
      <pattern type="File">%DATAPATH% [File1.txt]</pattern>
      <pattern type="File">%DATAPATH% [File2.txt]</pattern>
      <pattern type="File">%DATAPATH% [File3.txt]</pattern>
      <pattern type="File">%DATAPATH% [File4.txt]</pattern>
      <pattern type="File">%DATAPATH% [File5.txt]</pattern>
   </objectSet>
</include>

<exclude>

L’élément <exclude> détermine quels objets ne seront pas migrés, sauf si un élément <include> plus spécifique migre un objet. S’il existe un élément <include> et un élément <exclude> pour le même objet, celui-ci sera inclus. Pour chaque élément <exclude>, il peut exister plusieurs éléments <objectSet> enfants.

• Nombre d’occurrences : illimité

• Éléments parents : <rules>

• Éléments enfants : <objectSet>

• Fonctions d’assistance : vous pouvez utiliser les Fonctions de filtrage <include> et <exclude> suivantes avec cet élément : CompareStringContent, IgnoreIrrelevantLinks, AnswerNo, NeverRestore et SameRegContent.

Syntaxe :

<exclude filter="appel_script">

</exclude>

L’exemple suivant est extrait du fichier MigUser.xml :

<exclude>
   <objectSet>
      <pattern type="File">%CSIDL_MYMUSIC%\* [*]</pattern>
      <pattern type="File">%CSIDL_MYPICTURES%\* [*]</pattern>
      <pattern type="File">%CSIDL_MYVIDEO%\* [*]</pattern>
   </objectSet>
</exclude>

<excludeAttributes>

Vous pouvez utiliser l’élément <excludeAttributes> pour déterminer quels paramètres associés à un objet ne sont pas migrés. En cas de conflits entre les éléments <includeAttributes> et <excludeAttributes>, le modèle le plus spécifique détermine quels paramètres ne sont pas migrés. Si un objet n’a pas d’élément <includeAttributes> ou <excludeAttributes>, tous ses paramètres sont migrés.

• Nombre d’occurrences : illimité

• Éléments parents : <rules>

• Éléments enfants : <objectSet>

Syntaxe :

<excludeAttributes attributes="Security|TimeFields|Security,TimeFields">

</excludeAttributes>

Exemple :

<migration urlid="https://www.microsoft.com/migration/1.0/migxmlext/miguser">
<!-- This component migrates My Video files -->
   <component type="System" context="System">
      <displayName>System Data</displayName>
         <role role="Data">
            <rules>
<!-- Include all of the text files, which are immediately in the drive where the operating system is installed -->
               <include>
                  <objectSet>
                     <pattern type="File">%SYSTEMDRIVE%\ [*.txt]</pattern>
                  </objectSet>
               </include>
<!-- Exclude the time stamps from the text file starting with the letter a -->
               <excludeAttributes attributes="TimeFields">
                  <objectSet>
                     <pattern type="File">%SYSTEMDRIVE%\ [a*.txt]</pattern>
                  </objectSet>
               </excludeAttributes>
<!-- include the time stamps from the text file aa.txt -->
               <includeAttributes attributes="TimeFields">
                  <objectSet>
                     <pattern type="File">%SYSTEMDRIVE%\ [aa.txt]</pattern>
                  </objectSet>
               </includeAttributes>
<!-- Logoff the user after loadstate successfully completed. -->
               <externalProcess when="post-apply">
                  <commandLine>
                     logoff
                  </commandLine>
               </externalProcess>
         </rules>
   </role>
<!-- Migrate 
   all doc files from the system
   all power point files
   all visio design files 
   all my c++ program files -->
   <extensions>
      <extension>DOC</extension>
      <extension>PPT</extension>
      <extension>VXD</extension>
      <extension>PST</extension>
      <extension>CPP</extension>
   </extensions>
</component>
</migration>

<extensions>

L’élément <extensions> est un conteneur pour un ou plusieurs éléments <extension>.

• Nombre d’occurrences : zéro ou une

• Éléments parents : <component>

• Éléments enfants requis : <extension>

Syntaxe :

<extensions>

<extensions>

<extension>

Vous pouvez utiliser l’élément <extension> pour spécifier des documents portant une extension particulière.

• Nombre d’occurrences : illimité

• Éléments parents : <extensions>

• Éléments enfants : aucun

Syntaxe :

<extension>extension_nom_fichier</extension>

Par exemple, si vous voulez migrer tous les fichiers *.doc depuis l’ordinateur source, le fait de spécifier le code suivant sous l’élément <component> :

<extensions> 
        <extension>doc</extension> 
<extensions> 

revient à spécifier le code suivant sous l’élément <rules> :

<include> 
        <objectSet> 
                <script>MigXmlHelper.GenerateDrivePatterns ("* [*.doc]", "Fixed")</script> 
        </objectSet> 
</include>

Pour obtenir un autre exemple d’utilisation de l’élément <extension>, voir l’exemple donné pour l’élément <excludeAttributes>.

<externalProcess>

Vous pouvez utiliser l’élément <externalProcess> pour exécuter une ligne de commande au cours du processus de migration. Par exemple , vous voudrez peut-être exécuter une commande à la fin du processus LoadState.

• Nombre d’occurrences : illimité

• Éléments parents : <rules>

• Éléments enfants requis : <commandLine>

Syntaxe :

<externalProcess when="pre-scan|scan-success|post-scan|pre-apply|apply-success|post-apply">

</externalProcess>

Pour obtenir un exemple d’utilisation de l’élément <externalProcess>, voir l’exemple donné pour l’élément <excludeAttributes>.

<icon>

Il s’agit d’un élément interne de l’Outil de migration utilisateur (USMT). N’utilisez pas cet élément.

<include>

L’élément <include> détermine ce qui doit être migré, sauf s’il existe une règle <exclude> plus spécifique. Vous pouvez définir un script plus spécifique afin d’étendre la définition de ce que vous voulez collecter. Pour chaque élément <include>, il peut exister plusieurs éléments <objectSet>.

• Nombre d’occurrences : illimité

• Éléments parents : <rules>

• Élément enfant requis : <objectSet>

• Fonctions d’assistance : vous pouvez utiliser les Fonctions de filtrage <include> et <exclude> suivantes avec cet élément : CompareStringContent, IgnoreIrrelevantLinks, AnswerNo et NeverRestore.

Syntaxe :

<include filter="appel_script">

</include>

L’exemple suivant est extrait du fichier MigUser.xml :

<component type="Documents" context="User">
   <displayName _locID="miguser.myvideo">My Video</displayName>
      <paths>
         <path type="File">%CSIDL_MYVIDEO%</path>
      </paths>
      <role role="Data">
         <detects>           
            <detect>
               <condition>MigXmlHelper.DoesObjectExist("File","%CSIDL_MYVIDEO%")</condition>
            </detect>
         </detects>
         <rules>
               <include filter='MigXmlHelper.IgnoreIrrelevantLinks()'>                  <objectSet>                     <pattern type="File">%CSIDL_MYVIDEO%\* [*]</pattern>                  </objectSet>               </include>
               <merge script="MigXmlHelper.DestinationPriority()">
                  <objectSet>
                     <pattern type="File">%CSIDL_MYVIDEO% [desktop.ini]</pattern>
                  </objectSet>
            </merge>
         </rules>
      </role>
    </component>

Fonctions de filtrage <include> et <exclude>

Les fonctions suivantes renvoient une valeur booléenne. Vous pouvez les utiliser pour migrer certains objets selon que certaines conditions sont remplies.

• AnswerNo

  Ce filtre retourne toujours la valeur FALSE.

  Syntaxe : AnswerNo ()

• CompareStringContent

  Syntaxe : CompareStringContent("contenu_chaîne","type_comparaison")

  Paramètre	Obligatoire ?	Valeur
  contenu_chaîne	Oui	Chaîne avec laquelle effectuer la comparaison.
  type_comparaison	Oui	Une chaîne. Utilisez l’une des valeurs suivantes : Equal (ne respecte pas la casse). Cette fonction retourne la valeur TRUE si la représentation sous forme de chaîne de l’objet actuellement traité par le moteur de migration est identique à StringContent. NULLor any other value. Cette fonction retourne la valeur TRUE si la représentation sous forme de chaîne de l’objet actuellement traité par le moteur de migration ne correspond pas à StringContent.

• IgnoreIrrelevantLinks

  Ce filtre élimine les fichiers .lnk qui pointent vers un objet qui n’est pas valide sur l’ordinateur de destination. Notez que le filtrage a lieu sur l’ordinateur de destination, de sorte que tous les fichiers .lnk files seront enregistrées dans le magasin au cours de l’opération ScanState. Ils seront ensuite éliminés lorsque vous exécuterez l’outil LoadState.

  Syntaxe : IgnoreIrrelevantLinks ()

  Exemple :

  <include filter='MigXmlHelper.IgnoreIrrelevantLinks()'>
       <objectSet>
            <pattern type="File">%CSIDL_COMMON_VIDEO%\* [*]</pattern>
       </objectSet>
  </include>
  

• NeverRestore

  Vous pouvez utiliser cette fonction pour collecter les objets spécifiés sur l’ordinateur source, sans les migrer ensuite vers l’ordinateur de destination. Lorsque vous exécutez l’outil ScanState, cette fonction a la valeur TRUE. Lorsque vous exécutez l’outil LoadState, cette fonction a la valeur FALSE. Vous voudrez peut-être utiliser cette fonction pour vérifier la valeur d ’un objet sur l’ordinateur de destination, sans pour autant migrer cet objet vers l’ordinateur de destination.

  Syntaxe : NeverRestore()

  Dans l’exemple qui suit, HKCU\Control Panel\International [Locale] sera inclus dans le magasin, mais ne sera pas migré vers l’ordinateur de destination :

  <include filter="MigXmlHelper.NeverRestore()">
     <objectSet>
        <pattern type="Registry">HKCU\Control Panel\International [Locale]</pattern>
     </objectSet>
  </include>
  

<includeAttributes>

Vous pouvez utiliser l’élément <includeAttributes> pour déterminer si certains paramètres associés à un objet seront migrés avec l’objet lui-même. En cas de conflits entre les éléments <includeAttributes> et <excludeAttributes>, le modèle le plus spécifique détermine quels paramètres seront migrés. Si un objet n’a pas d’élément <includeAttributes> ou <excludeAttributes>, tous ses paramètres seront migrés.

• Nombre d’occurrences : illimité

• Éléments parents : <rules>

• Éléments enfants : <objectSet>

Syntaxe :

<includeAttributes attributes="Security|TimeFields|Security,TimeFields">

<includeAttributes>

Pour obtenir un exemple d’utilisation de l’élément <includeAttributes>, voir l’exemple donné pour l’élément <excludeAttributes>.

<library>

Il s’agit d’un élément interne de l’Outil de migration utilisateur (USMT). N’utilisez pas cet élément.

<location>

L’élément <location> définit l’emplacement de l’élément <object>.

• Nombre d’occurrences : une fois pour chaque élément <object>

• Éléments parents : <object>

• Éléments enfants : <script>

Syntaxe :

<location type="ID_type">emplacement_objet</location>

L’exemple suivant est extrait du fichier MigApp.xml :

<addObjects>
   <object>
      <location type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [UpgradeVersion]</location>
      <attributes>DWORD</attributes>
      <bytes>0B000000</bytes>
   </object>
   <object>
      <location type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [Lang]</location>
      <attributes>DWORD</attributes>
      <bytes>00000000</bytes>
   </object>
</addObjects>

<locationModify>

Vous pouvez utiliser l’élément <locationModify> pour modifier l’emplacement et le nom d’un objet avant sa migration vers l’ordinateur de destination L’élément <locationModify> est traité uniquement lorsque l’outil LoadState est exécuté sur l’ordinateur de destination. En d’autres termes, cet élément est ignoré par l’outil ScanState. L’élément <locationModify> crée le dossier approprié sur l’ordinateur de destination s’il n’existe pas déjà.

Nombre d’occurrences : illimité

• Éléments parents : <rules>

• Élément enfant requis : <objectSet>

• Fonctions d’assistance : vous pouvez utiliser les Fonctions <locationModify> suivantes avec cet élément : ExactMove, RelativeMove et Move.

Syntaxe :

<locationModify script="appel_script">

<locationModify>

L’exemple suivant est extrait du fichier MigApp.xml :

<locationModify script="MigXmlHelper.RelativeMove('%CSIDL_APPDATA%\Microsoft\Office','%CSIDL_APPDATA%')">
   <objectSet>
      <pattern type="File">%CSIDL_APPDATA%\Microsoft\Office\ [Access10.pip]</pattern>
   </objectSet>
</locationModify>

Fonctions <locationModify>

Les fonctions suivantes modifient l’emplacement des objets pendant leur migration lorsque l’élément <locationModify> est utilisé. Ces fonctions sont appelées pour chaque objet que l’élément <ObjectSet> parent énumère. L’élément <locationModify> crée le dossier approprié sur l’ordinateur de destination s’il n’existe pas déjà.

• ExactMove

  La fonction ExactMove déplace tous les objets mis en correspondance par l’élément <ObjectSet> parent dans l’emplacement_encodé_objet donné. Vous pouvez utiliser cette fonction lorsque vous souhaitez déplacer un seul fichier vers un emplacement différent sur l’ordinateur de destination. Si l’emplacement de destination est un nœud, tous les objets sources correspondants seront écrits dans le nœud sans sous-répertoires. Si l’emplacement de destination est une feuille, le moteur de migration migrera tous les objets sources correspondants dans le même emplacement. En cas de collision, les algorithmes de collision habituels s’appliqueront.

  Syntaxe : ExactMove(emplacement_encodé_objet)

  Paramètre	Obligatoire ?	Valeur
  emplacement_encodé_objet	Oui	Spécification d’emplacements de destination de tous les objets sources.

  Exemple :

  <locationModify script="MigXmlHelper.ExactMove('HKCU\Keyboard Layout\Toggle [HotKey]')">
       <objectSet>
            <pattern type="Registry">HKCU\Keyboard Layout\Toggle []</pattern>
       </objectSet>
  </locationModify>
  

• Move

  La fonction Move déplace les objets vers un emplacement différent sur l’ordinateur de destination. Par ailleurs, cette fonction crée les sous-répertoires qui se trouvaient au-dessus de la CSIDL la plus longue dans le nom de l’objet source.

  Syntaxe : Move(racine_destination)

  Paramètre	Obligatoire ?	Valeur
  racine_destination	Oui	Emplacement vers lequel les objets sources seront déplacés. Si nécessaire, cette fonction crée les sous-répertoires qui étaient au-dessus de la CSIDL la plus longue dans le nom de l’objet source.

• RelativeMove

  Vous pouvez utiliser la fonction RelativeMove pour collecter et déplacer des données. Notez que vous pouvez utiliser des variables d’environnement dans les nœuds sources et racines, mais qu’elles peuvent être définies différemment sur les ordinateurs source et de destination.

  Syntaxe : RelativeMove(racine_source,racine_destination)

  Paramètre	Obligatoire ?	Valeur
  SourceRoot	Oui	Emplacement depuis lequel les objets seront déplacés. Chacun des objets sources énumérés par l’élément <ObjectSet> parent qui ne se trouve pas à cet emplacement ne sera pas déplacé.
  racine_destination	Oui	Emplacement vers lequel les objets sources seront déplacés sur l’ordinateur de destination. Si nécessaire, cette fonction créera les sous-répertoires qui étaient au-dessus de racine_source.

  Exemple :

  <include>
     <objectSet>
        <pattern type="File">%CSIDL_COMMON_FAVORITES%\* [*]</pattern>
     <objectSet>
  </include>
  <locationModify script="MigXmlHelper.RelativeMove('%CSIDL_COMMON_FAVORITES%','%CSIDL_COMMON_FAVORITES%')">
       <objectSet>
            <pattern type="File">%CSIDL_COMMON_FAVORITES%\* [*]</pattern>
       </objectSet>
  </locationModify>
  

<_locDefinition>

Il s’agit d’un élément interne de l’Outil de migration utilisateur (USMT). N’utilisez pas cet élément.

<manufacturer>

L’élément <manufacturer> définit le fabricant du composant mais n’affecte pas la migration.

• Nombre d’occurrences : zéro ou une

• Éléments parents : <component>

• Éléments enfants : aucun

Syntaxe :

<manufacturer>nom</manufacturer>

<merge>

L’élément <merge> détermine ce qui se passe en cas de collision. Une collision se produit lorsqu’un objet qui est migré est déjà présent sur l’ordinateur de destination. Si vous ne spécifiez pas cet élément, par défaut pour le Registre, l’objet source remplace l’objet de destination dans le Registre et par défaut pour les fichiers, le fichier source est renommé « nom_fichier_origine(1).extension_origine ». Cet élément indique seulement ce qui doit être fait en cas de collision. Il n’inclut aucun objet. Par conséquent, pour migrer des objets, vous devez spécifier des règles <include> avec l’élément <merge>. Si une collision est détectée lors du traitement d’un objet, l’Outil de migration utilisateur (USMT) sélectionne la règle de fusion la plus spécifique et l’applique pour résoudre le conflit. Par exemple, si une règle <merge> C:\* [*] est définie sur <sourcePriority> et une règle <merge> C:\subfolder\* [*] est définie sur <destinationPriority>, l’Outil de migration utilisateur (USMT) utilise la règle <destinationPriority> car elle est la plus spécifique.

Pour obtenir un exemple de cet élément, voir Comment l’élément <merge> fonctionne-t-il en cas de conflits sur l’ordinateur de destination ?.

• Nombre d’occurrences : illimité

• Éléments parents : <rules>

• Élément enfant requis : <objectSet>

• Fonctions d’assistance : vous pouvez utiliser les Fonctions <merge> suivantes avec cet élément : SourcePriority, DestinationPriority, FindFilePlaceByPattern, LeafPattern, NewestVersion, HigherValue() et LowerValue().

Syntaxe :

<merge script="appel_script">

<merge>

L’exemple suivant est extrait du fichier MigUser.xml :

<rules>
   <include filter='MigXmlHelper.IgnoreIrrelevantLinks()'>
      <objectSet>
         <pattern type="File">%CSIDL_MYVIDEO%\* [*]</pattern>
      </objectSet>
   </include>
   <merge script="MigXmlHelper.DestinationPriority()">
      <objectSet>
         <pattern type="File">%CSIDL_MYVIDEO% [desktop.ini]</pattern>
      </objectSet>
   </merge>
</rules>

Fonctions <merge>

Ces fonctions contrôlent la manière dont les collisions sont résolues.

• DestinationPriority

  L’objet qui se trouve sur l’ordinateur de destination est conservé et l’objet sur l’ordinateur source n’est pas migré.

  Exemple :

  <merge script="MigXmlHelper.DestinationPriority()">
       <objectSet>
            <pattern type="Registry">HKCU\Software\Microsoft\Office\9.0\PhotoDraw\ [MyPictures]</pattern>
            <pattern type="Registry">HKCU\Software\Microsoft\Office\9.0\PhotoDraw\Settings\ [PicturesPath]</pattern>
            <pattern type="Registry">HKCU\Software\Microsoft\Office\9.0\PhotoDraw\Settings\ [AdditionalPlugInPath]</pattern>
       </objectSet>
  </merge>
  

• FindFilePlaceByPattern

  La fonction FindFilePlaceByPattern enregistre les fichiers avec un compteur à incrémentation si une collision se produit. Il s’agit d’une chaîne qui contient chacune des structures suivantes : <F>, <E>, <N> dans n’importe quel ordre.

  Syntaxe : FindFilePlaceByPattern(modèle_fichier)

  Paramètre	Obligatoire ?	Valeur
  modèle_fichier	Oui	<F> sera remplacé pour le nom de fichier d’origine. <N> sera remplacé par un compteur à incrémentation jusqu’à ce qu’il n’y ait plus de collision avec les objets sur l’ordinateur de destination. <E> sera remplacé par l’extension de nom de fichier. d’origine. Par exemple, <F> (<N>).<E> renommera le fichier source MyDocument.doc en MyDocument (1).doc sur l’ordinateur de destination.

• NewestVersion

  La fonction NewestVersion résout les conflits sur l’ordinateur de destination en fonction de la version du fichier.

  Syntaxe : NewestVersion(balise_version)

  Paramètre	Obligatoire ?	Valeur
  balise_version	Oui	Champ de version qui sera vérifié. Il peut s’agir de « FileVersion » ou « ProductVersion ». Le fichier dont la version balise_version est la plus élevée détermine quels conflits seront résolus en fonction de la version du fichier. Par exemple, si MonFichier.txt contient FileVersion 1 et le même fichier sur l’ordinateur de destination contient FileVersion 2, le fichier de l’ordinateur de destination sera conservé.

• HigherValue()

  Vous pouvez utiliser cette fonction pour fusionner des valeurs de Registre. Les valeurs de Registre seront évaluées en tant que valeurs numériques ; celle ayant la valeur la plus élevée déterminera quelles valeurs de Registre seront fusionnées.

• LowerValue()

  Vous pouvez utiliser cette fonction pour fusionner des valeurs de Registre. Les valeurs de Registre seront évaluées en tant que valeurs numériques ; celle ayant la valeur la plus faible déterminera quelles valeurs de Registre seront fusionnées.

• SourcePriority

  Indique que l’objet doit être migré depuis l’ordinateur source puis être supprimé de cet ordinateur.

  Exemple :

  <merge script="MigXmlHelper.SourcePriority()">
   <objectSet>
     <pattern type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Publisher [UpgradeVersion]</pattern>
     <pattern type="Registry">%HklmWowSoftware%\Microsoft\Office\11.0\Common\Migration\Publisher [UpgradeVersion]</pattern>
     <pattern type="Registry">%HklmWowSoftware%\Microsoft\Office\10.0\Common\Migration\Publisher [UpgradeVersion]</pattern>
   </objectSet>
  </merge>
  

<migration>

L’élément <migration> est le seul élément racine d’un fichier .xml de migration et est obligatoire Chaque fichier .xml doit avoir un ID d’URL de migration unique. L’ID d’URL de chaque fichier que vous spécifiez sur la ligne de commande doit être unique. En effet, l’Outil de migration utilisateur (USMT) utilise l’ID d’URL pour définir les composants dans le fichier. Par exemple, vous devez spécifier ce qui suit au début de chaque fichier : <CustomFileName> est le nom du fichier ; par exemple « CustomApp ».

• Nombre d’occurrences : une

• Éléments parents : aucun

• Éléments enfants requis : <component>

• Éléments enfants facultatifs : <library>, <namedElements>

Syntaxe :

<migration urlid="*ID_URL/*Nom">

<migration>

L’exemple suivant est extrait du fichier MigApp.xml :

<migration urlid="https://www.microsoft.com/migration/1.0/migxmlext/migapp">
</migration>

MigXMLHelper.FileProperties

Cette fonction d’assistance de filtrage peut être utilisée pour filtrer les fichiers de migration en fonction des attributs de taille de fichier et de date.

<component context="System"  type="Application">
<displayName>File_size</displayName>
<role role="Data">

   <rules>
        <include filter='MigXmlHelper.FileProperties("dateAccessed","range","2008/05/15-2008/05/17")'>
         <objectSet>
         <pattern type="File">%SYSTEMDRIVE%\DOCS\* [*]</pattern>
         </objectSet>
      </include>
   </rules>
</role>
</component>

<namedElements>

Vous pouvez utiliser l’élément <namedElements> pour définir des éléments nommés. Vous pouvez utiliser ces éléments dans tout composant de votre fichier .xml. Pour obtenir un exemple d’utilisation de cet élément, voir le fichier MigApp.xml.

Syntaxe :

<namedElements>

</namedElements>

• Nombre d’occurrences : illimité

• Éléments parents : <migration>

• Éléments enfants : <environment>, <rules>, <conditions>, <detection>, <detects>, <detect>

Pour obtenir un exemple de cet élément, voir le fichier MigApp.xml.

<object>

L’élément <object> représente un fichier ou une clé de Registre.

• Nombre d’occurrences : illimité

• Éléments parents : <addObjects>

• Éléments enfants requis : <location>, <attributes>

• Éléments enfants facultatifs : <bytes>

Syntaxe :

<object>

</object>

L’exemple suivant est extrait du fichier MigApp.xml :

<addObjects>
   <object>
      <location type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [UpgradeVersion]</location>
      <attributes>DWORD</attributes>
      <bytes>0B000000</bytes>
   </object>
   <object>
      <location type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [Lang]</location>
      <attributes>DWORD</attributes>
      <bytes>00000000</bytes>
      </object>
</addObjects>

<objectSet>

L’élément <objectSet> contient une liste de modèles d’objets ; par exemple des chemins d’accès aux fichiers, des emplacements de Registre, etc. Chaque élément <conditions> enfant sera tout d’abord évalué. Si tous les éléments <conditions> enfants renvoient FALSE, l’élément <objectSet> aura pour valeur un ensemble vide. Pour chaque élément parent, il peut exister plusieurs éléments <objectSet>.

• Nombre d’occurrences : illimité

• Éléments parents : <variable>, <content>, <include>, <exclude>, <merge>, <contentModify>, <locationModify>, <destinationCleanup>, <includeAttributes>, <excludeAttributes>, <unconditionalExclude>, <detect>

• Éléments enfants requis : <script> ou <pattern>

• Éléments enfants facultatifs : <content>, <conditions>, <condition>

Syntaxe :

<objectSet>

</objectSet>

L’exemple suivant est extrait du fichier MigUser.xml :

<component type="Documents" context="User">
   <displayName _locID="miguser.mymusic">My Music</displayName>
      <paths>
         <path type="File">%CSIDL_MYMUSIC%</path>
      </paths>
   <role role="Data">
      <detects>           
      <detect>
         <condition>MigXmlHelper.DoesObjectExist("File","%CSIDL_MYMUSIC%")</condition>
      </detect>
   </detects>           
   <rules>
      <include filter='MigXmlHelper.IgnoreIrrelevantLinks()'>
         <objectSet>            <pattern type="File">%CSIDL_MYMUSIC%\* [*]</pattern>         </objectSet>
      </include>
      <merge script="MigXmlHelper.DestinationPriority()">
         <objectSet>            <pattern type="File">%CSIDL_MYMUSIC%\ [desktop.ini]</pattern>         </objectSet>
      </merge>
   </rules>
   </role>
</component>

<path>

Il s’agit d’un élément interne de l’Outil de migration utilisateur (USMT). N’utilisez pas cet élément.

<paths>

Il s’agit d’un élément interne de l’Outil de migration utilisateur (USMT). N’utilisez pas cet élément.

<pattern>

Vous pouvez utiliser cet élément pour spécifier plusieurs objets. Vous pouvez spécifier plusieurs éléments <pattern> pour chaque élément <objectSet>. Ils seront ensuite combinés. Si vous spécifiez des fichiers vous voudrez peut-être plutôt utiliser GenerateDrivePatterns avec <script>. GenerateDrivePatterns est plus ou moins équivalent à une règle <pattern>, sans spécification de la lettre de lecteur. Par exemple, les deux lignes de code suivantes sont similaires :

<pattern type="File">C:\Folder\* [Sample.doc]</pattern>
<script>MigXmlHelper.GenerateDrivePatterns("\Folder\* [Sample.doc]","Fixed"</script>

• Nombre d’occurrences : illimité

• Éléments parents : <objectSet>

• Éléments enfants : aucun mais chemin_accès[objet] doit être valide.

Syntaxe :

<pattern type="ID_type">chemin_accès[objet]</pattern>

Exemple :

• Pour migrer une clé de Registre unique :

  <pattern type="Registry">HKLM\Software\Microsoft\Windows\CurrentVersion\Internet Settings\Cache [Persistent]</pattern>
  

• Pour migrer le dossier EngineeringDrafts et tous les sous-dossiers du lecteur C: :

  <pattern type="File">C:\EngineeringDrafts\* [*]</pattern>
  

• Pour migrer uniquement le dossier EngineeringDrafts du lecteur C:, sans les sous-dossiers :

  <pattern type="File"> C:\EngineeringDrafts\ [*]</pattern>
  

• Pour migrer les fichier Sample.doc à partir de C:\EngineeringDrafts :

  <pattern type="File"> C:\EngineeringDrafts\ [Sample.doc]</pattern>
  

• Pour migrer le fichier Sample.doc quel que soit son emplacement sur le lecteur C:, utilisez l’élément pattern de la façon suivante. Si le lecteur C: contient plusieurs fichiers portant le même nom, tous ces fichiers seront migrés.

  <pattern type="File"> C:\* [Sample.doc] </pattern>
  

• Pour obtenir d’autres exemples d’utilisation de cet élément, voir Exclure des fichiers et des paramètres, Réacheminer les fichiers et les paramètres, Inclure des fichiers et des paramètres et Exemples de fichiers XML personnalisés.

<processing>

Vous pouvez utiliser cet élément pour exécuter un script à un moment précis au cours du processus de migration. Aucune valeur de retour n’est attendue des scripts que vous spécifiez et si des valeurs sont retournées, elles sont ignorées.

• Nombre d’occurrences : illimité

• Éléments parents : <rules>

• Élément enfant requis : <script>

Syntaxe :

<processing when="pre-scan|scan-success|post-scan|pre-apply|apply-success|post-apply">

</processing>

<plugin>

Il s’agit d’un élément interne de l’Outil de migration utilisateur (USMT). N’utilisez pas cet élément.

<role>

L’élément <role> est requis dans un fichier .xml personnalisé. En spécifiant l’élément <role>, vous pouvez créer un composant concret. Le composant sera défini par les paramètres spécifiés au niveau de <component> et avec le rôle que vous spécifiez ici.

• Nombre d’occurrences : chaque <component> peut avoir un, deux ou trois éléments <role> enfants.

• Éléments parents : <component>, <role>

• Éléments enfants requis : <rules>

• Éléments enfants facultatifs : <environment>, <detection>, <component>, <role>, <detects>, <plugin>,

Syntaxe :

<role role="Container|Binaries|Settings|Data">

</role>

<component context="UserAndSystem" type="Application">
  <displayName _locID="migapp.msoffice2003">Microsoft Office 2003</displayName> 
  <environment name="GlobalEnv" /> 
  <role role="Container">
    <detection name="AnyOffice2003Version" /> 
    <detection name="FrontPage2003" /> 
    <!-- 
 Office 2003 Common Settings 
  --> 
    <component context="UserAndSystem" type="Application">

L’exemple suivant est extrait du fichier MigUser.xml. Pour obtenir d’autres exemples, voir le fichier MigApp.xml :

<component type="System" context="User">
   <displayName _locID="miguser.startmenu">Start Menu</displayName>
   <paths>
      <path type="File">%CSIDL_STARTMENU%</path>
   </paths>
   <role role="Settings">
      <detects>           
         <detect>
            <condition>MigXmlHelper.DoesObjectExist("File","%CSIDL_STARTMENU%")</condition>
         </detect>
      </detects>           
   <rules>
      <include filter='MigXmlHelper.IgnoreIrrelevantLinks()'>
         <objectSet>
            <pattern type="File">%CSIDL_STARTMENU%\* [*]</pattern>
         </objectSet>
      </include>
      <merge script="MigXmlHelper.DestinationPriority()">
         <objectSet>
            <pattern type="File">%CSIDL_STARTMENU% [desktop.ini]</pattern>
            <pattern type="File">%CSIDL_STARTMENU%\* [*]</pattern>
         </objectSet>
      </merge>
   </rules>
   </role>
</component>

<rules>

L’élément <rules> est requis dans un fichier .xml personnalisé. Cet élément contient des règles qui seront exécutées au cours de la migration si l’élément <component> parent est sélectionné, sauf si l’élément <conditions> enfant, s’il est présent, a la valeur FALSE. Pour chaque élément <rules>, il peut exister plusieurs éléments <rules> enfants.

• Nombre d’occurrences : illimité

• Éléments parents : <role>, <rules>, <namedElements>

• Éléments enfants requis : <include>

• Éléments enfants facultatifs : <rules>, <exclude>, <unconditionalExclude>,<merge>, <contentModify>, <locationModify>, <destinationCleanup>, <addObjects>, <externalProcess>, <processing>, <includeAttributes>, <excludeAttributes>, <conditions>, <detects>

Syntaxe :

<rules name="ID" context="User|System|UserAndSystem">

</rules>

L’exemple suivant est extrait du fichier MigUser.xml :

<component type="Documents" context="User">
   <displayName _locID="miguser.mymusic">My Music</displayName>
      <paths>
         <path type="File">%CSIDL_MYMUSIC%</path>
      </paths>
   <role role="Data">
      <detects>           
      <detect>
         <condition>MigXmlHelper.DoesObjectExist("File","%CSIDL_MYMUSIC%")</condition>
      </detect>
   </detects>           
   <rules>
      <include filter='MigXmlHelper.IgnoreIrrelevantLinks()'>
         <objectSet>
            <pattern type="File">%CSIDL_MYMUSIC%\* [*]</pattern>
         </objectSet>
      </include>
      <merge script="MigXmlHelper.DestinationPriority()">
         <objectSet>
            <pattern type="File">%CSIDL_MYMUSIC%\ [desktop.ini]</pattern>
         </objectSet>
      </merge>
   </rules>
   </role>
</component>

<script>

La valeur de retour qui est requise par <script> dépend de l’élément parent.

Nombre d’occurrences : une pour <variable>, illimité pour <objectSet> et<processing>

Éléments parents : <objectSet>, <variable>, <processing>

Éléments enfants : aucun

Syntaxe et fonctions d’assistance :

• Syntaxe générale : <script>script_avec_arguments</script>

• Vous pouvez utiliser Fonctions <script> lorsque <script> se trouve dans <variable>.

  Syntaxe : <script>MigXmlHelper.GetStringContent("type_objet","modèle_emplacement_encodé", "développer_contenu")</script>

  Exemple : <script>MigXMLHelper.GetStringContent("Registry","HKLM\Software\MyApp\Installer [EXEPATH]")</script>

• Vous pouvez utiliser Fonctions <script> lorsque <script> se trouve dans <objectSet>.

  Syntaxe : <script>MigXmlHelper.GenerateUserPatterns("type_objet","modèle_emplacement_encodé","traiter_utilisateur_actuel")</script>

  Exemple : <script>MigXmlHelper.GenerateUserPatterns ("File","%USERPROFILE%\* [*.doc]", "FALSE")</script>

• Vous pouvez utiliser Fonctions <script> lorsque <script> se trouve dans <objectSet>.

  Syntaxe : <script>MigXmlHelper.GenerateDrivePatterns("segment_modèle","type_lecteur")</script>

  Exemple : <script>MigXmlHelper.GenerateDrivePatterns("* [sample.doc]", "Fixed")</script>

• Vous pouvez utiliser les Fonctions <script> avec les éléments <script> qui se trouvent dans des éléments <processing> : AskForLogoff, ConvertToShortFileName, KillExplorer, RemoveEmptyDirectories, RestartExplorer, RegisterFonts, StartService, StopService, SyncSCM.

  Syntaxe : <script>MigXmlHelper.script_exécution</script>

  Exemple : <script>MigXmlHelper.KillExplorer()</script>

Exemples :

Pour migrer le fichier Sample.doc à partir de n’importe quel lecteur de l’ordinateur source, utilisez <script> de la manière suivante. Si plusieurs fichiers portent le même nom, tous seront migrés.

<script>MigXmlHelper.GenerateDrivePatterns("* [sample.doc]", "Fixed")</script> 

Pour obtenir d’autres exemples d’utilisation de cet élément, voir Exclure des fichiers et des paramètres, Réacheminer les fichiers et les paramètres, Réacheminer les fichiers et les paramètres et Exemples de fichiers XML personnalisés.

Fonctions <script>

Vous pouvez utiliser les fonctions suivantes avec l’élément <script> :

• Fonctions de génération de chaînes et de modèles

• Scripts d’exécution simples

Fonctions de génération de chaînes et de modèles

Ces fonctions retournent une chaîne ou un modèle.

• GetStringContent

  Vous pouvez utiliser GetStringContent avec les éléments <script> qui se trouvent dans des éléments <variable>. Si possible, cette fonction retourne la représentation sous forme de chaîne de l’objet donné. Sinon, NULL est retourné. Pour les objets de type fichier, cette fonction retourne toujours NULL.

  Syntaxe : GetStringContent("type_objet","modèle_emplacement_encodé", "développer_contenu")

  Paramètre	Obligatoire ?	Valeur
  type_objet	Oui	Type de l’objet. Peut être Registry ou Ini (pour un fichier .ini).
  modèle_emplacement_encodé	Oui	Si le type d’objet est Registry, modèle_emplacement_encodé doit être un chemin d’accès au Registre valide. Par exemple, HKLM\SOFTWARE\MyKey[]. Si le type d’objet est Ini, modèle_emplacement_encodé doit être au format suivant : chemin_accès_fichier_Ini|nom_section[nom_paramètre]
  développer_contenu	Non (valeur par défaut = TRUE)	Peut être TRUE ou FALSE. Si la valeur est FALSE, l’emplacement donné ne sera pas développé avant d’être retourné.

  Exemple :

  <variable name="MSNMessengerInstPath">
  <script>MigXmlHelper.GetStringContent("Registry","%HklmWowSoftware%\Microsoft\MSNMessenger [InstallationDirectory]")</script>
  </variable>
  

• GenerateDrivePatterns

  La fonction GenerateDrivePatterns parcourt tous les lecteurs disponibles et sélectionne ceux qui correspondent au type de lecteur demandé. Elle concatène ensuite les lecteurs sélectionnés avec la partie finale de segment_modèle pour former un modèle de fichier entièrement encodé. Par exemple, si segment_modèle a la valeur Path [file.txt] et type_lecteur la valeur Fixed, cette fonction génère C:\Path [file.txt] et d’autres modèles s’il existe d’autres lecteurs fixes en plus de C:. Vous ne pouvez pas spécifier de variables d’environnement avec cette fonction. Vous pouvez utiliser GenerateDrivePatterns avec des éléments <script> qui se trouvent dans des éléments <objectSet> eux-mêmes dans des éléments <include>/<exclude>.

  Syntax : GenerateDrivePatterns("segment_modèle","type_lecteur")

  Paramètre	Obligatoire ?	Valeur
  segment_modèle	Oui	Suffixe d’un modèle encodé. Ce suffixe sera concaténé avec une spécification de lecteur, comme « c:\ », pour former un Spécification d’emplacements complet. Par exemple, « * [*.doc] ». segment_modèle ne peut pas être une variable d’environnement.
  type_lecteur	Oui	Type de lecteur pour lequel les modèles doivent être générés. Vous pouvez spécifier l’une des valeurs suivantes : Fixed CDROM Removable Remote

  Pour obtenir un exemple de cet élément, voir le dernier composant du fichier MigUser.xml.

• GenerateUserPatterns

  Cette fonction parcourt tous les utilisateurs qui sont migrés, à l’exclusion de l’utilisateur actuellement traité si <traiter_utilisateur_actuel> a la valeur FALSE et développe le modèle spécifié dans le contexte de chaque utilisateur. Par exemple, si les utilisateurs A, B et C ont des profils dans C:\Documents and Settings), en appelant GenerateUserPattens('File','%userprofile% [*.doc]','TRUE'), la fonction d’assistance génère les trois modèles suivants :

  • « "C:\Documents and Settings\A\* [*.doc] »

  • « "C:\Documents and Settings\B\* [*.doc] »

  • « C:\Documents and Settings\C\* [*.doc] »

  Syntaxe : GenerateUserPatterns("type_objet","modèle_emplacement_encodé","traiter_utilisateur_actuel")

  Paramètre	Obligatoire ?	Valeur
  type_objet	Oui	Définit le type de l’objet. Peut être Fichier ou Registre.
  modèle_emplacement_encodé	Oui	Spécification d’emplacements. Les variables d’environnement sont autorisées.
  traiter_utilisateur_actuel	Oui	Peut être TRUE ou FALSE. Indique si les modèles doivent être générés pour l’utilisateur actuel.

  Exemple :

  Si GenerateUserPattens(’File’,’%userprofile% [*.doc]’,’FALSE’) est appelé alors que l’Outil de migration utilisateur (USMT) traite l’utilisateur A, cette fonction génère alors des modèles pour les utilisateurs B et C. Vous pouvez utiliser cette fonction d’assistance pour créer des règles complexes. Par exemple, pour migrer tous les fichiers .doc à partir de l’ordinateur source ; mais si l’utilisateur X n’est pas migré, ne migrez alors aucun fichier .doc à partir du profil de l’utilisateur X.

  Un exemple de code pour ce scénario est fourni ci-dessous. Le premier élément <rules> migre tous les fichiers .doc sur l’ordinateur source à l’exception de ceux qui se trouvent dans C:\Documents and Settings. Le deuxième élément <rules> migre tous les fichiers .doc à partir de C:\Documents and Settings à l’exception des fichiers .doc qui se trouvent dans les profils des autres utilisateurs. Dans la mesure où le second élément <rules> sera traité dans chaque contexte utilisateur migré, le résultat final sera le comportement souhaité. Le résultat final est celui qui était attendu.

  <rules context="System">
    <include>
      <objectSet>
        <script>MigXmlHelper.GenerateDrivePatterns ("* [*.doc]", "Fixed")</script>
      </objectSet>
    </include>
    <exclude>
      <objectSet>
        <pattern type="File">%ProfilesFolder%\* [*.doc]</pattern>
      </objectSet>
    </exclude>
  </rules>
  <rules context="User">
    <include>
      <objectSet>
        <pattern type="File">%ProfilesFolder%\* [*.doc]</pattern>
      </objectSet>
    </include>
    <exclude>
      <objectSet>
        <script>MigXmlHelper.GenerateUserPatterns ("File","%userprofile%\* [*.doc]", "FALSE")</script>
      </objectSet>
    </exclude>
  </rules>
  

MigXmlHelper.GenerateDocPatterns

Cette fonction d’assistance appelle l’outil de recherche de documents qui recherche dans le système tous les fichiers pouvant être migrés. Cet outil peut être appelé dans le contexte système ou utilisateur de manière à cibler la recherche.

 <!-- This component migrates data in user context -->
  <component type="Documents" context="User">
    <displayName>MigDocUser</displayName>
    <role role="Data">
      <rules>
        <include filter='MigXmlHelper.IgnoreIrrelevantLinks()'>
          <objectSet>
            <script>MigXmlHelper.GenerateDocPatterns ("false")</script>
          </objectSet>
        </include>
        <exclude>
          <objectSet>
           <script>MigXmlHelper.GenerateDocPatterns ("false", "false", "false")</script>
          </objectSet>
        </exclude>
      </rules>
    </role>
  </component>

Scripts d’exécution simples

Les scripts suivants n’ont aucune valeur de retour. Vous pouvez utiliser les erreurs suivantes avec des éléments <script> qui se trouvent dans des éléments <processing>.

• AskForLogoff(). Invite l’utilisateur à se déconnecter à la fin de la migration. Exemple :

       <processing when="apply-success">
            <script>MigXmlHelper.AskForLogoff()</script>
       </processing>
  

• ConvertToShortFileName(emplacement_encodé_Registre). Si emplacement_encodé_Registre est le chemin d’accès complet d’un fichier existant, cette fonction attribue au fichier son nom court et met à jour la valeur de Registre.

• KillExplorer(). Arrête Explorer.exe pour le contexte utilisateur actuel. Cela permet d’accéder à certaines clés et certains fichiers qui restent ouverts lorsque Explorer.exe est en cours d’exécution. Exemple :

       <processing when="pre-apply">
            <script>MigXmlHelper.KillExplorer()</script>
       </processing>
  

• RegisterFonts(emplacement_encodé_fichier). Enregistre la police donnée ou toutes les polices dans le répertoire indiqué. Exemple :

  <processing when="apply-success">
  <script>MigXmlHelper.RegisterFonts("%CSIDL_COMMON_FONTS%")</script>
  </processing>
  

• **RemoveEmptyDirectories (modèle_encodé_répertoire).**Supprime tout répertoire vide qui correspond à modèle_encodé_répertoire sur l’ordinateur de destination.

• RestartExplorer(). Redémarre Explorer.exe à la fin de la migration. Exemple :

       <processing when="post-apply">
            <script>MigXmlHelper.RestartExplorer()</script>
       </processing>
  

• StartService (nom_service, param_facultatif_1, param_facultatif2,…). Démarre le service identifié par nom_service. nom_service est la sous-clé dans HKLM\System\CurrentControlSet\Services qui contient les données du service donné. Les paramètres facultatifs, le cas échéant, seront transmis à l’API de StartService. Pour plus d’informations, visitez ce site Web de Microsoft.

• StopService (nom_service). Arrête le service identifié par nom_service. nom_service est la sous-clé dans HKLM\System\CurrentControlSet\Services qui contient les données du service indiqué.

• SyncSCM(nom_court_service). Lit la valeur de Start dans le Registre (HKLM\System\CurrentControlSet\Services\ServiceShortName [Start]) après qu’elle a été modifiée par le moteur de migration, puis synchronise Service Control Manager (SCM) avec la nouvelle valeur.

<text>

Vous pouvez utiliser l’élément <text> afin de définir une valeur pour toute variable d’environnement qui se trouve à l’intérieur de l’un des fichiers .xml de migration.

• Nombre d’occurrences : une fois dans chaque élément <variable>.

• Éléments parents : <variable>

• Éléments enfants : aucun

Syntaxe :

<text>texte_normal</text>

Exemple :

<variable name="QuickTime5or6DataSys">
  <text>%CSIDL_COMMON_APPDATA%\QuickTime</text> 
</variable>

<unconditionalExclude>

L’élément <unconditionalExclude> exclut de la migration les fichiers et valeurs de Registre spécifiés, sans tenir compte des autres règles include présentes dans les fichiers .xml de migration ou dans le fichier Config.xml. Les objets déclarés ici ne sont pas migrés car cet élément est prioritaire sur toutes les autres règles. Par exemple, même s’il existe des règles <include> explicites pour inclure les fichiers .mp3, si vous spécifiez de les exclure avec cette option, ils ne seront pas migrés.

Utilisez cet élément si vous voulez exclure tous les fichiers .mp3 de l’ordinateur source. Ou, si vous sauvegardez C:\UserData à l’aide d’une autre méthode, vous pouvez exclure l’intégralité du dossier de la migration. Vous devez toutefois procéder avec précaution lors de l’utilisation de cet élément, car si une application a besoin d’un fichier que vous excluez, elle risque de ne pas fonctionner correctement sur l’ordinateur de destination.

• Nombre d’occurrences : illimité.

• Éléments parents : <rules>

• Éléments enfants : <objectSet>

Syntaxe :

<unconditionalExclude></unconditionalExclude>

Le fichier .xml suivant exclut tous les fichiers .mp3 de la migration. Pour obtenir d’autres exemples d’utilisation de cet élément, voir Exclure des fichiers et des paramètres.

<migration urlid="https://www.microsoft.com/migration/1.0/migxmlext/excludefiles">
  <component context="System" type="Documents">
        <displayName>Test</displayName>
        <role role="Data">
            <rules>
             <unconditionalExclude>
                        <objectSet>
    <script>MigXmlHelper.GenerateDrivePatterns ("* [*.mp3]", "Fixed")</script>
                        </objectSet> 
             </unconditionalExclude>
            </rules>
        </role>
    </component>
</migration>

<variable>

L’élément <variable> est requis dans un élément <environment>. Pour chaque élément <variable>, il doit exister un élément <objectSet>, <script> ou <text>. Le contenu de l’élément <variable> attribue une valeur de texte à la variable d’environnement. Trois options sont disponibles pour cet élément :

1. Si l’élément <variable> contient un élément <text>, la valeur de l’élément <variable> est la valeur de l’élément <text>.

2. Si l’élément <variable> contient un élément <script> et si l’appel du script produit une chaîne non null, la valeur de l’élément <variable> est le résultat de l’appel du script.

3. Si l’élément <variable> contient un élément <objectSet> et si l’évaluation de l’élément <objectSet> produit au moins un modèle d’objet, la valeur du premier objet qui correspond au modèle d’objet résultant est la valeur de l’élément <variable>.

• Nombre d’occurrences : illimité

• Éléments parents : <environment>

• Éléments enfants requis : <text>, <script> ou <objectSet>

Syntaxe :

<variable name="ID" remap=TRUE|FALSE>

</variable>

L’exemple suivant est extrait du fichier MigApp.xml :

<environment>
   <variable name="HklmWowSoftware">
      <text>HKLM\Software</text>
   </variable>
   <variable name="WinZip8or9or10Exe">
      <script>MigXmlHelper.GetStringContent("Registry","%HklmWowSoftware%\Microsoft\Windows\CurrentVersion\App Paths\winzip32.exe []")</script>
   </variable>
</environment>

<version>

L’élément <version> définit la version du composant mais n’affecte pas la migration.

• Nombre d’occurrences : zéro ou une

• Éléments parents : <component>

• Éléments enfants : aucun

Syntaxe :

<version>version_composant</version>

Exemple :

<version>4.*</version>

<windowsObjects>

L’élément <windowsObjects> est réservé à l’usage interne de l’Outil de migration utilisateur (USMT). N’utilisez pas cet élément.

Annexe

Spécification d’emplacements

• Spécification d’emplacements encodés. L’emplacement encodé utilisé dans toutes les fonctions d’assistance est une représentation non ambiguë sous forme de chaîne du nom d’un objet Il se compose de la partie nœud, suivie de façon facultative de la feuille mise entre crochets. Cela fait une nette différence entre les nœuds et les feuilles.

  Par exemple, spécifiez le fichier C:\Windows\Notepad.exe de la manière suivante : c:\Windows[Notepad.exe]. De même, spécifiez le fichier C:\Windows\System32 de la manière suivante : c:\Windows\System32. (Notez l’absence de crochets [].)

  La représentation du Registre est très similaire. La valeur par défaut d’une clé de Registre est représentée par des crochets vides ([]). Par exemple, la valeur par défaut de la clé de Registre HKLM\SOFTWARE\MyKey est HKLM\SOFTWARE\MyKey[].

• Spécification de modèles d’emplacements. Un modèle d’emplacement est spécifié de la même manière qu’un emplacement réel. La seule différence est que la partie nœud et la partie feuille acceptent toutes deux des modèles. Toutefois, un modèle au niveau du nœud ne s’étend pas à la feuille.

  Par exemple, le modèle c:\Windows\* met en correspondance le répertoire Windows et tous ses sous-répertoires. Par contre, il ne met pas en correspondance les fichiers de ces répertoires. Pour mettre également en correspondance les fichiers, vous devez spécifier c:\Windows\*[*].

Fonctions internes de l’Outil de migration utilisateur (USMT)

Les fonctions suivantes sont réservées à l’usage interne de l’Outil de migration utilisateur (USMT). Ne les utilisez pas dans un fichier .xml.

• AntiAlias

• ConvertScreenSaver

• ConvertShowIEOnDesktop

• ConvertToOfficeLangID

• MigrateActiveDesktop

• MigrateAppearanceUPM

• MigrateDisplayCS

• MigrateDisplaySS

• MigrateIEAutoSearch

• MigrateMouseUPM

• MigrateSoundSysTray

• MigrateTaskBarSS

• SetPstPathInMapiStruc

Balises de version valides

Vous pouvez utiliser les balises de version suivantes avec différentes fonctions d’assistance :

• « CompanyName »

• « FileDescription »

• « FileVersion »

• « InternalName »

• « LegalCopyright »

• « OriginalFilename »

• « ProductName »

• « ProductVersion »

Les balises de version suivantes contiennent des valeurs qui peuvent être comparées :

• « FileVersion »

• « ProductVersion »

Voir aussi

Autres ressources

Informations de référence XML de l’outil USMT