Biblioteca de elementos XML

Visão geral

Este tópico descreve os elementos XML e as funções auxiliares que você pode empregar para criar arquivos .xml de migração para serem usados com a USMT (ferramenta de transferência do Windows). Supõe-se que você conhece as noções básicas do XML. .

Neste tópico

Além dos elementos XML e das funções auxiliares, este tópico descreve como especificar locais e padrões de locais, funções para uso exclusivo interno da USMT e as marcas de versão que você pode usar com as funções auxiliares.

• Elementos e funções auxiliares

• Apêndice

  • Especificando locais

  • Funções internas da USMT

  • Marcas de versão válidas

Elementos e funções auxiliares

A tabela a seguir descreve os elementos XML e as funções auxiliares que você pode usar com a USMT.

<addObjects>

O elemento <addObjects> emula a existência de um ou mais objetos no computador de origem. Os elementos filhos <object> fornecem os detalhes dos objetos emulados. Se o conteúdo for um elemento <script>, o resultado da invocação será uma matriz de objetos.

• Número de ocorrências: ilimitado

• Elementos pais: <rules>

• Elementos filhos necessários: <object> Além disso, você deve especificar <location> e <attributes> como elementos filhos deste elemento <object>.

• Elementos filhos opcionais: <conditions>, <condition>, <script>

Sintaxe:

<addObjects>

</addObjects>

Veja a seguir um exemplo do arquivo 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>

O elemento <attributes> define os atributos de um arquivo ou chave do Registro.

• Número de ocorrências: uma para cada <object>

• Elementos pais: <object>

• Elementos filhos: nenhum

Sintaxe:

<attributes>Conteúdo</attributes>

Veja a seguir um exemplo do arquivo MigApp.xml:

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

<bytes>

Você deve especificar o elemento <bytes> apenas para arquivos porque, se <location> corresponder a uma chave do Registro ou a um diretório, <bytes> será ignorado.

• Número de ocorrências: zero ou uma

• Elementos pais: <object>

• Elementos filhos: nenhum

Sintaxe:

<bytes string="Yes|No" expand="Yes|No">Conteúdo</bytes>

Veja a seguir um exemplo do arquivo MigApp.xml:

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

<commandLine>

Você pode querer usar o elemento <commandLine> se desejar iniciar ou parar um serviço ou aplicativo antes ou depois de executar as ferramentas ScanState e LoadState.

• Número de ocorrências: ilimitado

• Elementos pais: <externalProcess>

• Elementos filhos: nenhum

Sintaxe:

<commandLine>CommandLineString</commandLine>

<component>

O elemento <component> é necessário em um arquivo .xml personalizado. Este elemento define a construção mais básica de um arquivo .xml de migração. Por exemplo, no arquivo MigApp.xml, "Microsoft® Office 2003" é um componente que contém outro componente, "Microsoft Office Access® 2003". Você pode usar os elementos filhos para definir o componente.

Um componente pode ser aninhado dentro de outro componente; ou seja, o elemento <component> pode ser um filho do elemento <role> no elemento <component> em dois casos: 1) quando o elemento pai <component> é um contêiner ou 2) se o elemento filho <component> tem a mesma função que o elemento pai <component>.

• Número de ocorrências: ilimitado

• Elementos pais: <migration>, <role>

• Elementos filhos necessários: <role>, <displayName>

• Elementos filhos opcionais: <manufacturer>, <version>, <description>, <paths>, <icon>, <environment>, <extensions>

Sintaxe:

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

hidden="Yes|No">

</component>

Por exemplo, veja qualquer um dos arquivos .xml de migração padrão.

<condition>

Embora o elemento <condition> sob os elementos <detect>, <objectSet> e <addObjects> tenham suporte, recomendamos que você não use-o. Esse elemento pode ser preterido em versões futuras da USMT, exigindo que você reescreva seus scripts. Recomendamos que, se você precisar usar uma condição dentro dos elementos <objectSet> e <addObjects>, use o elemento <conditions> mais avançado, que permite formular instruções boolianas complexas.

O elemento <condition> tem um resultado booliano. Você pode usar esse elemento para especificar as condições em que o elemento pai será avaliado. Se qualquer uma das presentes condições retornar FALSE, o elemento pai não será avaliado.

• Número de ocorrências: ilimitado.

• Elementos pais: <conditions>, <detect>, <objectSet>, <addObjects>

• Elementos filhos: nenhum

• Funções auxiliares: você pode usar as seguintes Funções <condition> com este elemento: DoesOSMatch, IsNative64Bit(), IsOSLaterThan, IsOSEarlierThan, DoesObjectExist, DoesFileVersionMatch, IsFileVersionAbove, IsFileVersionBelow, IsSystemContext, DoesStringContentEqual, DoesStringContentContain, IsSameObject, IsSameContent e IsSameStringContent.

Sintaxe:

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

Por exemplo,

No exemplo de código a seguir, os elementos <condition>, A e B, são unidos pelo operador AND porque estão em seções <conditions> separadas. Por exemplo:

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

Entretanto, no código de exemplo a seguir, os elementos <condition>, A e B, são unidos pelo operador OR porque estão na mesma seção <conditions>.

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

Funções <condition>

As funções <condition> retornam um valor booliano. Você pode usar estes elementos nas condições <addObjects>.

• Funções de versão do sistema operacional

• Funções de conteúdo do objeto

Funções de versão do sistema operacional

• DoesOSMatch

  Todas as ocorrências diferenciam maiúsculas de minúsculas.

  Sintaxe: DoesOSMatch("OSType","OSVersion")

  Configuração	Obrigatória?	Valor
  OSType	Sim	O único valor válido para esta configuração é NT. No entanto, observe que você deve definir essa configuração para as funções <condition> funcionarem corretamente.
  OSVersion	Sim	A versão principal, versão secundária, número de compilação e versão de disquete de serviço corrigido separados por pontos. Por exemplo, 5.0.2600.Service Pack 1. Você também pode determinar uma especificação parcial da versão com um padrão. Por exemplo, 5.0.*.

  Por exemplo:

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

• IsNative64Bit

  A função IsNative64Bit retorna TRUE se o processo de migração estiver sendo executado como um processo de 64 bits nativo; ou seja, um processo sendo executado em um sistema de 64 bits sem o WOW (Windows on Windows). Caso contrário, retorna FALSE.

• IsOSLaterThan

  Todas as comparações diferenciam maiúsculas de minúsculas.

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

  Configuração	Obrigatória?	Valor
  OSType	Sim	Pode ser 9x ou NT. Se OSType não coincidir com o tipo de sistema operacional atual, retorna FALSE. Por exemplo, se o sistema operacional atual é baseado no Windows NT e OSType é "x9", o resultado será FALSE.
  OSVersion	Sim	A versão principal, versão secundária, número de compilação e versão de disquete de serviço corrigido separados por pontos. Por exemplo, 5.0.2600.Service Pack 1. Você também pode determinar uma especificação parcial da versão, mas nenhum padrão é permitido. Por exemplo, 5.0. A função IsOSLaterThan retorna TRUE quando o sistema operacional atual é posterior ou igual a OSVersion.

  Por exemplo:

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

• IsOSEarlierThan

  Todas as comparações diferenciam maiúsculas de minúsculas.

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

  Configuração	Obrigatória?	Valor
  OSType	Sim	Pode ser 9x ou NT. Se OSType não coincidir com o tipo de sistema operacional atual, retorna FALSE. Por exemplo, se o sistema operacional atual é baseado no Windows NT e OSType é "x9", o resultado será FALSE.
  OSVersion	Sim	A versão principal, versão secundária, número de compilação e versão de disquete de serviço corrigido separados por pontos. Por exemplo, 5.0.2600.Service Pack 1. Você também pode determinar uma especificação parcial da versão, mas nenhum padrão é permitido. Por exemplo, 5.0. A função IsOSEarlierThan retorna TRUE se o sistema operacional atual for anterior a OSVersion.

Funções de conteúdo do objeto

• DoesObjectExist

  A função DoesObjectExist retorna TRUE se existir qualquer objeto que corresponda ao padrão de localização. Caso contrário, retorna FALSE. O padrão de localização é expandido antes de tentar a enumeração.

  Sintaxe: DoesObjectExist("ObjectType","EncodedLocationPattern")

  Configuração	Obrigatória?	Valor
  ObjectType	Sim	Define o tipo de objeto. Pode ser Arquivo ou Registro.
  EncodedLocationPattern	Sim	O Especificando locais. Variáveis de ambiente são permitidas.

  Para obter um exemplo desse elemento, veja o arquivo MigApp.xml.

• DoesFileVersionMatch

  A verificação padrão diferencia maiúsculas de minúsculas.

  Sintaxe: DoesFileVersionMatch("EncodedFileLocation","VersionTag","VersionValue")

  Configuração	Obrigatória?	Valor
  EncodedFileLocation	Sim	O Especificando locais do arquivo que será verificado. Variáveis de ambiente são permitidas.
  VersionTag	Sim	O valor da Marcas de versão válidas que será verificada.
  VersionValue	Sim	Um padrão de caideia de caracteres. Por exemplo, "Microsoft *".

  Por exemplo:

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

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

• IsFileVersionAbove

  A função IsFileVersionAbove retorna TRUE quando a versão do arquivo é superior a VersionValue.

  Sintaxe: IsFileVersionAbove("EncodedFileLocation","VersionTag","VersionValue")

  Configuração	Obrigatória?	Valor
  EncodedFileLocation	Sim	O Especificando locais do arquivo que será verificado. Variáveis de ambiente são permitidas.
  VersionTag	Sim	O valor da Marcas de versão válidas que será verificada.
  VersionValue	Sim	O valor a ser comparado. Você não pode especificar um padrão.

• IsFileVersionBelow

  Sintaxe: IsFileVersionBelow("EncodedFileLocation","VersionTag","VersionValue")

  Configuração	Obrigatória?	Valor
  EncodedFileLocation	Sim	O Especificando locais do arquivo que será verificado. Variáveis de ambiente são permitidas.
  VersionTag	Sim	O valor da Marcas de versão válidas que será verificada.
  VersionValue	Sim	O valor a ser comparado. Você não pode especificar um padrão.

• IsSystemContext

  A função IsSystemContext retorna TRUE se o contexto atual for "System". Caso contrário, retorna FALSE.

  Sintaxe: IsSystemContext()

• DoesStringContentEqual

  A função DoesStringContentEqual retorna TRUE quando a representação de cadeia de caracteres do objeto fornecido é idêntica a StringContent.

  Sintaxe: DoesStringContentEqual("ObjectType","EncodedLocation","StringContent")

  Configuração	Obrigatória?	Valor
  ObjectType	Sim	Define o tipo de objeto. Pode ser Arquivo ou Registro.
  EncodedLocationPattern	Sim	A Especificando locais do objeto que será examinado. Você pode especificar variáveis de ambiente.
  StringContent	Sim	A cadeia de caracteres que será verificada.

  Por exemplo:

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

• DoesStringContentContain

  A função DoesStringContentContain retorna TRUE quando há pelo menos uma ocorrência de StrToFind na representação de cadeia de caracteres do objeto.

  Sintaxe: DoesStringContentContain("ObjectType","EncodedLocation","StrToFind")

  Configuração	Obrigatória?	Valor
  ObjectType	Sim	Define o tipo de objeto. Pode ser Arquivo ou Registro.
  EncodedLocationPattern	Sim	A Especificando locais do objeto que será examinado. Você pode especificar variáveis de ambiente.
  StrToFind	Sim	Uma cadeia de caracteres que será pesquisada dentro do conteúdo de determinado objeto.

• IsSameObject

  A função IsSameObject retorna TRUE se as localizações codificadas fornecidas resolverem o mesmo objeto físico. Caso contrário, retorna FALSE.

  Sintaxe: IsSameObject("ObjectType","EncodedLocation1","EncodedLocation2")

  Configuração	Obrigatória?	Valor
  ObjectType	Sim	Define o tipo de objeto. Pode ser Arquivo ou Registro.
  EncodedLocation1	Sim	A Especificando locais do primeiro objeto. Você pode especificar variáveis de ambiente.
  EncodedLocation2	Sim	A Especificando locais do segundo objeto. Você pode especificar variáveis de ambiente.

  Por exemplo:

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

• IsSameContent

  A função IsSameContent retorna TRUE se os objetos determinados têm o mesmo conteúdo. Caso contrário, retorna FALSE. O conteúdo será comparado byte a byte.

  Sintaxe: IsSameContent("ObjectType1","EncodedLocation1","ObjectType2","EncodedLocation2")

  Configuração	Obrigatória?	Valor
  ObjectType1	Sim	Define o tipo do primeiro objeto. Pode ser Arquivo ou Registro.
  EncodedLocation1	Sim	A Especificando locais do primeiro objeto. Você pode especificar variáveis de ambiente.
  ObjectType2	Sim	Define o tipo do segundo objeto. Pode ser Arquivo ou Registro.
  EncodedLocation2	Sim	A Especificando locais do segundo objeto. Você pode especificar variáveis de ambiente.

• IsSameStringContent

  A função IsSameStringContent retorna TRUE se os objetos determinados têm o mesmo conteúdo. Caso contrário, retorna FALSE. O conteúdo será interpretado como uma cadeia de caracteres.

  Sintaxe: IsSameStringContent("ObjectType1","EncodedLocation1","ObjectType2","EncodedLocation2")

  Configuração	Obrigatória?	Valor
  ObjectType1	Sim	Define o tipo do primeiro objeto. Pode ser Arquivo ou Registro.
  EncodedLocation1	Sim	A Especificando locais do primeiro objeto. Você pode especificar variáveis de ambiente.
  ObjectType2	Sim	Define o tipo do segundo objeto. Pode ser Arquivo ou Registro.
  EncodedLocation2	Sim	A Especificando locais do segundo objeto. Você pode especificar variáveis de ambiente.

<conditions>

O elemento <conditions> retorna um resultado booliano que é usado para especificar as condições em que o elemento pai é avaliado. A USMT avalia elementos filhos e junta seus resultados usando os operadores AND ou OR, de acordo com o parâmetro operation.

• Número de ocorrências: ilimitado dentro de outro elemento <conditions>. Limitado a uma ocorrência em <detection>, <rules>, <addObjects> e <objectSet>

• Elementos pais: <conditions>, <detection>, <environment>, <rules>, <addObjects> e <objectSet>

• Elementos filhos: <conditions>, <condition>

Sintaxe:

<conditions operation="AND|OR">

</conditions>

Veja a seguir um exemplo do arquivo MigApp.xml:

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

<content>

Você pode usar o elemento <content> para especificar uma lista de padrões de objeto para obter um objeto definido do computador de origem. Cada <objectSet> dentro de um elemento <content> é avaliado. Para cada lista de padrões do objeto resultante, os objetos que correspondem a ele são enumerados e seu conteúdo é filtrado pelo parâmetro filter. A matriz de cadeia de caracteres resultante é a saída para o elemento <content>. O script de filtro retorna uma matriz de locais. O elemento pai <objectSet> pode conter vários elementos filhos <content>.

• Número de ocorrências: ilimitado

• Elementos pais: <objectSet>

• Elementos filhos: <objectSet>

• Funções auxiliares: você pode usar as seguintes Funções <content> com estes elementos: ExtractSingleFile, ExtractMultipleFiles e ExtractDirectory.

Sintaxe:

<content filter="ScriptInvocation">

</content>

Funções <content>

As funções a seguir geram padrões fora do conteúdo de um objeto. Essas funções são chamadas para cada objeto que o elemento pai <ObjectSet> é enumerar.

• ExtractSingleFile

  Se o valor do Registro é MULTI-SZ, apenas o primeiro segmento é processado. O padrão retornado é a localização codificada para o arquivo que deve existir no sistema. Se a especificação está correta no valor do Registro, mas o arquivo não existe, essa função retorna NULL.

  Sintaxe: ExtractSingleFile(Separators,PathHints)

  Configuração	Obrigatória?	Valor
  Separators	Sim	Uma lista de possíveis separadores que pode seguir a especificação de arquivo neste nome de valor do Registro. Por exemplo, se o conteúdo for "C:\Windows\Notepad.exe,-2", o separador é uma vírgula. Você pode especificar NULL.
  PathHints	Sim	Uma lista de caminhos extras, separados por ponto e vírgula (;), onde a função irá procurar um arquivo que corresponda ao conteúdo atual. Por exemplo, se o conteúdo é "Notepad.exe" e o caminho é a variável de ambiente %Path%, a função encontra Notepad.exe em %windir% e retorna "c:\Windows [Notepad.exe]". Você pode especificar NULL.

  Por exemplo:

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

  e

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

• ExtractMultipleFiles

  A função ExtractMultipleFiles retorna vários padrões, um para cada arquivo que se encontra no conteúdo do valor determinado do Registro. Se o valor do Registro for MULTI-SZ, o separador de MULTI-SZ será considerado um separador por padrão. Portanto, para MULTI-SZ, o argumento <Separators> deve ser NULL.

  Os padrões retornados são localizações codificadas para arquivos que devem existir no computador de origem. Se a especificação está correta no valor do Registro, mas o arquivo não existe, ela não será incluída na lista resultante.

  Sintaxe: ExtractMultipleFiles(Separators,PathHints)

  Configuração	Obrigatória?	Valor
  Separators	Sim	Uma lista de possíveis separadores que pode seguir a especificação de arquivo neste nome de valor do Registro. Por exemplo, se o conteúdo for "C:\Windows\Notepad.exe,-2", o separador é uma vírgula. Este parâmetro deve ser NULL quando processamento MULTI-SZ do Registro valores.
  PathHints	Sim	Uma lista de caminhos extras, separados por ponto e vírgula (;), onde a função irá procurar um arquivo que corresponda ao conteúdo atual. Por exemplo, se o conteúdo é "Notepad.exe" e o caminho é a variável de ambiente %Path%, a função encontra Notepad.exe em %windir% e retorna "c:\Windows [Notepad.exe]". Você pode especificar NULL.

• ExtractDirectory

  A função ExtractDirectory retorna um padrão que é a localização codificada para um diretório que deve existir no computador de origem. Se a especificação está correta no valor do Registro, mas o diretório não existe, a função retorna NULL. Se está processando um valor do Registro que é um MULTI-SZ, apenas o primeiro segmento será processado.

  Sintaxe: ExtractDirectory(Separators,LevelsToTrim,PatternSuffix)

  Configuração	Obrigatória?	Valor
  Separators	Não	Uma lista de possíveis separadores que pode seguir a especificação de arquivo neste nome de valor do Registro. Por exemplo, se o conteúdo for "C:\Windows\Notepad.exe,-2", o separador é uma vírgula. Você deve especificar NULL quando processar os valores do Registro MULTI-SZ.
  LevelsToTrim	Sim	O número de níveis para excluir do final da especificação do diretório. Use esta função para extrair um diretório raiz quando você tem um valor do Registro que aponta dentro desse diretório raiz em um local conhecido.
  PatternSuffix	Sim	O padrão para adicionar à especificação de diretório. Por exemplo, * [*].

  Por exemplo:

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

<contentModify>

O elemento <contentModify> modifica o conteúdo de um objeto antes de ele é gravado no computador de destino. Para cada elemento <contentModify> pode haver vários elementos <objectSet>. Esse elemento retorna o novo conteúdo do objeto que está sendo processado.

• Número de ocorrências: ilimitado

• Elementos pais: <rules>

• Elementos filhos necessários: <objectSet>

• Funções auxiliares: você pode usar as seguintes Funções <contentModify> com estes elementos: ConvertToDWORD, ConvertToString, ConvertToBinary, KeepExisting, OffsetValue, SetValueByTable, MergeMultiSzContent e MergeDelimitedContent.

Sintaxe:

<contentModify script="ScriptInvocation">

</contentModify>

Funções <contentModify>

As seguintes funções alteram o conteúdo dos objetos conforme eles são migrados. Essas funções são chamadas para cada objeto que o elemento pai <ObjectSet> é enumerar.

• ConvertToDWORD

  A função ConvertToDWORD converte o conteúdo de valores do Registro que são enumerados pelo elemento pai <ObjectSet> para DWORD. Por exemplo, ConvertToDWORD converterá a cadeia de caracteres "1" no DWORD 0x00000001. Se a conversão falhar, o valor de DefaultValueOnError será aplicado.

  Sintaxe: ConvertToDWORD(DefaultValueOnError)

  Configuração	Obrigatória?	Valor
  DefaultValueOnError	Não	O valor que será gravado no nome do valor se a conversão falhar. Você pode especificar NULL e 0 será gravado se a conversão falhar.

• ConvertToString

  A função ConvertToString converte o conteúdo dos valores do Registro que correspondem ao elemento pai <ObjectSet> em uma cadeia de caracteres. Por exemplo, ele converterá o DWORD 0x00000001 na cadeia de caracteres "1". Se a conversão falhar, o valor de DefaultValueOnError será aplicado.

  Sintaxe: ConvertToString(DefaultValueOnError)

  Configuração	Obrigatória?	Valor
  DefaultValueOnError	Não	O valor que será gravado no nome do valor se a conversão falhar. Você pode especificar NULL e 0 será gravado se a conversão falhar.

  Por exemplo:

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

• ConvertToBinary

  A função ConvertToBinary converte o conteúdo dos valores do Registro que correspondem ao elemento pai <ObjectSet> em um tipo binário.

  Sintaxe: ConvertToBinary ()

• OffsetValue

  A função OffsetValue adiciona ou subtrai o Valor do valor do objeto migrado e depois grava o resultado de volta no valor do Registro no computador de destino. Por exemplo, se o objeto migrado for um DWORD com um valor 14, e o Valor for "-2", o valor do Registro será 12 no computador de destino.

  Sintaxe: OffsetValue(Valor)

  Configuração	Obrigatória?	Valor
  Valor	Sim	A representação de cadeia de caracteres de um valor numérico. Ele pode ser positivo ou negativo. Por exemplo, OffsetValue(2).

• SetValueByTable

  A função de SetValueByTable corresponde o valor do computador de origem à tabela de origem. Se o valor existe, o valor equivalente na tabela de destino será aplicado. Se o valor não existe, ou se a tabela de destino não tem nenhum valor equivalente, DefaultValueOnError será aplicado.

  Sintaxe: SetValueByTable(SourceTable,DestinationTable,DefaultValueOnError)

  Configuração	Obrigatória?	Valor
  SourceTable	Sim	Uma lista de valores separados por vírgulas que são possíveis para os valores de Registro de origem.
  DestinationTable	Não	Uma lista de valores traduzidos separados por vírgulas.
  DefaultValueOnError	Não	O valor que será aplicado ao computador de destino se 1) o valor do computador de origem não corresponder a SourceTable ou 2) DestinationTable não tiver nenhum valor equivalente. Se DefaultValueOnError for NULL, o valor não será alterado no computador de destino.

• KeepExisting

  Você pode usar a função KeepExisting quando há conflitos no computador de destino. Esta função irá manter (não substituir) os atributos especificados para o objeto que está no computador de destino.

  Sintaxe: KeepExisting("OptionString","OptionString","OptionString",…)

  Configuração	Obrigatória?	Valor
  OptionString	Sim	OptionString pode ser Security, TimeFields, ou FileAttrib:Letter. Você pode especificar um de cada tipo de OptionStrings. Não especifique vários OptionStrings com o mesmo valor. Se você fizer isso, a opção à extrema direita daquele tipo será mantida. Por exemplo, não especifique ("FileAttrib:H", "FileAttrib:R") porque apenas Somente leitura será avaliado. Em vez disso, especifique ("FileAttrib:HR") e ambos os atributos Hidden e Read-only serão mantidos no computador de destino. Segurança. Mantém o descritor de segurança do objeto de destino se ele existir. TimeFields. Mantém os carimbos de data/hora do objeto de destino. Este parâmetro é apenas para arquivos. FileAttrib:Letter. Mantém valor de atributo do objeto de destino, ligado ou desligado, para o conjunto de atributos do arquivo especificado. Este parâmetro é apenas para arquivos. Os itens a seguir não diferenciam maiúsculas de minúsculas, mas a USMT irá ignorar todos os valores que são inválidos, repetidos ou se houver um espaço após "FileAttrib:". Você pode especificar qualquer combinação dos seguintes atributos: A = Archive C = Compressed E = Encrypted H = Hidden I = Not Content Indexed O = Offline R = Read-Only S = System T = Temporary

• MergeMultiSzContent

  A função MergeMultiSzContent mescla o conteúdo MULTI-SZ dos valores do Registro que são enumerados pelo elemento pai <ObjectSet> com o conteúdo dos valores do Registro equivalentes que já existem no computador de destino. Instruction e String removem ou adicionam conteúdo ao MULTI-SZ resultante. Elementos duplicados serão removidos.

  Sintaxe: MergeMultiSzContent (Instruction,String,Instruction,String,…)

  Configuração	Obrigatória?	Valor
  Instruction	Sim	Pode ser uma das seguintes opções: Adicionar. Adiciona a cadeia de caracteres correspondente ao MULTI-SZ resultante se ele não já estiver lá. Remover. Remove a cadeia de caracteres correspondente do MULTI-SZ resultante.
  String	Sim	A cadeia de caracteres a ser adicionada ou removida.

• MergeDelimitedContent

  A função MergeDelimitedContent mescla o conteúdo dos valores do Registro que são enumerados pelo elemento pai <ObjectSet> com o conteúdo dos valores do Registro equivalentes que já existem no computador de destino. O conteúdo é considerado uma lista de elementos separados por um dos caracteres no parâmetro Delimiters. Elementos duplicados serão removidos.

  Sintaxe: MergeDelimitedContent(Delimiters,Instruction,String,…)

  Configuração	Obrigatória?	Valor
  Delimiters	Sim	Um único caractere que será usado para separar o conteúdo do objeto que está sendo processado. O conteúdo será considerado como uma lista de elementos separados pelos Delimitadores. Por exemplo, "." irá separar a cadeia de caracteres com base em um ponto.
  Instruction	Sim	Pode um destes procedimentos: Adicionar. Adiciona String ao MULTI-SZ resultante, se ainda não estiver lá. Remover. Remove String do MULTI-SZ resultante.
  String	Sim	A cadeia de caracteres a ser adicionada ou removida.

<description>

O elemento <description> define uma descrição para o componente, mas não afeta a migração.

• Número de ocorrências: zero ou uma

• Elementos pais: <component>

• Elementos filhos: nenhum

Sintaxe:

<description>ComponentDescription</description>

O exemplo de código a seguir mostra como o elemento <description> define a descrição de "Meu componente personalizado":

<description>My custom component<description>

<destinationCleanup>

O elemento <destinationCleanup> exclui objetos, como arquivos e chaves do Registro, do computador de destino antes de aplicar os objetos do computador de origem. Este elemento é avaliado somente quando a ferramenta LoadState é executada no computador de destino. Ou seja, esse elemento é ignorado pela ferramenta ScanState.

Para cada elemento <destinationCleanup> pode haver vários elementos <objectSet>. Um uso comum desse elemento é saber se existe uma chave do Registro ausente no computador de origem e se você deseja garantir que um componente foi migrado. Nesse caso, você pode excluir todas as chaves do Registro do componente antes de migrar as chaves do Registro de origem. Isso garantirá que, se houver uma chave ausente no computador de origem, ela também estará ausente no computador de destino.

• Número de ocorrências: ilimitado

• Elementos pais: <rules>

• Elementos filhos: <objectSet> (Observe que o computador de destino exclui todos os elementos filhos.)

Sintaxe:

<destinationCleanup filter=ScriptInvocation>

</destinationCleanup>

Por exemplo:

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

Embora o elemento <detect> ainda tenha suporte, não recomendamos usá-lo porque ele pode ser substituído nas futuras versões da USMT. Nesse caso, você teria que reescrever seus scripts. Recomendamos que você use o elemento <detection>.

Você usa o elemento <detect> para determinar se o componente está presente em um sistema. Se todos os elementos filhos <detect> dentro de um elemento <detect> são resolvidos como TRUE, o elemento <detect> elemento é resolvido como TRUE. Se qualquer elemento filho <detect> for resolvido como FALSE, o elemento pai <detect> será resolvido como FALSE. Se não houver nenhuma seção de elemento <detect>, a USMT assumirá que o componente está presente.

Para cada elemento <detect>, pode haver vários elementos filhos <condition> ou elementos <objectSet>, que logicamente serão unidos por um operador OR. Se pelo menos um elemento <condition> ou <objectSet> for avaliado como TRUE, o elemento <detect> será avaliado como TRUE.

• Número de ocorrências: ilimitado

• Elementos pais: <detects>, <namedElements>

• Elementos filhos necessários: <condition>

• Elementos filhos opcionais: <objectSet>

Sintaxe:

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

</detect>

Para obter exemplos, veja os exemplos de <detection>.

<detects>

Embora o elemento <detects> ainda tenha suporte, recomendamos que você não o use porque ele pode ser substituído nas versões futuras da USMT, que podem exigir que você reescreva seus scripts. Em vez disso, recomendamos que você use o elemento <detection> se o elemento pai for <role> ou <namedElements>, e recomendamos que você use o elemento <conditions> se o elemento pai for <rules>. Usar <detection> permite formular mais claramente instruções boolianas complexas.

O elemento <detects> é um contêiner de um ou mais elementos <detect>. Se todos os elementos filhos <detect> dentro de um elemento <detects> forem resolvidos como TRUE, <detects> será resolvido como TRUE. Se qualquer um dos elementos filhos <detect> forem resolvidos como FALSE, <detects> será resolvido como FALSE. Se você não quiser escrever os elementos <detects> dentro de um componente, pode criar o elemento <detects> sob o elemento <namedElements> e fazer referência a ele. Se não houver nenhuma seção de elemento <detects>, a USMT irá assumir que o componente está presente. Os resultados de cada elemento <detects> são unidos pelo operador OR para formar a regra usada para detectar o elemento pai.

Sintaxe:

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

</detects>

• Número de ocorrências: ilimitado.

• Elementos pais: <role>, <rules>, <namedElements>

• Elementos filhos necessários: <detect>

O exemplo a seguir é do arquivo 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>

O elemento <detection> é um contêiner para um elemento <conditions>. O resultado dos elementos filhos <condition>, localizado sob o elemento <conditions>, determina o resultado deste elemento. Por exemplo, se todos os elementos filhos <conditions> dentro do elemento <detection> forem resolvidos como TRUE, o elemento <detection> será resolvido como TRUE. Se qualquer um dos elementos filhos <conditions> forem resolvidos como FALSE, o elemento <detection> será resolvido como FALSE.

Além disso, os resultados de cada seção <detection> dentro do elemento <role> são unidos pelo operador OR para formar a regra de detecção do elemento pai. Ou seja, se uma das seções <detection> for resolvida como TRUE, o elemento <role> será processado. Caso contrário, o elemento <role> não será processado.

Use o elemento <detection> no elemento <namedElements> se você não quiser escrevê-lo dentro de um componente. Então inclua uma seção correspondente do <detection> sob o elemento <role> para controlar se o componente será migrado. Se não houver uma seção <detection> de um componente, a USMT irá assumir que o componente está presente.

• Número de ocorrências: ilimitado.

• Elementos pais: <role>, <namedElements>

• Elementos filhos: <conditions>

Sintaxe:

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

</detection>

Por exemplo:

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

e

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

<displayName>

O elemento <displayName> é um campo obrigatório dentro de cada elemento <component>.

• Número de ocorrências: uma vez para cada componente

• Elementos pais: <component>

• Elementos filhos: nenhum

Sintaxe:

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

Por exemplo:

<displayName>Command Prompt settings</displayName>

<environment>

O elemento <environment> é um contêiner para elementos <variable> no qual você pode definir variáveis para usar no arquivo .xml. Todas as variáveis de ambiente definidas desta forma serão privadas. Ou seja, elas estarão disponíveis apenas para os componentes filhos e o componente no qual foram definidas. Para dois cenários de exemplo, veja Exemplos.

• Número de ocorrências: ilimitado

• Elementos pais: <role>, <component>, <namedElements>

• Elementos filhos necessários: <variable>

• Elementos filhos opcionais: <conditions>

Sintaxe:

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

</environment>

Cenário de exemplo 1

Nesse cenário, você deseja gerar a localização dos objetos em tempo de execução dependendo da configuração do computador de destino. Por exemplo, você deve fazer isso se um aplicativo grava dados no diretório onde ele está instalado, e os usuários podem instalar o aplicativo em qualquer local no computador. Se o aplicativo grava um valor do Registro hklm\software\nomedaempresa\instalar [caminho] e atualiza esse valor com o local onde o aplicativo está instalado, a única maneira para você migrar os dados necessários corretamente é definir uma variável de ambiente. Por exemplo:

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

Você pode usar uma regra de inclusão da seguinte maneira. Você pode usar qualquer uma das Funções <script> para executar tarefas semelhantes.

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

Depois, também pode filtrar valores do Registro que contêm dados que você precisa. O exemplo a seguir extrai a primeira cadeia de caracteres (antes do separador ",") no valor do Registro Hklm\software\nomedaempresa\aplicativo\ [caminho].

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

Cenário de exemplo 2:

