Outil d’enregistreur de tests VSS
L’enregistreur de tests est un utilitaire que vous pouvez utiliser pour tester les applications de demandeur VSS. Cet enregistreur peut être configuré pour effectuer presque toutes les actions qu’un enregistreur VSS peut effectuer. En outre, l’enregistreur de tests effectue des vérifications approfondies pour s’assurer que le demandeur a traité ces actions d’enregistreur correctement.
Chaque instance de l’enregistreur est initialisé avec un fichier de configuration XML qui décrit exactement les composants que l’enregistreur doit signaler et le comportement de l’enregistreur. L’enregistreur peut être configuré pour créer des rapports sur différents types de scénarios, y compris des scénarios plus complexes à l’aide des interfaces incrémentielles et différentielles. L’enregistreur effectue des vérifications à différents moments du processus pour s’assurer que le demandeur se comporte correctement. Une fois la restauration terminée, l’enregistreur case activée que tous les fichiers nécessaires ont été restaurés sans altération. L’enregistreur peut également être configuré pour effectuer d’autres opérations telles que l’échec d’événements spécifiques.
Notes
Cet outil est inclus dans le Kit de développement logiciel (SDK) Microsoft Windows pour Windows Vista et versions ultérieures. Vous pouvez télécharger le Kit de développement logiciel (SDK) Windows à partir de https://msdn.microsoft.com/windowsvista.
Dans l’installation du Kit de développement logiciel (SDK) Windows, l’outil VssSampleProvider se trouve dans %Program Files(x86)%\Windows Kits\8.1\bin\x64 (pour Windows 64 bits) et %Program Files(x86)%\Windows Kits\8.1\bin\x86.
Exécution de l’outil Enregistreur de tests
Pour démarrer l’enregistreur de tests, tapez ce qui suit à l’invite de commandes :
vswriter.exefichier de configuration
où config-file est le chemin d’accès à un fichier de configuration qui spécifie le comportement de cet enregistreur.
Pour arrêter l’enregistreur de tests, appuyez sur Ctrl+C.
Plusieurs instances de l’enregistreur de tests peuvent être exécutées en même temps. Toutefois, chaque instance de l’enregistreur signale le même ID de classe writer (bien qu’un autre enregistreur instance ID), de sorte que les chemins logiques et les noms de composants doivent être uniques pour toutes les instances en cours d’exécution simultanée de l’enregistreur.
Pour garantir que l’enregistreur peut correctement case activée que le demandeur a respecté les spécifications de fichier d’exclusion, tous les fichiers sauvegardés doivent être supprimés du volume d’origine avant de tenter de les restaurer. Il est recommandé de stocker un modèle de chaque scénario d’enregistreur afin que le scénario puisse être facilement recréé.
Utilisation d'un fichier de configuration
L’exemple de fichier de configuration suivant, vswriter_config.xml, se trouve dans %ProgramFiles%\Microsoft SDKs\Windows\v7.0\bin\vsstools sur les plateformes x86 et %ProgramFiles%\Microsoft SDKs\Windows\v7.0\bin\x64\vsstools sur les plateformes x64.
<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>
L’élément racine de ce fichier de configuration est nommé TestWriter. Tous les autres éléments sont organisés sous l’élément TestWriter.
L’un des attributs associés à TestWriter est l’attribut d’utilisation. Cet attribut spécifie le type d’utilisation signalé via IVssExamineWriterMetadata::GetIdentity. L’une des valeurs possibles pour cet attribut est USER_DATA.
Le premier élément enfant de l’élément racine doit toujours être un élément RestoreMethod. Cet élément spécifie les éléments suivants :
- Méthode de restauration (dans ce cas, RESTORE_IF_CAN_BE_REPLACED)
- Indique si l’enregistreur nécessite des événements de restauration (dans ce cas, toujours)
- Si un redémarrage est nécessaire après la restauration de l’enregistreur (dans ce cas, non)
Cet élément peut éventuellement spécifier un mappage d’emplacement de substitution. (Dans ce cas, aucun autre emplacement n’est spécifié.)
Le deuxième élément enfant est un élément ExcludeFile. Cet élément oblige l’enregistreur à exclure un fichier ou un ensemble de fichiers de la sauvegarde.
Le troisième élément enfant est un élément Component. Cet élément oblige l’enregistreur à ajouter un composant à ses métadonnées. Un élément Component contient des attributs pour décrire le composant et des éléments enfants pour décrire le contenu du composant, tels que les suivants :
- componentType pour indiquer s’il s’agit d’un groupe de fichiers ou d’une base de données
- logicalPath pour le chemin logique du composant
- componentName pour le nom du composant
- sélectionnable pour indiquer le status selectable-for-backup
L’élément Component a également un élément enfant nommé ComponentFile pour ajouter une spécification de fichier à ce composant. (Un élément Component peut avoir un nombre arbitraire d’éléments ComponentFile qui peuvent être spécifiés pour chaque composant.) Cet élément ComponentFile possède les attributs suivants :
- path="c:\writerData\myFilesHere »
- filespec="* »
- recursive="no »
Bien que l’enregistreur de tests vérifie le comportement du demandeur, il ne vérifie pas que le fichier de configuration conserve toujours la sémantique documentée pour un enregistreur. Il existe de nombreuses opérations qu’un enregistreur bien comportementé ne doit pas effectuer (comme signaler le même fichier dans plusieurs composants), et il incombe à l’auteur du fichier de configuration XML de gérer ces sémantiques.
Configuration des attributs de l’enregistreur
L’élément racine TestWriter contient des attributs qui déterminent différents comportements de l’enregistreur. Voici quelques-uns des comportements qui peuvent être modifiés :
| Attribut | Description |
|---|---|
| Verbosité |
L’enregistreur imprime les status sur la console à mesure qu’il reçoit des événements et les traite. Le niveau de détail affiché est spécifié par l’attribut verbosity. Il existe trois niveaux de détail parmi lesquels choisir :
|
| deleteFiles |
Pour effectuer une vérification supplémentaire, définissez cet attribut sur « oui » afin que l’enregistreur supprime tous ses fichiers immédiatement après la création du cliché instantané du volume. Le demandeur doit ensuite copier les fichiers à partir du cliché instantané, car ils n’existent plus sur le volume d’origine. Note: Dans le cas des enregistreurs de broches, les fichiers sont supprimés de l’emplacement d’origine après le crachat, mais avant la création du cliché instantané. Une fois le cliché instantané créé, les fichiers sont supprimés du répertoire spit. |
| deletePartialFiles |
Pour supprimer des fichiers partiels, définissez cet attribut sur « yes ». |
| deleteDifferencedFiles |
Pour supprimer les fichiers différentiels, définissez cet attribut sur « yes ». |
| checkIncludes |
Définissez cet attribut sur « oui » pour que l’enregistreur case activée que chaque fichier sauvegardé a été restauré à un emplacement approprié et que le fichier n’a pas été endommagé. Les fichiers partiels et les fichiers différentiels sont également correctement gérés. |
| checkExcludes |
Définissez cet attribut sur « yes » pour que l’enregistreur case activée que les fichiers correspondant à une spécification de fichier dans la liste d’exclusions ne soient pas restaurés. Pour que cela fonctionne correctement, les répertoires de restauration doivent être vidés avant la restauration. |
Spécification de mappages d’emplacements de remplacement
Un autre mappage d’emplacement spécifie un emplacement à restaurer si la méthode de restauration est VSS_WRE_RESTORE_TO_ALTERNATE_LOCATION ou si la restauration normale d’un composant échoue. Un enregistreur peut signaler ses mappages d’emplacements de remplacement au demandeur à l’aide de la méthode IVssExamineWriterMetadata::GetAlternateLocationMapping . Vous pouvez ajouter d’autres mappages d’emplacements au fichier de configuration Test Writer en ajoutant des sous-éléments AlternateLocationMapping à l’élément RestoreMethod.
L’élément RestoreMethod suivant contient un sous-élément AlternateLocationMapping.
<RestoreMethod method="RESTORE_IF_CAN_REPLACE"
writerRestore="always"
rebootRequired="no">
<AlternateLocationMapping path="c:\files"
filespec="*.txt"
recursive="no"
alternatePath="c:\altfiles"/>
</RestoreMethod>
Cet exemple spécifie que le demandeur doit d’abord tenter de restaurer tous les fichiers correspondant à c:\files\*.txt dans le répertoire c:\files. Si l’un de ces fichiers ne peut pas être remplacé, le demandeur doit restaurer tous les fichiers dans le répertoire c:\altfiles à la place. Le demandeur doit enregistrer ce mappage d’emplacement de remplacement à l’aide de la méthode IVssBackupComponents::AddAlternativeLocationMapping . Si l’enregistreur de tests est configuré pour case activée si les fichiers ont été restaurés, il case activée également si le demandeur a appelé AddAlternativeLocationMapping.
Spécification des fichiers à exclure
Chaque enregistreur peut spécifier une liste de spécifications de fichiers qui spécifient des fichiers que le demandeur doit exclure de la sauvegarde. Vous pouvez ajouter ces spécifications de fichier au fichier de configuration Test Writer en ajoutant des sous-éléments ExcludeFile à l’élément racine TestWriter.
Voici un exemple de sous-élément ExcludeFile qui exclut tous les fichiers du répertoire C:\files correspondant à C:\temp*.*.
<ExcludeFile path="c:\files"
filespec="temp*.*"
recursive="no"/>
Sauvegarde des enregistreurs de broches
De nombreux écrivains agissent comme des « écrivains crachés ». Un enregistreur de broches crée des fichiers intermédiaires, ou « fichiers crachés », en fonction d’un ensemble de fichiers d’origine, et place les fichiers crachés dans un autre emplacement au moment de la sauvegarde. L’enregistreur utilise la méthode IVssWMFiledesc::GetAlternateLocation pour informer le demandeur qu’il doit sauvegarder ces fichiers à partir de l’autre emplacement. Toutefois, ces fichiers doivent toujours être restaurés à l’emplacement actif des fichiers d’origine. L’enregistreur de test peut être configuré pour faire office d’enregistreur de broches pour une spécification de fichier particulière.
L’élément ComponentFile suivant contient un attribut alternatePath :
<ComponentFile path="c:\files"
filespec="*.txt"
recursive="no"
alternatePath="c:\files\spit" />
Cet exemple configure l’enregistreur de tests pour copier tous les fichiers correspondant à c:\files\*.txt dans le répertoire c:\files\spit juste avant la création du cliché instantané du volume. Le demandeur doit sauvegarder les fichiers du répertoire c:\files\spit. Si l’enregistreur de tests est configuré pour supprimer des fichiers, il supprime les fichiers d’origine avant la création du cliché instantané, de sorte qu’ils n’apparaissent pas dans le répertoire c:\files sur le volume de cliché instantané. Dans ce cas, les fichiers dans c:\files\spit sont supprimés après la création du cliché instantané. Ils doivent donc être sauvegardés à partir du répertoire c:\files\spit sur le volume de cliché instantané.
Dépendances des composants de création de rapports
Les rédacteurs peuvent spécifier une dépendance entre un composant local et un composant qui existe dans un autre enregistreur. Ces dépendances sont signalées au demandeur à l’aide d’IVssWMComponent::GetDependency. L’enregistreur de tests peut être configuré pour signaler ces dépendances en ajoutant un ou plusieurs sous-éléments de dépendance à l’élément Component.
L’élément Component suivant contient un sous-élément Dependency :
<Component componentType="filegroup"
logicalPath=""
componentName="WriterComponent"
selectable="yes">
<Dependency writerId="<GUID of target writer>"
logicalPath="ComponentPath"
componentName="Writer2Component" />
</Component>
La dépendance est spécifiée en tant qu’attributs de l’élément Dependency. writerId est l’ID de classe de l’enregistreur contenant la cible de la dépendance, logicalPath est le chemin logique du composant dans cet enregistreur et componentName est le nom du composant. Dans ce cas, si le demandeur sauvegarde « WriterComponent » dans l’enregistreur actuel, il doit également sauvegarder le composant « ComponentPath\Writer2Component » dans l’enregistreur cible.
Notes
L’enregistreur de tests n’effectue aucune vérification pour s’assurer que les dépendances sont respectées.
Événements défaillants
L’enregistreur de tests peut être configuré pour échouer tous les événements normaux reçus par un enregistreur. Ces événements sont les suivants :
| Événement | Description |
|---|---|
| Identifier |
Reçu en réponse à un appel IVssBackupComponents::GatherWriterMetadata . L’échec ici entraîne la non-signalement de l’enregistreur. |
| PrepareForBackup |
Reçu en réponse au demandeur appelant IVssBackupComponents::P repareForBackup. |
| PrepareForSnapsot |
Reçu lorsque le demandeur appelle IVssBackupComponents::D oSnapshotSet, mais avant la création du cliché instantané. |
| Gèlent |
Reçu immédiatement après PrepareForSnapshot, mais toujours avant la création du cliché instantané. |
| Décongelez |
Reçu une fois la création du cliché instantané terminé. |
| PostSnapshot |
Reçu une fois le dégel terminé, mais avant la fin d’IVssBackupComponents::D oSnapshotSet . |
| Annuler |
Reçu si trop de temps s’écoule entre le gel et le dégel ou si le demandeur appelle IVssBackupComponents::AbortBackup. |
| BackupComplete |
Reçu lors de la sortie du demandeur. Les échecs ici ne seront jamais signalés. |
| PreRestore |
Reçu lorsque le demandeur appelle IVssBackupComponents::P reRestore. |
| PostRestore |
Reçu lorsque le demandeur appelle IVssBackupComponents::P ostRestore. |
Ces échecs sont configurés en ajoutant un ou plusieurs sous-éléments FailEvent à l’élément racine TestWriter. Il existe deux classes d’échecs qui peuvent être définies : retenable et non nouvelle tentative. Les erreurs pouvant faire l’objet d’une nouvelle tentative sont des erreurs qui peuvent disparaître si l’ensemble du processus de sauvegarde est retenté, tandis que les erreurs non retenables sont peu susceptibles de disparaître. Le type d’échec de l’événement est choisi en fonction de l’attribut nouvelle tentative.
Voici un exemple d’échec de base non retenable :
<FailEvent writerEvent="Freeze"
retryable="no" />
Cet exemple entraîne l’échec de l’enregistreur pendant l’événement Freeze . IVssBackupComponents::GatherWriterStatus signale l’échec de l’enregistreur à VSS_E_WRITERERROR_NONRETRYABLE.
Voici un exemple d’erreur de base pouvant faire l’objet d’une nouvelle tentative :
<FailEvent writerEvent="Freeze"
retryable="yes"
numFailures="2"/>
Cet exemple entraîne l’échec de l’enregistreur lors des deux premières réceptions d’un événement Freeze . Après les deux premières fois, l’auteur réussit toujours. L’échec de l’enregistreur signalé via GatherWriterStatus sera un code d’erreur aléatoire pouvant faire l’objet d’une nouvelle tentative.
Déclaration des types de sauvegarde pris en charge
Les rédacteurs communiquent les types de sauvegarde pris en charge par le biais de l’appel d’IVssExamineWriterMetadata::GetBackupSchema du demandeur. L’élément racine TestWriter contient des attributs pour chaque type de sauvegarde pour indiquer la prise en charge. Ces attributs sont supportsCopy, supportsDifferential, supportsIncremental et supportsLog. Pour indiquer la prise en charge d’un type de sauvegarde particulier, définissez l’attribut correspondant sur « yes ».
Si le demandeur définit le type de sauvegarde sur un type de sauvegarde qui n’est pas pris en charge par l’enregistreur, l’enregistreur notera ce fait pendant PrepareForBackup, mais fonctionnera sinon correctement.
Indiquant le type de sauvegarde de fichier
La méthode IVssWMFiledesc::GetBackupTypeMask retourne un masque de bits au demandeur indiquant comment sauvegarder un fichier. Cela indique si un fichier est obligatoire ou non pendant des types de sauvegarde spécifiques, ainsi qu’un cliché instantané pendant des types spécifiques de sauvegarde. Les types de sauvegarde dans ce masque de bits sont expliqués plus en détail dans le document Rôle demandeur dans la sauvegarde des magasins complexes.
Dans l’enregistreur de test, les éléments de ce masque de bits sont spécifiés en définissant des attributs dans chaque élément ComponentFile. Les attributs fullBackupRequired, diffBackupRequired, incBackupRequired et logBackupRequired spécifient quand un fichier doit être sauvegardé. Les attributs fullSnapshotRequired, diffSnapshotRequired, incSnapshotRequired et logSnapshotRequired spécifient quand un fichier doit être sauvegardé à partir d’un cliché instantané d’un volume (et jamais à partir du volume d’origine). La valeur par défaut pour toutes ces valeurs est « yes », ce qui indique qu’un fichier doit toujours être sauvegardé et doit être sauvegardé à partir d’un cliché instantané d’un volume.
Ajout de fichiers partiels
Pendant le traitement de DoSnapshotSet, un enregistreur a la possibilité d’ajouter des fichiers partiels à chaque composant. Ces fichiers partiels sont signalés à l’aide d’IVssComponent::GetPartialFile. L’enregistreur de tests peut être configuré pour ajouter des fichiers partiels en spécifiant des sous-éléments PartialFile dans un élément Component.
Voici un exemple d’élément Component qui a deux sous-éléments PartialFile :
<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>
Seuls les fichiers partiels qui correspondent partiellement à un ComponentFile existant (comme dans le premier fichier partiel de l’exemple) ou les nouveaux fichiers partiels qui se trouvent sur le même volume qu’un ComponentFile existant (comme dans le deuxième fichier partiel) doivent être spécifiés de cette façon. Pour ce composant, le demandeur doit sauvegarder entièrement tous les fichiers correspondant à c:\files\*.txt à l’exception des partial.txt. Le demandeur doit ensuite sauvegarder les plages spécifiées (où une plage est un décalage suivi d’une longueur) pour les fichiers c:\files\partial.txt et c:\files2\partial.txt.
Si l’enregistreur est configuré pour case activée restaurations de fichiers, seules les plages sauvegardées du fichier partiel sont vérifiées au moment de la restauration. Les modifications apportées à d’autres parties du fichier passent inaperçues. Si l’attribut deletePartialFiles de l’élément racine TestWriter est défini, les fichiers partiels sont supprimés du volume d’origine immédiatement après la création du cliché instantané.
Ajout de fichiers différentiels
Pendant le traitement de DoSnapshotSet, un enregistreur peut ajouter des fichiers différents à chaque composant. Ces fichiers différents sont signalés à l’aide d’IVssComponent::GetDifferencedFile. L’enregistreur de tests peut être configuré pour ajouter des fichiers différentiels en spécifiant des sous-éléments DifferencedFile dans un élément Component.
Voici un exemple d’élément Component qui a deux sous-éléments 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>
Contrairement aux fichiers partiels, les fichiers différents ne doivent jamais correspondre partiellement à une spécification ComponentFile. La spécification de fichier d’un élément DifferencedFile doit correspondre exactement à un ComponentFile (comme dans le premier fichier différent de l’exemple) ou elle ne doit pas la correspondre du tout, mais se trouver sur un volume référencé dans un ComponentFile (comme dans le deuxième fichier différent). Les valeurs de date et d’heure doivent être relatives au fuseau horaire local, mais elles seront converties en GMT avant d’être signalées au demandeur. Dans l’exemple, seuls les fichiers correspondant à c:\files\*.txt ou c:\files2\*.txt qui ont été modifiés depuis le 22/1/2003:12:44:17 seront sauvegardés.
Si l’enregistreur de tests est configuré pour case activée les restaurations de fichiers, seuls les fichiers modifiés sont vérifiés pour la restauration. Si l’attribut deleteDifferencedFiles de l’élément racine TestWriter est défini, les fichiers différents sont supprimés du volume d’origine immédiatement après la création du cliché instantané.
Nouvelles cibles
Certains rédacteurs permettent au demandeur de l’informer qu’un nouvel emplacement a été choisi pour restaurer certains fichiers. L’enregistreur indique qu’il prend en charge ce mode dans le cadre du masque de bits retourné par IVssExamineWriterMetadata::GetBackupSchema. Par défaut, l’enregistreur de tests prend toujours en charge les nouvelles cibles. Cette prise en charge peut être désactivée en définissant l’attribut supportsNewTarget dans l’élément racine TestWriter sur « no ».
Si un enregistreur prend en charge de nouvelles cibles, le demandeur peut informer l’enregistreur de nouvelles cibles en appelant IVssBackupComponents::AddNewTarget. L’enregistreur case activée ensuite le nouvel emplacement cible pour vérifier la restauration plutôt que l’emplacement d’origine.
Informations complémentaires
L’enregistreur de tests prend en charge d’autres options de configuration qui ne sont pas décrites ici. Le schéma complet pour toutes les fonctionnalités de configuration de l’enregistreur de tests est spécifié dans swriter.xml dans %ProgramFiles%\Microsoft SDKs\Windows\v7.0\bin\x64\vsstools (pour Windows 64 bits) et %ProgramFiles%\Microsoft SDKs\Windows\v7.0\bin\vsstools (pour Windows 32 bits). Ce fichier contient un schéma XML qui décrit entièrement tous les éléments et attributs qui composent un fichier de configuration. Chaque élément et chaque attribut de ce fichier sont commentés avec une description qui documente l’utilisation de cet élément ou de cet attribut.
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour