Herramienta VSS redactor de pruebas

2024-07-24

El redactor de pruebas es una utilidad que se puede utilizar para probar las aplicaciones solicitantes de VSS. Este redactor puede configurarse para realizar casi todas las acciones que puede realizar un redactor VSS. Además, el redactor de pruebas realiza comprobaciones exhaustivas para asegurarse de que el solicitante ha tratado correctamente estas acciones del redactor.

Cada instancia del redactor se inicializa con un archivo de configuración XML que describe exactamente sobre qué componentes informará el redactor y cómo se comportará. El redactor puede configurarse para informar sobre distintos tipos de escenarios, incluidos los más complicados, utilizando las interfaces incremental y diferencial. El redactor realizará comprobaciones en varios momentos del proceso para asegurarse de que el solicitante se comporta de forma adecuada. Una vez finalizada la restauración, el redactor comprobará que todos los archivos necesarios se han restaurado sin corrupción. El redactor también puede configurarse para realizar otras operaciones, como fallar eventos específicos.

Nota:

Esta herramienta está incluida en el kit de desarrollo de software (SDK) de Microsoft Windows para Windows Vista y versiones posteriores. Puede descargar el Windows SDK desde https://msdn.microsoft.com/windowsvista.

En la instalación de Windows SDK installation, se pueden encontrar las siguientes herramientas VssSampleProvider en %Program Files(x86)%\Windows Kits\8.1\bin\x64 (para 64-bit Windows) y %Program Files(x86)%\Windows Kits\8.1\bin\x86.

Ejecutar la herramienta VSS redactor de pruebas

Para iniciar el redactor de pruebas, escriba lo siguiente en la línea de comandos:

vswriter.execonfig-file

donde config-file es la ruta a un archivo de configuración que especifica el comportamiento de este redactor.

Para detener el redactor de pruebas, pulse CTRL+C.

Se pueden ejecutar varias instancias del redactor de pruebas al mismo tiempo. Sin embargo, cada instancia del redactor reportará el mismo ID de clase del redactor (aunque un ID de instancia del redactor diferente), por lo que las rutas lógicas y los nombres de los componentes deben ser únicos en todas las instancias del redactor que se ejecuten simultáneamente.

Para garantizar que el redactor pueda comprobar correctamente que el solicitante ha respetado las especificaciones de exclusión de archivos, todos los archivos de los que se haya realizado una copia de seguridad deben eliminarse del volumen original antes de intentar restaurarlos. Se recomienda almacenar una plantilla de cada escenario de redactor, de modo que el escenario pueda recrearse fácilmente.

Usar un archivo de configuración

El siguiente ejemplo de archivo de configuración, vswriter_config.xml, se puede encontrar en %ProgramFiles%\Microsoft SDKs\Windows\v7.0\bin\vsstools en x86 plataformas y %ProgramFiles%\Microsoft SDKs\Windows\v7.0\bin\x64\vsstools en x64 plataformas.

<TestWriter usage="USER_DATA">

    <RestoreMethod method="RESTORE_IF_CAN_BE_REPLACED"
                   writerRestore="always"
                   rebootRequired="no" />

    <ExcludeFile path="c:\writerData\notTheseFiles" 
                 filespec="excludeThisFile.txt" 
                 recursive="no"/>

    <Component componentType="filegroup"
               componentName="TestFiles">
        <ComponentFile path="c:\writerData\myFilesHere" 
                       filespec="*"
                       recursive="no" />
    </Component>

</TestWriter>

El elemento raíz de este archivo de configuración se llama TestWriter. Todos los demás elementos están dispuestos bajo el elemento TestWriter.

Uno de los atributos asociados a TestWriter es el atributo usage. Este atributo especifica el tipo de uso notificado a través de IVssExamineWriterMetadata::GetIdentity. f los valores posibles para este atributo es USER_DATA.

El primer elemento hijo del elemento raíz debe ser siempre un elemento RestoreMethod. Este elemento especifica lo siguiente:

El método de restauración (en este caso, RESTORE_IF_CAN_BE_REPLACED)
Si el redactor requiere eventos de restauración (en este caso, siempre)
Si es necesario reiniciar después de restaurar el redactor (en este caso, no)

Este elemento puede especificar opcionalmente una asignación de ubicación alternativa. (En este caso, no se especifica ninguna ubicación alternativa).

El segundo elemento hijo es un elemento ExcludeFile. Este elemento hace que el redactor excluya un archivo o un conjunto de archivos de la copia de seguridad.

El tercer elemento hijo es un elemento Componente. Este elemento hace que el redactor añada un componente a sus metadatos. Un elemento Componente contiene atributos para describir el componente y elementos hijo para describir el contenido del componente, como los siguientes:

componentType para indicar si se trata de un grupo de archivos o de una base de datos
logicalPath para la ruta lógica del componente
componentName para el nombre del componente
seleccionable para indicar el estado seleccionable para copia de seguridad

El elemento Componente también tiene un elemento hijo llamado ComponentFile para añadir una especificación de archivo a este componente. (Un elemento Componente puede tener un número arbitrario de elementos ComponentFile que pueden especificarse para cada componente). Este elemento ComponentFile tiene los siguientes atributos:

ruta="c:\writerData\myFilesHere"
filespec="*"
recursivo="no"

Aunque el Escritor de Prueba verifica el comportamiento del solicitante, no verifica que el archivo de configuración mantenga siempre la semántica documentada para un redactor. Hay muchas operaciones que un redactor que se comporte bien no debería hacer (como informar del mismo archivo en varios componentes), y corresponde al autor del archivo de configuración XML mantener esta semántica.

Configuración de los atributos del redactor

El elemento raíz TestWriter contiene atributos que determinan varios comportamientos del redactor. Algunos de los comportamientos que pueden alterarse son los siguientes:

Atributo	Descripción
verborrea	El redactor imprime el estado en la consola a medida que recibe eventos y los procesa. El nivel de verbosidad mostrado se especifica mediante el atributo verborrea. Se puede elegir entre tres niveles de verborrea: bajo Solo se imprimirán los fallos del redactor o el comportamiento incorrecto del solicitante. medio Se imprime todo en el nivel de verborrea bajo, además de información de estado adicional como, por ejemplo, cuándo se reciben eventos. Es el nivel predeterminado. alto Se proporciona información detallada sobre el funcionamiento del redactor.
deleteFiles	Para realizar una verificación adicional, establezca este atributo en "yes" para que el redactor elimine todos sus archivos inmediatamente después de que se cree la instantánea de volumen. A continuación, el solicitante debe copiar los archivos de la copia sombra, porque ya no existen en el volumen original. Nota: En el caso de los redactores de spits, los archivos se eliminan de la ubicación original después del spit pero antes de que se cree la copia oculta Una vez creada la copia oculta, los archivos se eliminan del directorio spit.
deletePartialFiles	Para eliminar archivos parciales, establezca este atributo en "sí".
deleteDifferencedFiles	Para eliminar archivos diferenciados, establezca este atributo en "sí".
checkIncludes	Establezca este atributo en "sí" para que el redactor compruebe que todos los archivos de los que se ha realizado una copia de seguridad se han restaurado en una ubicación adecuada y que el archivo no se ha dañado. También se gestionan correctamente los archivos parciales y los archivos con diferencias.
checkExcludes	Establezca este atributo en "sí" para que el redactor compruebe que los archivos que coinciden con una especificación de archivo en la lista de exclusión no se restauran. Para que esto funcione correctamente, los directorios de restauración deben vaciarse antes de la restauración.

Especificación de la asignación de ubicaciones alternativas.

Una asignación de ubicación alternativa especifica una ubicación a la que restaurar si el método de restauración es VSS_WRE_RESTORE_TO_ALTERNATE_LOCATION o si falla la restauración normal de un componente. Un redactor puede informar de sus asignaciones de ubicaciones alternativas al solicitante utilizando el IVssExamineWriterMetadata::GetAlternateLocationMapping método. Puede añadir asignaciones de ubicación alternativas al archivo de configuración del redactor de pruebas añadiendo subelementos AlternateLocationMapping al elemento RestoreMethod.

El siguiente elemento RestoreMethod contiene un subelemento AlternateLocationMapping.

<RestoreMethod method="RESTORE_IF_CAN_REPLACE"
              writerRestore="always"
              rebootRequired="no">
    <AlternateLocationMapping path="c:\files"
                              filespec="*.txt"
                              recursive="no"
                              alternatePath="c:\altfiles"/>
</RestoreMethod>

Este ejemplo especifica que el solicitante debe intentar restaurar primero todos los archivos que coincidan con c:\files\*.txt en el directorio c:\files. Si uno de estos archivos no puede ser reemplazado, el solicitante debe restaurar todos los archivos en el directorio c:\altfiles en su lugar. Un redactor puede informar de sus asignaciones de ubicaciones alternativas al solicitante utilizando el IVssBackupComponents::AddAlternativeLocationMapping método. Si el redactor de pruebas está configurado para comprobar si se han restaurado los archivos, también comprobará si el solicitante ha llamado a AddAlternativeLocationMapping.

Especificación de los archivos que deben excluirse

Cada redactor puede especificar una lista de especificaciones de archivos que especifiquen los archivos que el solicitante debe excluir de la copia de seguridad. Puede añadir estas especificaciones de archivo al archivo de configuración del redactor de pruebas añadiendo subelementos ExcludeFile al elemento raíz TestWriter.

Este es un ejemplo de un subelemento ExcludeFile que excluye todos los archivos del directorio C:\files que coincidan con C:\temp*.*.

    <ExcludeFile path="c:\files" 
                 filespec="temp*.*" 
                 recursive="no"/>

Respaldar a los redactores de escupitajos

Muchos redactores actúan como "spit writers". Un "spit writer" crea archivos intermedios, o "spit files", basados en un conjunto original de archivos, y coloca los "spit files" en una ubicación alternativa en el momento de realizar la copia de seguridad. Un redactor puede informar de sus asignaciones de ubicaciones alternativas al solicitante utilizando el IVssWMFiledesc::GetAlternateLocation método para notificar al solicitante que debe realizar una copia de seguridad de estos archivos desde la ubicación alternativa. No obstante, estos archivos deben restaurarse en la ubicación activa de los archivos originales. El redactor de pruebas puede configurarse para que actúe como redactor de saliva para una especificación de archivo concreta.

El siguiente elemento ComponentFile contiene un atributo alternatePath:

    <ComponentFile path="c:\files"
                   filespec="*.txt"
                   recursive="no"
                   alternatePath="c:\files\spit" />

Este ejemplo configura el redactor de pruebas para que copie todos los archivos que coincidan con c:\files\*.txt en el directorio c:\files\spit inmediatamente antes de que se cree la copia oculta del volumen. El solicitante debe hacer una copia de seguridad de los archivos del directorio c:\files\spit. Si el redactor de pruebas está configurado para eliminar archivos, elimina los archivos originales antes de que se cree la copia oculta, por lo que no aparecen en el directorio c:\files del volumen de copia oculta. En este caso, los archivos en c:\files\spit se borran después de que se crea la copia oculta, por lo que deben ser respaldados desde el directorio c:\files\spit en el volumen de copia oculta.

Dependencias de los componentes de informes

Los redactores pueden especificar una dependencia entre un componente local y un componente que exista en otro redactor. Estas dependencias se comunican al solicitante mediante IVssWMComponent::GetDependency. El redactor de pruebas puede configurarse para informar de estas dependencias añadiendo uno o más subelementos Dependency al elemento Component.

El siguiente elemento Componente contiene un subelemento Dependencia:

    <Component componentType="filegroup"
               logicalPath=""
               componentName="WriterComponent"
               selectable="yes">
         <Dependency writerId="<GUID of target writer>"
                     logicalPath="ComponentPath"
                     componentName="Writer2Component" />
    </Component>

La dependencia se especifica como atributos del elemento Dependencia. writerId es el id de clase del redactor que contiene el objetivo de la dependencia, logicalPath es la ruta lógica al componente en ese redactor, y componentName es el nombre del componente. En este caso, si el solicitante está realizando una copia de seguridad de "WriterComponent" en el redactor actual, también debería realizar una copia de seguridad del componente "ComponentPath\Writer2Component" en el redactor de destino.

Nota:

El redactor de pruebas no realiza ninguna comprobación para garantizar que se respetan las dependencias.

Eventos fallidos

El redactor de prueba puede configurarse para que falle cualquiera de los eventos normales que recibe un redactor. Estos eventos son los siguientes:

Evento	Descripción
Identidad	Recibida una respuesta como una IVssBackupComponents::GatherWriterMetadata llamada. En caso contrario, el redactor no será informado.
PrepareForBackup	Recibida una respuesta como una IVssBackupComponents::PrepareForBackup llamada.
PrepareForSnapsot	Se recibe cuando el solicitante llama IVssBackupComponents::DoSnapshotSet, pero antes de que se cree la copia oculta.
Inmovilizar	Se recibe inmediatamente después IVssBackupComponents::PrepareForSnapshot, pero incluso antes de que se cree la copia oculta.
Reanudar	Se recibe una vez finalizada la creación de la copia oculta.
PostSnapshot	Se recibe cuando el solicitante llama IVssBackupComponents::DoSnapshotSet completa.
Aborto	Recibido si transcurre demasiado tiempo entre Congelar y Descongelar o si las llamadas solicitadas IVssBackupComponents::AbortBackup.
BackupComplete	Se recibe cuando el solicitante sale. Aquí nunca se informará de los fallos.
PreRestore	Recibida una respuesta como una IVssBackupComponents::PreRestore llamada.
PostRestore	Recibida una respuesta como una IVssBackupComponents::PostRestore llamada.