Nesse cenário, você deseja migrar cinco arquivos chamados File1.txt, File2.txt e assim por diante, de %SYSTEMDRIVE%\data\userdata\dir1\dir2\. Para fazer isso, você deve ter a seguinte regra <include> em um arquivo .xml:

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

Em vez de digitar o caminho cinco vezes, você pode criar uma variável para o local da seguinte maneira:

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

Em seguida, você pode especificar a variável em uma regra <include> da seguinte forma:

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

O elemento <exclude> determina quais objetos não serão migrados, a menos que haja um elemento <include> mais específico que migra um objeto. Se não houver um elemento <include> e <exclude> para o mesmo objeto, o objeto será incluído. Para cada elemento <exclude> pode haver vários elementos filhos <objectSet>.

• Número de ocorrências: ilimitado

• Elementos pais: <rules>

• Elementos filhos: <objectSet>

• Funções auxiliares: você pode usar as seguintes Funções de filtro <include> e <exclude> com estes elementos: CompareStringContent, IgnoreIrrelevantLinks, AnswerNo, NeverRestore e SameRegContent.

Sintaxe:

<exclude filter="ScriptInvocation">

</exclude>

Por exemplo, do arquivo MigUser.

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

<excludeAttributes>

Você pode usar o elemento <excludeAttributes> para determinar quais parâmetros associados a um objeto não serão migrados. Se houver conflitos entre os elementos <includeAttributes> e <excludeAttributes>, o padrão mais específico determinará os padrões que não serão migrados. Se um objeto não tiver um elemento <includeAttributes> ou <excludeAttributes>, todos os seus parâmetros serão migrados.

• Número de ocorrências: ilimitado

• Elementos pais: <rules>

• Elementos filhos: <objectSet>

Sintaxe:

< excludeAttributes atributos = "Security|TimeFields|Segurança, TimeFields">

</excludeAttributes>

Exemplo:

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

O elemento <extensions> é um contêiner para um ou mais elementos <extension>.

• Número de ocorrências: zero ou uma

• Elementos pais: <component>

• Elementos filhos necessários: <extension>

Sintaxe:

<extensions>

</extensions>

<extension>

Você pode usar o elemento <extension> para especificar documentos de uma extensão específica.

• Número de ocorrências: ilimitado

• Elementos pais: <extensions>

• Elementos filhos: nenhum

Sintaxe:

<extension>FilenameExtension</extension>

Por exemplo, se você quiser migrar todos os arquivos *.doc do computador de origem, especificando o código a seguir no elemento <component>:

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

é o mesmo que especificar o código a seguir abaixo do elemento <rules>:

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

Para obter outro exemplo de como usar o elemento <extension>, veja o exemplo de <excludeAttributes>.

<externalProcess>

Você pode usar o elemento <externalProcess> para executar uma linha de comando durante o processo de migração. Por exemplo, você pode querer executar um comando após o processo do LoadState.

• Número de ocorrências: ilimitado

• Elementos pais: <rules>

• Elementos filhos necessários: <commandLine>

Sintaxe:

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

</externalProcess>

Para obter um exemplo de como usar o elemento <extension>, veja o exemplo de <excludeAttributes>.

<icon>

Este é um elemento interno da USMT. Não use esse elemento.

<include>

O elemento <include> determina o que será migrado, a menos que haja uma regra <exclude> mais específica. Você pode especificar um script para ser mais específico para alargar a definição do que você deseja coletar. Para cada elemento <include> pode haver vários elementos <objectSet>.

• Número de ocorrências: ilimitado

• Elementos pais: <rules>

• Elemento filho necessário: <objectSet>

• Funções auxiliares: você pode usar as seguintes Funções de filtro <include> e <exclude> com estes elementos: CompareStringContent, IgnoreIrrelevantLinks, AnswerNo e NeverRestore.

Sintaxe:

<include filter="ScriptInvocation">

</include>

O exemplo a seguir é do arquivo 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>

Funções de filtro <include> e <exclude>

As seguintes funções retornam um valor booliano. Você pode usá-los para migrar determinados objetos com base em quando determinadas condições são atendidas.

• AnswerNo

  Este filtro sempre retorna FALSE.

  Syntax: AnswerNo ()

• CompareStringContent

  Syntax: CompareStringContent("StringContent","CompareType")

  Configuração	Obrigatória?	Valor
  StringContent	Sim	A cadeia de caracteres a ser verificada.
  CompareType	Sim	Uma cadeia de caracteres. Use um dos seguintes valores: Equal (não diferencia maiúsculas de minúsculas). A função retorna TRUE se a representação de cadeia de caracteres do objeto atual que é processado pelo mecanismo de migração for idêntica a StringContent. NULLou qualquer outro valor. A função retorna TRUE se a representação de cadeia de caracteres do objeto atual que é processado pelo mecanismo de migração não corresponder a StringContent.

• IgnoreIrrelevantLinks

  Este filtro seleciona os arquivos .lnk que apontam para um objeto que não é válido no computador de destino. Observe que a seleção ocorre no computador de destino, para que todos os arquivos .lnk sejam salvos no repositório durante o ScanState. Em seguida, eles serão exibidos quando você executar a ferramenta LoadState.

  Sintaxe: IgnoreIrrelevantLinks ()

  Por exemplo:

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

• NeverRestore

  Você pode usar esta função para coletar os objetos especificados do computador de origem, mas não para migrar os objetos para o computador de destino. Quando executada com a ferramenta ScanState, essa função é avaliada como TRUE. Quando executada com a ferramenta LoadState, essa função é avaliada como FALSE. Convém usar esta função quando você quer verificar o valor de um objeto no computador de destino, mas não pretende migrar o objeto para o destino.

  Sintaxe: NeverRestore()

  No exemplo a seguir, HKCU\Painel de Controle\Internacional [localidade] será incluído no repositório, mas ele não será migrado para o computador de destino:

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

<includeAttributes>

Você pode usar o elemento <includeAttributes> para determinar se determinados parâmetros associados com um objeto serão migrados juntamente com o próprio objeto. Se houver conflitos entre os elementos <includeAttributes> e <excludeAttributes>, o padrão mais específico determinará quais parâmetros serão migrados. Se um objeto não tiver um elemento <includeAttributes> ou <excludeAttributes>, todos os seus parâmetros serão migrados.

• Número de ocorrências: ilimitado

• Elementos pais: <rules>

• Elementos filhos: <objectSet>

Sintaxe:

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

</includeAttributes>

Para obter um exemplo de como usar o elemento <includeAttributes>, veja o exemplo de <excludeAttributes>.

<library>

Este é um elemento interno da USMT. Não use esse elemento.

<location>

O elemento <location> define o local do elemento <object>.

• Número de ocorrências: uma para cada <object>

• Elementos pais: <object>

• Elementos filhos: <script>

Sintaxe:

<location type="typeID">ObjectLocation</location>

Veja a seguir um exemplo do arquivo 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>

Você pode usar o elemento <locationModify> para alterar o local e o nome de um objeto antes de ele ser migrado para o computador de destino. O elemento <locationModify> é processado somente quando a ferramenta LoadState é executada no computador de destino. Em outras palavras, esse elemento é ignorado pela ferramenta ScanState. O elemento <locationModify> irá criar a pasta apropriada no computador de destino se ela ainda não existir.

Número de ocorrências: ilimitado

• Elementos pais: <rules>

• Elemento filho necessário: <objectSet>

• Funções auxiliares: você pode usar as seguintes Funções <locationModify> com estes elementos: ExactMove, RelativeMove e Move.

Sintaxe:

<locationModify script="ScriptInvocation">

</locationModify>

Veja a seguir um exemplo do arquivo 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>

Funções <locationModify>

As seguintes funções alteram a localização dos objetos conforme eles são migrados quando usam o elemento <locationModify>. Essas funções são chamadas para cada objeto que o elemento pai <ObjectSet> está enumerando. O elemento <locationModify> irá criar a pasta apropriada no computador de destino se ela ainda não existir.

• ExactMove

  A função ExactMove move todos os objetos correspondidos pelo elemento pai <ObjectSet> a determinado ObjectEncodedLocation. Você pode usar esta função para mover um único arquivo para outro local no computador de destino. Se o local de destino for um nó, todos os objetos de origem correspondentes serão gravados no nó sem nenhum subdiretório. Se o local de destino for uma folha, o mecanismo de migração migrará todos os objetos de origem correspondentes no mesmo local. Se ocorrer uma colisão, os algoritmos de colisão normal serão aplicados.

  Sintaxe: ExactMove(ObjectEncodedLocation)

  Configuração	Obrigatória?	Valor
  ObjectEncodedLocation	Sim	A Especificando locais de destino para todos os objetos de origem.

  Por exemplo:

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