Estos fallos se configuran añadiendo uno o más subelementos FailEvent al elemento raíz TestWriter. Se pueden establecer dos clases de fallos: los que se pueden volver a intentar y los que no se pueden volver a intentar. Los errores que se pueden volver a intentar son errores que pueden desaparecer si se reintenta todo el proceso de copia de seguridad, mientras que los errores que no se pueden volver a intentar es poco probable que desaparezcan. El tipo de fallo para el evento se elige en función del atributo que se pueden volver a intentar.

He aquí un ejemplo de fallo básico que no se pueden volver a intentar:

    <FailEvent writerEvent="Freeze"
               retryable="no" />

Este ejemplo hará que el redactor falle durante el Congelar evento. IVssBackupComponents::GatherWriterStatus informará de que el redactor no es VSS_E_WRITERERROR_NONRETRYABLE.

He aquí un ejemplo de error básico que no se pueden volver a intentar:

    <FailEvent writerEvent="Freeze"
               retryable="yes"
               numFailures="2"/>

Este ejemplo hará que el redactor falle las dos primeras veces si recibe un Congelar evento. Después de las dos primeras veces, el redactor siempre tendrá éxito. El fallo del redactor denunciado a través de IVssBackupComponents::GatherWriterStatus será un código de error aleatorio que se pueden volver a intentar.

Declaración de los tipos de copia de seguridad admitidos

Los redactores comunican qué tipos de copia de seguridad admiten a través de la llamada del solicitante IVssExamineWriterMetadata::GetBackupSchema. El elemento raíz TestWriter contiene atributos para cada tipo de copia de seguridad para indicar la compatibilidad. Estos atributos son supportsCopy, supportsDifferential, supportsIncremental y supportsLog. Para indicar la compatibilidad con un determinado tipo de copia de seguridad, establezca el atributo correspondiente en "sí".

Si el solicitante establece un tipo de copia de seguridad que el redactor no admite, el redactor tomará nota de este hecho durante el proceso de creación de la copia de seguridad PrepareForBackup, pero por lo demás funcionan correctamente.

Indicación del tipo de copia de seguridad de archivos

El IVssWMFiledesc::GetBackupTypeMask método devuelve al solicitante una máscara de bits que indica cómo debe realizarse la copia de seguridad de un archivo. Esto indicará si un archivo es necesario o no durante determinados tipos de copia de seguridad, y también si es necesaria una copia oculta durante determinados tipos de copia de seguridad. Los tipos de copia de seguridad de esta máscara de bits se explican con más detalle en el documento El papel del solicitante en la copia de seguridad de almacenes complejos.

En el redactor de pruebas, los elementos de esta máscara de bits se especifican estableciendo atributos en cada elemento ComponentFile. Los atributos fullBackupRequired, diffBackupRequired, incBackupRequired y logBackupRequired especifican cuándo es necesario realizar una copia de seguridad de un archivo. Los atributos fullSnapshotRequired, diffSnapshotRequired, incSnapshotRequired y logSnapshotRequired especifican cuándo se debe realizar una copia de seguridad de un archivo desde una copia oculta de un volumen (y nunca desde el volumen original). El valor predeterminado para todos estos valores es "sí", lo que indica que siempre se debe hacer una copia de seguridad de un archivo y que se debe hacer desde una copia oculta de un volumen.

Añadir archivos parciales

Durante el proceso de DoSnapshotSet, un redactor tiene la posibilidad de añadir archivos parciales a cada componente. Estos archivos parciales se notifican mediante IVssComponent::GetPartialFile. El redactor de pruebas puede configurarse para añadir archivos parciales especificando subelementos PartialFile en un elemento Component.

Este es un ejemplo de un elemento Componente que tiene dos subelementos ArchivoParcial:

    <Component componentType="filegroup"
               logicalPath=""
               componentName="WriterComponent"
               selectable="yes">
        <ComponentFile path="c:\files"
                       filespec="*.txt"
                       recursive="no"/>
        <PartialFile path="c:\files"
                     filespec="partial.txt"
                     ranges="0:5,100:20" />
        <PartialFile path="c:\files2"
                     filespec="partial.txt"
                     ranges="0:5,100:20" />
    </Component>

Solo deben especificarse de este modo los archivos parciales que coincidan parcialmente con un ComponentFile existente (como en el primer archivo parcial del ejemplo) o los nuevos archivos parciales que se encuentren en el mismo volumen que un ComponentFile existente (como en el segundo archivo parcial). Para este componente, el solicitante debe realizar una copia de seguridad completa de todos los archivos que coincidan con c:\files\*.txt excepto de partial.txt. A continuación, el solicitante debe realizar una copia de seguridad de los rangos especificados (donde un rango es un desplazamiento seguido de una longitud) para los archivos c:\files\parcial.txt y c:\files2\parcial.txt.

Si el redactor está configurado para comprobar las restauraciones de archivos, solo se comprobarán los rangos de copia de seguridad del archivo parcial en el momento de la restauración. Las modificaciones de otras partes del archivo pasarán desapercibidas. Si se define el atributo deletePartialFiles del elemento raíz TestWriter, los archivos parciales se eliminan del volumen original inmediatamente después de crear la copia oculta.

Añadir archivos diferenciados

Durante el proceso de DoSnapshotSet, un redactor puede añadir archivos diferenciados a cada componente. Estos archivos parciales se notifican mediante IVssComponent::GetDifferencedFile. El redactor de pruebas puede configurarse para añadir archivos diferenciados especificando subelementos DifferencedFile en un elemento Component.

Este es un ejemplo de un elemento Componente que tiene dos subelementos DifferencedFile:

    <Component componentType="filegroup"
               logicalPath=""
               componentName="WriterComponent"
               selectable="yes">
        <ComponentFile path="c:\files"
                       filespec="*.txt"
                       recursive="no"/>
        <DifferencedFile path="c:\files"
                         filespec="*.txt"
                         year="2007"
                         month="1"
                         day="22"
                         hour="12"
                         minute="44"
                         second="17" />
        <DifferencedFile path="c:\files2"
                         filespec="*.txt"
                         year="2007"
                         month="1"
                         day="22"
                         hour="12"
                         minute="44"
                         second="17" />
    </Component>

A diferencia de los archivos parciales, los archivos diferenciados nunca deben coincidir parcialmente con una especificación ComponentFile. La especificación de archivo en un elemento DifferencedFile debe coincidir exactamente con un ComponentFile (como en el primer archivo diferenciado del ejemplo) o no debe coincidir en absoluto, sino estar en un volumen al que se hace referencia en un ComponentFile (como en el segundo archivo diferenciado). Los valores de fecha y hora deben ser relativos a la zona horaria local, pero se convertirán a GMT antes de ser comunicados al solicitante. En el ejemplo, solo se realizará una copia de seguridad de los archivos que coincidan con c:\files\*.txt o c:\files2\*.txt que se hayan modificado desde el 1/22/2003:12:44:17.

Si el redactor de pruebas está configurado para comprobar la restauración de archivos, solo se comprobará la restauración de los archivos modificados. Si se define el atributo deleteDifferencedFiles del elemento raíz TestWriter, los archivos diferenciados se eliminan del volumen original inmediatamente después de crear la copia oculta.

Nuevos objetivos

Algunos redactores permiten que el solicitante les informe de que se ha elegido una nueva ubicación para restaurar determinados archivos. El redactor indica que admite este modo como parte de la máscara de bits devuelta por IVssExamineWriterMetadata::GetBackupSchema. Por defecto, el redactor de pruebas siempre admite nuevos objetivos. Este soporte puede desactivarse estableciendo el atributo supportsNewTarget del elemento raíz TestWriter en "no".

Si un redactor admite nuevos objetivos, el solicitante puede informar al redactor de los nuevos objetivos llamando a IVssBackupComponents::AddNewTarget. A continuación, el redactor comprobará la nueva ubicación de destino para verificar la restauración en lugar de la ubicación original.

Más información

El redactor de pruebas admite más opciones de configuración que no se describen aquí. El esquema completo de todas las funciones de configuración del redactor de pruebas se especifica en swriter.xml en %ProgramFiles%\Microsoft SDKs\Windows\v7.0\bin\x64\vsstools (para 64-bit Windows) y %ProgramFiles%\Microsoft SDKs\Windows\v7.0\bin\vsstools (para 32-bit Windows). Este archivo contiene un esquema XML que describe completamente todos los elementos y atributos que componen un archivo de configuración. Cada elemento y cada atributo de este archivo se comenta con una descripción que documenta el uso de ese elemento o atributo.