• Move

  A função Move movimenta objetos para um local diferente no computador de destino. Além disso, esta função cria subdiretórios que eram superiores à CSIDL mais longa no nome do objeto de origem.

  Sintaxe: Move(DestinationRoot)

  Configuração	Obrigatória?	Valor
  DestinationRoot	Sim	O local para onde serão movidos os objetos de origem. Se necessário, essa função irá criar quaisquer subdiretórios que eram superiores à CSIDL mais longa no nome do objeto de origem.

• RelativeMove

  Você pode usar a função RelativeMove para coletar e mover os dados. Observe que você pode usar variáveis de ambiente em raízes de origem e de destino, mas elas podem ser definidas de forma diferente nos computadores de origem e de destino.

  Sintaxe: RelativeMove(SourceRoot,DestinationRoot)

  Configuração	Obrigatória?	Valor
  SourceRoot	Sim	O local de onde os objetos serão movidos. Nenhum objeto de origem que seja enumerado pelo elemento pai <ObjectSet>, que não esteja neste local, será movido.
  DestinationRoot	Sim	O local onde os objetos de origem serão movidos para o computador de destino. Se necessário, essa função irá criar quaisquer subdiretórios que estavam acima de SourceRoot.

  Por exemplo:

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

Este é um elemento interno da USMT. Não use esse elemento.

<manufacturer>

O elemento <manufacturer> define o fabricante do componente, mas não afeta a migração.

• Número de ocorrências: zero ou uma

• Elementos pais: <component>

• Elementos filhos: nenhum

Sintaxe:

<manufacturer>Nome</manufacturer>

<merge>

O elemento <merge> determina o que vai acontecer quando ocorre um conflito. Uma colisão é quando um objeto migrado já está presente no computador de destino. Se você não especificar esse elemento, o comportamento padrão do Registro será para o objeto de origem substituir o objeto de destino. O comportamento padrão dos arquivos serve para o arquivo de origem ser renomeado para "OriginalFileName(1).OriginalExtension". Este elemento especifica apenas o que deve ser feito quando uma colisão ocorre. Não inclui objetos. Portanto, para os objetos migrarem, você deve especificar regras <include> juntamente com o elemento <merge>. Quando um objeto for processado e uma colisão for detectada, a USMT irá selecionar a regra mais específica de mesclagem e aplicá-la para resolver o conflito. Por exemplo, se você tiver uma regra <merge> C:\* [*] definida como <sourcePriority> e uma regra <merge> C:\subfolder\* [*] definida como <destinationPriority>, a USMT poderá usar a regra <destinationPriority> porque é a mais específica.

Para obter um exemplo deste elemento, veja Como <merge> funciona quando há conflitos no computador de destino?.

• Número de ocorrências: ilimitado

• Elementos pais: <rules>

• Elemento filho necessário: <objectSet>

• Funções auxiliares: você pode usar as seguintes Funções <merge> com estes elementos: SourcePriority, DestinationPriority, FindFilePlaceByPattern, LeafPattern, NewestVersion, HigherValue() e LowerValue().

Sintaxe:

<merge script="ScriptInvocation">

</merge>

O exemplo a seguir é do arquivo 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>

Funções <merge>

Essas funções controlam como os conflitos são resolvidos.

• DestinationPriority

  Especifica para manter o objeto que está no computador de destino e não migrar o objeto de computador de origem.

  Por exemplo:

  <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

  A função FindFilePlaceByPattern salva arquivos com um contador incrementado quando ocorre um conflito. É uma cadeia de caracteres que contém uma das construções de cada: <F>, <E>, <N> em qualquer ordem.

  Sintaxe: FindFilePlaceByPattern(FilePattern)

  Configuração	Obrigatória?	Valor
  FilePattern	Sim	<F> será substituído pelo nome do arquivo original. <N> será substituído por um contador incrementado até que não haja nenhuma colisão com os objetos no computador de destino. <E> será substituído pela extensão de nome de arquivo original. Por exemplo, <F> (<N>).<E> irá alterar o arquivo de origem MyDocument.doc para MyDocument (1).doc no computador de destino.

• NewestVersion

  A função NewestVersion irá resolver conflitos no computador de destino com base na versão do arquivo.

  Sintaxe: NewestVersion(VersionTag)

  Configuração	Obrigatória?	Valor
  VersionTag	Sim	O campo de versão que será verificado. Isso pode ser "FileVersion" ou "ProductVersion". O arquivo com a versão mais recente de VersionTag determina quais conflitos serão resolvidos com base na versão do arquivo. Por exemplo, se myfile. txt contém 1 FileVersion e o mesmo arquivo no computador de destino contém FileVersion 2, o arquivo de destino permanecerá.

• HigherValue()

  Você pode usar esta função para mesclar os valores do Registro. Os valores do Registro serão avaliados como valores numéricos, e um com o valor mais alto irá determinar quais valores do Registro serão mesclados.

• LowerValue()

  Você pode usar esta função para mesclar os valores do Registro. Os valores do Registro serão avaliados como valores numéricos e um com o valor mais baixo irá determinar quais valores do Registro serão mesclados.

• SourcePriority

  Especifica a migração do objeto do computador de origem e a excluisão do objeto que está no computador de destino.

  Por exemplo:

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

O elemento <migration> é o único elemento raiz de um arquivo .xml de migração e é necessário. Cada arquivo .xml deve ter um urlid de migração exclusivo. O urlid de cada arquivo que você especificar na linha de comando deve ser exclusivo. Isso ocorre porque a USMT usa o urlid para definir os componentes dentro do arquivo. Por exemplo, você deve especificar o seguinte no início de cada arquivo: <CustomFileName> é o nome do arquivo; por exemplo, "CustomApp".

• Número de ocorrências: uma

• Elementos pais: nenhum

• Elementos filhos necessários: <component>

• Elementos filhos opcionais: <library>, <namedElements>

Sintaxe:

<migration urlid="*UrlID/*Name">

</migration>

Veja a seguir um exemplo do arquivo MigApp.xml:

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

MigXMLHelper.FileProperties

Esta função de auxiliar de filtro pode ser usada para filtrar a migração de arquivos com base em atributos de tamanho e data do arquivo.

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

Você pode usar o elemento <namedElements> para definir elementos nomeados. Você pode usar esses elementos em qualquer componente em todo seu arquivo .xml. Para obter um exemplo de como usar esse elemento, veja o arquivo MigApp.xml.

Sintaxe:

<namedElements>

</namedElements>

• Número de ocorrências: ilimitado

• Elementos pais: <migration>

• Elementos filhos: <environment>, <rules>, <conditions>, <detection>, <detects>, <detect>

Para obter um exemplo desse elemento, veja o arquivo MigApp.xml.

<object>

O elemento <object> representa um arquivo ou chave do Registro.

• Número de ocorrências: ilimitado

• Elementos pais: <addObjects>

• Elementos filhos necessários: <location>, <attributes>

• Elementos filhos opcionais: <bytes>

Sintaxe:

<object>

</object>

Veja a seguir um exemplo do arquivo 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>

O elemento <objectSet> contém uma lista de padrões de objeto; por exemplo, caminhos de arquivo, locais do Registro e assim por diante. Todos os elementos filhos <conditions> serão avaliados primeiro. Se todos os elementos filhos <conditions> retornam FALSE, o elemento <objectSet> será avaliado como um conjunto vazio. Para cada elemento pai, pode haver apenas vários elementos <objectSet>.

• Número de ocorrências: ilimitado

• Elementos pais: <variable>, <content>, <include>, <exclude>, <merge>, <contentModify>, <locationModify>, <destinationCleanup>, <includeAttributes>, <excludeAttributes>, <unconditionalExclude>, <detect>

• Elementos filhos necessários: either <script> ou <pattern>

• Elementos filhos opcionais: <content>, <conditions>, <condition>

Sintaxe:

<objectSet>

</objectSet>

O exemplo a seguir é do arquivo 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>

Este é um elemento interno da USMT. Não use esse elemento.

<paths>

Este é um elemento interno da USMT. Não use esse elemento.

<pattern>

Você pode usar esse elemento para especificar vários objetos. Você pode especificar vários elementos <pattern> para cada elemento <objectSet> e eles serão combinados. Se você estiver especificando arquivos, pode querer usar GenerateDrivePatterns com <script>. GenerateDrivePatterns é basicamente o mesmo que uma regra <pattern>, sem a especificação de letra de unidade. Por exemplo, as duas linhas de código a seguir são semelhantes:

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

• Número de ocorrências: ilimitado

• Elementos pais: <objectSet>

• Elementos filhos: nenhum, mas Caminho [objeto] deve ser válido.

Sintaxe:

<pattern type="typeID">Path [object]</pattern>

Por exemplo:

• Para migrar uma chave do Registro único:

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

• Para migrar a pasta EngineeringDrafts e todas as subpastas da unidade c::

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

• Para migrar somente a pasta EngineeringDrafts, excluindo as subpastas, da unidade c::

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

• Para migrar o arquivo Sample.doc de C:\EngineeringDrafts:

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

• Para migrar o arquivo de Sample.doc de onde ele existir na unidade c:, use o padrão da seguinte maneira. Se existirem vários arquivos com o mesmo nome na unidade c:, todos esses arquivos serão migrados.

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

• Para obter mais exemplos de como usar este elemento, veja os artigos sobre Excluir arquivos e configurações, Reencaminhar arquivos e configurações, Incluir arquivos e configurações e Exemplos de XML personalizados.

<processing>

Você pode usar esse elemento para executar um script durante um ponto específico do processo de migração. Retorne valores não esperados dos scripts que você especifica e, se não houver valores de retorno, eles serão ignorados.

• Número de ocorrências: ilimitado

• Elementos pais: <rules>

• Elemento filho necessário: <script>

Sintaxe:

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

</processing>

<plugin>

Este é um elemento interno da USMT. Não use esse elemento.

<role>

O elemento <role> é necessário em um arquivo .xml personalizado. Ao especificar o elemento <role>, você pode criar um componente concreto. O componente será definido pelos parâmetros especificados no nível de <component> e com a função que você especificar aqui.

• Número de ocorrências: cada <component> pode ter um, dois ou três elementos filhos <role>.

• Elementos pais: <component>, <role>

• Elementos filhos necessários: <rules>

• Elementos filhos opcionais: <environment>, <detection>, <component>, <role>, <detects>, <plugin>

Sintaxe:

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

O exemplo a seguir é do arquivo MigUser.xml: Para obter mais exemplos, veja o arquivo 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>

O elemento <rules> é necessário em um arquivo .xml personalizado. Esse elemento contém regras que serão executadas durante a migração se o elemento pai <component> for selecionado, a menos que o elemento filho <conditions>, se presente, for avaliado como FALSE. Para cada elemento <rules> pode haver vários elementos filhos <rules>.

• Número de ocorrências: ilimitado

• Elementos pais: <role>, <rules>, <namedElements>

• Elementos filhos necessários: <include>

• Elementos filhos opcionais: <rules>, <exclude>, <unconditionalExclude>,<merge>, <contentModify>, <locationModify>, <destinationCleanup>, <addObjects>, <externalProcess>, <processing>, <includeAttributes>, <excludeAttributes>, <conditions>, <detects>

Sintaxe:

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

</rules>

O exemplo a seguir é do arquivo 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>

O valor de retorno que é exigido pelo <script> depende do elemento pai.

Número de ocorrências: uma vez para <variable>, ilimitado para <objectSet> e <processing>

Elementos pais: <objectSet>, <variable>, <processing>

Elementos filhos: nenhum

Sintaxe e funções auxiliares:

• Sintaxe geral: <script>ScriptWithArguments</script>

• Você pode usar Funções <script> quando <script> está dentro de <variable>.

  Sintaxe: <script>MigXmlHelper.GetStringContent("ObjectType","EncodedLocationPattern", "ExpandContent")</script>

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

• Você pode usar Funções <script> quando <script> está dentro de <objectSet>.

  Sintaxe: <script>MigXmlHelper.GenerateUserPatterns("ObjectType","EncodedLocationPattern","ProcessCurrentUser")</script>

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

• Você pode usar Funções <script> quando <script> está dentro de <objectSet>.

  Sintaxe: <script>MigXmlHelper.GenerateDrivePatterns("PatternSegment","DriveType")</script>

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

• Você pode usar os Funções <script> com elementos <script> que estão dentro dos elementos <processing>: AskForLogoff, ConvertToShortFileName, KillExplorer, RemoveEmptyDirectories, RestartExplorer, RegisterFonts, StartService, StopService, SyncSCM.

  Sintaxe: <script>MigXmlHelper.ExecutingScript</script>

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

Exemplos:

Para migrar o arquivo Sample.doc de qualquer unidade no computador de origem, use <script> como a seguir. Se houver vários arquivos com o mesmo nome, todos esses arquivos serão migrados.

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

Para obter mais exemplos de como usar este elemento, veja os artigos sobre Excluir arquivos e configurações, Reencaminhar arquivos e configurações, Reencaminhar arquivos e configurações e Exemplos de XML personalizados.

Funções <script>

Você pode usar as seguintes funções com o elemento <script>

• Cadeia de caracteres e funções de geração padrão

• Scripts de execução simples

Cadeia de caracteres e funções de geração padrão

Essas funções retornam uma cadeia de caracteres ou um padrão.

• GetStringContent

  Você pode usar GetStringContent com elementos <script> que estão dentro de elementos <variable>. Se possível, essa função retorna a representação de string do objeto fornecido. Caso contrário, retorna NULL. Para objetos de arquivo, esta função sempre retorna NULL.

  Sintaxe: GetStringContent("ObjectType","EncodedLocationPattern", "ExpandContent")

  Configuração	Obrigatória?	Valor
  ObjectType	Sim	O tipo de objeto. Pode ser Registro ou Ini (para um arquivo .ini).
  EncodedLocationPattern	Sim	Se o tipo de objeto for Registro, EncodedLocationPattern deve ser um caminho válido do Registro. Por exemplo, HKLM\SOFTWARE\MyKey[]. Se o tipo de objeto for Ini, EncodedLocationPattern deve estar no seguinte formato: IniFilePath|SectionName[SettingName]
  ExpandContent	Não (padrão = TRUE)	Pode ser TRUE ou FALSE. Se FALSE, o local indicado não será expandido antes de ele ser retornado.

  Por exemplo:

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

• GenerateDrivePatterns

  A função GenerateDrivePatterns itera todas as unidades disponíveis e seleciona as que correspondem ao tipo de unidade solicitado. Em seguida, ela concatena as unidades selecionadas com a parte final de PatternSegment para formar um padrão completo de arquivo codificado. Por exemplo, se PatternSegment for Path [file.txt] e DriveType for Fixed, a função vai gerar C:\Path [file.txt] e outros padrões, se houver unidades fixas diferentes de C:. Você não pode especificar variáveis de ambiente com essa função. Você pode usar GenerateDrivePatterns com elementos <script> que estão dentro de <objectSet> dentro de <include>/<exclude>.

  Sintaxe: GenerateDrivePatterns("PatternSegment","DriveType")

  Configuração	Obrigatória?	Valor
  PatternSegment	Sim	O sufixo de um padrão codificado. Ele é concatenado com uma especificação de unidade, como "c:\", para formar um Especificando locais completo. Por exemplo, "* [*. doc]". PatternSegment não pode ser uma variável de ambiente.
  DriveType	Sim	O tipo de unidade para que os padrões sejam gerados. Você pode especificar um destes: Corrigido CD-ROM Removível Remoto

  Veja o último componente no arquivo MigUser.xml para obter um exemplo deste elemento.

• GenerateUserPatterns

  A função faz a iteração por todos os usuários que estão sendo migrados, excluindo o usuário atualmente processado quando <ProcessCurrentUser> é FALSE, e expande o padrão especificado no contexto de cada usuário. Por exemplo, quando os usuários A, B e C têm perfis em C:\Documents and Settings), ao chamar GenerateUserPattens('File','%userprofile% [*.doc]','TRUE'), a função auxiliar gera os três padrões a seguir:

  • "C:\Documents e Settings\A\ [*. doc]"

  • "C:\Documents e Settings\B\ [*. doc]"

  • "C:\Documents e Settings\C\ [*. doc]"

  Sintaxe:GenerateUserPatterns("ObjectType","EncodedLocationPattern","ProcessCurrentUser")

  Configuração	Obrigatória?	Valor
  ObjectType	Sim	Define o tipo de objeto. Pode ser Arquivo ou Registro.
  EncodedLocationPattern	Sim	O Especificando locais. Variáveis de ambiente são permitidas.
  ProcessCurrentUser	Sim	Pode ser TRUE ou FALSE. Indica se os padrões devem ser gerados para o usuário atual.

  Exemplo:

  Se GenerateUserPattens ('File','%userprofile% [*.doc]','FALSE') for chamado enquanto a USMT está processando o usuário A, essa função irá gerar somente padrões para usuários B e C. Você pode usar esta função auxiliar para construir regras complexas. Por exemplo, para migrar todos os arquivos .doc do computador de origem — mas se o usuário X não for migrado, não migre nenhum dos arquivos .doc do perfil do usuário X.

  Veja a seguir o código de exemplo para este cenário. O primeiro elemento <rules> migra todos os arquivos .doc no computador de origem, com exceção dos que estão dentro de C:\Documents and Settings. O segundo elemento <rules> migrará todos os arquivos .doc de C:\Documents and Settings, com exceção dos arquivos .doc nos perfis de outros usuários. Como o segundo elemento <rules> será processado em cada contexto de usuário migrado, o resultado final será o comportamento desejado. O resultado final é o que esperávamos.

  <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

Essa função auxiliar chama o localizador de documento para fazer a varredura do sistema para todos os arquivos que podem ser migrados. Ele pode ser chamado no contexto de System ou User para concentrar a varredura.

 <!-- 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 de execução simples

Os scripts a seguir não têm nenhum valor de retorno. Você pode usar os seguintes erros com elementos <script> que estão dentro de elementos <processing>

• AskForLogoff(). Solicita que o usuário faça logoff no final da migração. Por exemplo:

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

• ConvertToShortFileName(RegistryEncodedLocation). Se RegistryEncodedLocation for o caminho completo de um arquivo existente, essa função irá converter o arquivo no seu nome de arquivo curto e irá atualizar o valor do Registro.

• KillExplorer(). Para o Explorer.exe para o contexto de usuário atual. Isso permite o acesso a determinadas chaves e arquivos que são mantidos abertos quando o Explorer.exe está em execução. Por exemplo:

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

• RegisterFonts(FileEncodedLocation). Registra a determinada fonte ou todas as fontes no diretório especificado. Por exemplo:

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

• **RemoveEmptyDirectories (DirectoryEncodedPattern).**Exclui quaisquer diretórios vazios que correspondem a DirectoryEncodedPattern no computador de destino.

• RestartExplorer(). Reinicia o Explorer.exe no final da migração. Por exemplo:

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

• StartService (ServiceName, OptionalParam1, OptionalParam2,…). Inicia o serviço identificado por ServiceName. ServiceName é a subchave em HKLM\System\CurrentControlSet\Services que retém os dados de determinado serviço. Os parâmetros opcionais, se houver, são passados para a API de StartService. Para saber mais, veja este site da Microsoft.

• StopService (ServiceName). Para o serviço identificado por ServiceName. ServiceName é a subchave em HKLM\System\CurrentControlSet\Services que retém os dados de determinado serviço.

• SyncSCM(ServiceShortName). Lê o valor de tipo de Start do Registro (HKLM\System\CurrentControlSet\Services\ServiceShortName [Start]) depois que ele é alterado pelo mecanismo de migração e sincroniza o SCM (Gerenciador de Controle de Serviço) com o novo valor.

<text>

Você pode usar o elemento <text> para definir um valor para quaisquer variáveis de ambiente que estão dentro de um dos arquivos .xml de migração.

• Número de ocorrências: uma em cada elemento <variable>.

• Elementos pais: <variable>

• Elementos filhos: nenhum.

Sintaxe:

<text>NormalText</text>

Por exemplo:

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

<unconditionalExclude>

O elemento <unconditionalExclude> exclui os arquivos especificados e valores do Registro da migração, independentemente de outras regras de inclusão em qualquer um dos arquivos .xml de migração ou no arquivo Config.xml. Os objetos declarados aqui não serão migrados porque este elemento tem precedência sobre todas as outras regras. Por exemplo, mesmo se houver regras <include> explícita para incluir arquivos .mp3, se você especificar excluí-los com esta opção, eles não serão migrados.

Use esse elemento se você deseja excluir todos os arquivos .mp3 do computador de origem. Ou, se você estiver fazendo backup em C:\UserData usando outro método, pode excluir a pasta inteira da migração. Use esse elemento com cuidado, no entanto, porque se um aplicativo precisar de um arquivo que você excluiu, o aplicativo pode não funcionar corretamente no computador de destino.

• Número de ocorrências: ilimitado.

• Elementos pais: <rules>

• Elementos filhos: <objectSet>

Sintaxe:

<unconditionalExclude> </unconditionalExclude>

O seguinte arquivo .xml exclui todos os arquivos .mp3 da migração. Para obter exemplos adicionais de como usar este elemento, veja o artigo sobre Excluir arquivos e configurações.

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

O elemento <variable> é necessário em um elemento <environment>. Para cada elemento <variable> deve haver um elemento <objectSet>, <script> ou <text>. O conteúdo do elemento <variable> atribui um valor de texto para a variável de ambiente. Este elemento tem as três opções a seguir:

1. Se o elemento <variable> contiver um elemento <text>, o valor do elemento variável será o valor do elemento <text>.

2. Se o elemento <variable> contiver um elemento <script> e a invocação do script produzir uma cadeia de caracteres não nula, o valor do elemento <variable> será o resultado da invocação do script.

3. Se o elemento <variable> contiver um elemento <objectSet> e a avaliação do elemento <objectSet> produzir pelo menos um padrão de objeto, o valor do primeiro objeto correspondente ao padrão de objeto resultante será o valor do elemento variável.

• Número de ocorrências: ilimitado

• Elementos pais: <environment>

• Elementos filhos necessários: <text>, <script> ou <objectSet>

Sintaxe:

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

</variable>

Veja a seguir um exemplo do arquivo 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>

O elemento <version> define a versão do componente, mas não afeta a migração.

• Número de ocorrências: zero ou uma

• Elementos pais: <component>

• Elementos filhos: nenhum

Sintaxe:

<version>ComponentVersion</version>

Por exemplo:

<version>4.*</version>

<windowsObjects>

O elemento <windowsObjects> é somente para uso interno da USMT. Não use esse elemento.

Apêndice

Especificando locais

• Especificando locais codificados. O local codificado usado em todas as funções auxiliares é uma representação de cadeia de caracteres inequívoca para o nome de um objeto. É composto por parte do nó, seguido opcionalmente pela folha entre colchetes. Isso faz uma distinção clara entre nós e folhas.

  Por exemplo, especifique o arquivo C:\Windows\Notepad.exe como este: c:\Windows[Notepad.exe]. Da mesma forma, especifique o diretório C:\Windows\System32 como este: c:\Windows\System32. (Observe a ausência da construção [].)

  Representar o Registro é muito semelhante. O valor padrão de uma chave do Registro é representado como uma construção [] vazia. Por exemplo, o valor padrão da chave do Registro HKLM\SOFTWARE\MyKey será HKLM\SOFTWARE\MyKey[].

• Especificando padrões de localização. Você especifica um padrão de localização de uma forma semelhante como especifica uma localização real. A exceção é que tanto a parte do nó quanto da folha aceita padrões. No entanto, um padrão do nó não se estende à folha.

  Por exemplo, o padrão c:\Windows\* corresponderá ao diretório do Windows e a todos os subdiretórios. Mas ele não irá corresponder a nenhum dos arquivos nesses diretórios. Para corresponder também aos arquivos, você deve especificar c:\Windows\*[*].

Funções internas da USMT

As seguintes funções são somente para uso interno da USMT. Não use-os em um arquivo .xml.

• AntiAlias

• ConvertScreenSaver

• ConvertShowIEOnDesktop

• ConvertToOfficeLangID

• MigrateActiveDesktop

• MigrateAppearanceUPM

• MigrateDisplayCS

• MigrateDisplaySS

• MigrateIEAutoSearch

• MigrateMouseUPM

• MigrateSoundSysTray

• MigrateTaskBarSS

• SetPstPathInMapiStruc

Marcas de versão válidas

Você pode usar as seguintes marcas de versão com várias funções auxiliares:

• "CompanyName"

• "FileDescription"

• "FileVersion"

• "InternalName"

• "LegalCopyright"

• "OriginalFilename"

• "ProductName"

• "ProductVersion"

As seguintes marcas de versão contêm valores que podem ser comparados:

• "FileVersion"

• "ProductVersion"

Consulte também

Outros Recursos

Referência XML da USMT