Strumento vss test writer

Articolo
06/13/2023

Test Writer è un'utilità che è possibile usare per testare le applicazioni richiedente VSS. Questo writer può essere configurato per eseguire quasi tutte le azioni che un writer VSS può eseguire. Inoltre, il writer di test esegue controlli estesi per garantire che il richiedente abbia gestito correttamente queste azioni writer.

Ogni istanza del writer viene inizializzata con un file di configurazione XML che descrive esattamente i componenti che il writer reportrà e il comportamento del writer. Il writer può essere configurato per segnalare vari tipi di scenari, inclusi scenari più complessi usando le interfacce incrementali e differenziali. Il writer eseguirà controlli in vari punti durante il processo per garantire che il richiedente si comporti correttamente. Al termine del ripristino, il writer verificherà che tutti i file necessari siano stati ripristinati senza danneggiamento. Il writer può anche essere configurato per eseguire altre operazioni, ad esempio errori di eventi specifici.

Nota

Questo strumento è incluso in Microsoft Windows Software Development Kit (SDK) per Windows Vista e versioni successive. È possibile scaricare Windows SDK da https://msdn.microsoft.com/windowsvista.

Nell'installazione di Windows SDK, lo strumento VssSampleProvider è disponibile in %Program Files(x86)%\Windows Kits\8.1\bin\x64 (per Windows a 64 bit) e %Program Files(x86)%\Windows Kits\8.1\bin\x86.

Esecuzione dello strumento Writer di test

Per avviare Test Writer, digitare quanto segue al prompt dei comandi:

vswriter.exefile config-file

dove config-file è il percorso di un file di configurazione che specifica il comportamento di questo writer.

Per arrestare il writer di test, premere CTRL+C.

È possibile eseguire più istanze del writer di test contemporaneamente. Tuttavia, ogni istanza del writer segnala lo stesso ID classe writer (anche se un ID istanza del writer diverso), pertanto i percorsi logici e i nomi dei componenti devono essere univoci in tutte le istanze in esecuzione simultanea del writer.

Per assicurarsi che il writer possa verificare correttamente che il richiedente abbia rispettato le specifiche del file di esclusione, tutti i file di cui è stato eseguito il backup devono essere eliminati dal volume originale prima di tentare di ripristinarli. È consigliabile archiviare un modello di ogni scenario writer, in modo che lo scenario possa essere ricreato facilmente.

Uso di un file di configurazione

Il file di configurazione di esempio seguente, vswriter_config.xml, è disponibile in nelle %ProgramFiles%\Microsoft SDKs\Windows\v7.0\bin\vsstools piattaforme x86 e %ProgramFiles%\Microsoft SDKs\Windows\v7.0\bin\x64\vsstools nelle piattaforme 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'elemento radice in questo file di configurazione è denominato TestWriter. Tutti gli altri elementi vengono disposti sotto l'elemento TestWriter.

Uno degli attributi associati a TestWriter è l'attributo di utilizzo. Questo attributo specifica il tipo di utilizzo segnalato tramite IVssExamineWriterMetadata::GetIdentity. Uno dei valori possibili per questo attributo è USER_DATA.

Il primo elemento figlio dell'elemento radice deve essere sempre un elemento RestoreMethod. Questo elemento specifica quanto segue:

Metodo restore (in questo caso, RESTORE_IF_CAN_BE_REPLACED)
Indica se il writer richiede eventi di ripristino (in questo caso, sempre)
Indica se è necessario un riavvio dopo il ripristino del writer (in questo caso, no)

Questo elemento può facoltativamente specificare un mapping di percorso alternativo. In questo caso non viene specificata alcuna posizione alternativa.

Il secondo elemento figlio è un elemento ExcludeFile. Questo elemento fa sì che il writer escluda un file o un set di file dal backup.

Il terzo elemento figlio è un elemento Component. Questo elemento fa sì che il writer aggiunga un componente ai relativi metadati. Un elemento Component contiene attributi per descrivere il componente e gli elementi figlio per descrivere il contenuto del componente, ad esempio:

componentType per indicare se si tratta di un filegroup o di un database
logicalPath per il percorso logico del componente
componentName per il nome del componente
selezionabile per indicare lo stato selezionabile per il backup

L'elemento Component include anche un elemento figlio denominato ComponentFile per aggiungere una specifica di file a questo componente. Un elemento Component può avere un numero arbitrario di elementi ComponentFile che possono essere specificati per ogni componente. Questo elemento ComponentFile ha gli attributi seguenti:

path="c:\writerData\myFilesHere"
filespec="*"
ricorsivo="no"

Anche se il writer di test verifica il comportamento del richiedente, non verifica che il file di configurazione mantenga sempre la semantica documentata per un writer. Esistono molte operazioni che un writer ben comportato non deve eseguire (ad esempio, segnalare lo stesso file in più componenti) ed è l'autore del file di configurazione XML per mantenere questa semantica.

Configurazione degli attributi del writer

L'elemento radice TestWriter contiene attributi che determinano diversi comportamenti del writer. Alcuni dei comportamenti che possono essere modificati sono i seguenti:

Attributo	Descrizione
Dettaglio	Il writer stampa lo stato nella console quando riceve gli eventi ed elabora tali eventi. Il livello di dettaglio visualizzato viene specificato dall'attributo verbosity. Esistono tre livelli di dettaglio tra cui scegliere: Basso Verranno stampati solo gli errori nel writer o il comportamento non corretto del richiedente. Medio Tutto a livello di dettaglio basso viene stampato oltre a informazioni aggiuntive sullo stato, ad esempio quando vengono ricevuti eventi. Si tratta del livello predefinito. alto Vengono segnalate informazioni dettagliate sullo stato relative al funzionamento del writer.
deleteFiles	Per eseguire una verifica aggiuntiva, impostare questo attributo su "sì" per fare in modo che il writer elimini tutti i file immediatamente dopo la creazione della copia shadow del volume. Il richiedente deve quindi copiare i file dalla copia shadow, perché non esistono più nel volume originale. Nota: Nel caso dei writer spit, i file vengono eliminati dalla posizione originale dopo lo spit, ma prima della creazione della copia shadow. Dopo aver creato la copia shadow, i file vengono eliminati dalla directory spit.
deletePartialFiles	Per eliminare i file parziali, impostare questo attributo su "sì".
deleteDifferencedFiles	Per eliminare i file con differenza, impostare questo attributo su "sì".
checkIncludes	Impostare questo attributo su "sì" per fare in modo che il writer verifichi che ogni file di cui è stato eseguito il backup sia stato ripristinato in un percorso appropriato e che il file non sia danneggiato. Anche i file parziali e i file con differenze vengono gestiti correttamente.
checkExcludes	Impostare questo attributo su "sì" per fare in modo che il writer controlli che i file corrispondenti a una specifica di file nell'elenco di esclusione non vengano ripristinati. Affinché funzioni correttamente, è necessario svuotare le directory di ripristino prima del ripristino.

Specifica dei mapping di percorsi alternativi

Un mapping di percorso alternativo specifica un percorso in cui eseguire il ripristino se il metodo di ripristino è VSS_WRE_RESTORE_TO_ALTERNATE_LOCATION o se il normale ripristino di un componente ha esito negativo. Un writer può segnalare i mapping di posizione alternativi al richiedente usando il metodo IVssExamineWriterMetadata::GetAlternateLocationMapping . È possibile aggiungere mapping di percorsi alternativi al file di configurazione test writer aggiungendo sottoelementi AlternateLocationMapping all'elemento RestoreMethod.

L'elemento RestoreMethod seguente contiene un sottoelemento AlternateLocationMapping.

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

In questo esempio viene specificato che il richiedente deve prima tentare di ripristinare tutti i file corrispondenti a c:\files\*.txt nella directory c:\files. Se non è possibile sostituire uno di questi file, il richiedente deve ripristinare tutti i file nella directory c:\altfiles. Il richiedente deve salvare questo mapping di percorso alternativo usando il metodo IVssBackupComponents::AddAlternativeLocationMapping . Se il writer di test è configurato per verificare se i file sono stati ripristinati, verificherà anche se il richiedente ha chiamato AddAlternativeLocationMapping.

Specifica dei file da escludere

Ogni writer può specificare un elenco di specifiche di file che specificano i file per il richiedente da escludere dal backup. È possibile aggiungere queste specifiche di file al file di configurazione test writer aggiungendo sottoelementi ExcludeFile all'elemento radice TestWriter.

Di seguito è riportato un esempio di sottoelemento ExcludeFile che esclude tutti i file nella directory C:\files che corrispondono a C:\temp*.*.

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

Backup di writer spit

Molti scrittori agiscono come "spit writer". Un writer spit crea file intermedi o "file spit", in base a un set originale di file e inserisce i file spit in un percorso alternativo in fase di backup. Il writer usa il metodo IVssWMFiledesc::GetAlternateLocation per notificare al richiedente che deve eseguire il backup di questi file dal percorso alternativo. Tuttavia, questi file devono comunque essere ripristinati nel percorso attivo dei file originali. Il writer di test può essere configurato per fungere da writer spit per una specifica di file specifica.

L'elemento ComponentFile seguente contiene un attributo alternatePath:

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

In questo esempio viene configurato test writer per copiare tutti i file corrispondenti a c:\files\*.txt nella directory c:\files\spit immediatamente prima della creazione della copia shadow del volume. Il richiedente deve eseguire il backup dei file dalla directory c:\files\spit. Se il writer di test è configurato per eliminare i file, elimina i file originali prima della creazione della copia shadow, quindi non vengono visualizzati nella directory c:\files nel volume di copia shadow. In questo caso, i file in c:\files\spit vengono eliminati dopo la creazione della copia shadow, quindi devono essere sottoposti a backup dalla directory c:\files\spit nel volume di copia shadow.

Dipendenze del componente di creazione di report

I writer possono specificare una dipendenza tra un componente locale e un componente presente in un altro writer. Queste dipendenze vengono segnalate al richiedente usando IVssWMComponent::GetDependency. Il writer di test può essere configurato per segnalare queste dipendenze aggiungendo uno o più sottoelementi Dependency all'elemento Component.

L'elemento Component seguente contiene un sottoelemento Dependency:

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

La dipendenza viene specificata come attributi dell'elemento Dependency. writerId è l'ID classe del writer contenente la destinazione della dipendenza, logicalPath è il percorso logico del componente in tale writer e componentName è il nome del componente. In questo caso, se il richiedente esegue il backup di "WriterComponent" nel writer corrente, deve eseguire anche il backup del componente "ComponentPath\Writer2Component" nel writer di destinazione.

Nota

Il writer di test non esegue alcun controllo per assicurarsi che le dipendenze siano rispettate.

Eventi non riusciti

Il writer di test può essere configurato per non riuscire in uno degli eventi normali ricevuti da un writer. Questi eventi sono i seguenti:

Event	Descrizione
Identificare	Ricevuto come risposta a una chiamata IVssBackupComponents::GatherWriterMetadata . In questo caso, il writer non verrà segnalato.
PrepareForBackup	Ricevuta come risposta al richiedente che chiama IVssBackupComponents::P repareForBackup.
PrepareForSnapsot	Ricevuto quando il richiedente chiama IVssBackupComponents::D oSnapshotSet, ma prima della creazione della copia shadow.
Congelare	Ricevuto immediatamente dopo PrepareForSnapshot, ma ancora prima della creazione della copia shadow.
Disgelo	Ricevuto al termine della creazione della copia shadow.
PostSnapshot	Ricevuto dopo il completamento di Thaw, ma prima che IVssBackupComponents::D oSnapshotSet venga completato.
Interrompere	Ricevuto se è trascorso troppo tempo tra Freeze e Thaw o se il richiedente chiama IVssBackupComponents::AbortBackup.
BackupComplete	Ricevuto al termine dell'uscita del richiedente. Gli errori qui non verranno mai segnalati.
PreRestore	Ricevuto quando il richiedente chiama IVssBackupComponents::P reRestore.
PostRestore	Ricevuto quando il richiedente chiama IVssBackupComponents::P ostRestore.

Questi errori vengono configurati aggiungendo uno o più sottoelementi FailEvent all'elemento radice TestWriter. Esistono due classi di errori che possono essere impostate: riprovabili e non riprovabili. Gli errori riprovabili sono errori che potrebbero andare via se l'intero processo di backup viene riprovato, mentre gli errori non riprovabili sono improbabili che scompaiano. Il tipo di errore per l'evento viene scelto in base all'attributo riprovabile.

Ecco un esempio di errore non riprovabile di base:

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

In questo esempio il writer avrà esito negativo durante l'evento Freeze . IVssBackupComponents::GatherWriterStatus segnala l'errore del writer VSS_E_WRITERERROR_NONRETRYABLE.

Ecco un esempio di errore retryable di base:

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

In questo esempio il writer avrà esito negativo la prima volta che riceve un evento Freeze . Dopo le prime due volte, il writer avrà sempre esito positivo. L'errore del writer segnalato tramite GatherWriterStatus sarà un codice di errore retryable casuale.

Dichiarazione dei tipi di backup supportati

I writer comunicano quali tipi di backup sono supportati tramite la chiamata di IVssExamineWriterMetadata::GetBackupSchema. L'elemento radice TestWriter contiene attributi per ogni tipo di backup per indicare il supporto. Questi attributi sono supportatiCopy, supportaDifferential, supportaIncrementale e supportLog. Per indicare il supporto per un tipo di backup specifico, impostare l'attributo corrispondente su "sì".

Se il richiedente imposta il tipo di backup su un tipo di backup che non è supportato dal writer, il writer noterà questo fatto durante PrepareForBackup, ma in caso contrario funziona correttamente.

Indicazione del tipo di backup del file

Il metodo IVssWMFiledesc::GetBackupTypeMask restituisce una maschera di bit al richiedente che indica come eseguire il backup di un file. In questo modo verrà indicato se è necessario un file o meno durante specifici tipi di backup e anche se è necessaria una copia shadow durante tipi specifici di backup. I tipi di backup in questa maschera di bit vengono spiegati con maggiore lunghezza nel ruolo del richiedente documento in Backup di archivi complessi.

Nel writer di test gli elementi di questa maschera bit vengono specificati impostando gli attributi in ogni elemento ComponentFile. Gli attributi fullBackupRequired, diffBackupRequired, incBackupRequired e logBackupRequired specificano quando è necessario eseguire il backup di un file. Gli attributi fullSnapshotRequired, diffSnapshotRequired, incSnapshotRequired e logSnapshotRequired specificano quando un file deve essere eseguito il backup da una copia shadow di un volume (e non dal volume originale). Il valore predefinito per tutti questi valori è "sì", che indica che un file deve sempre essere eseguito il backup e deve essere eseguito il backup da una copia shadow di un volume.

Aggiunta di file parziali

Durante l'elaborazione di DoSnapshotSet, un writer ha la possibilità di aggiungere file parziali a ogni componente. Questi file parziali vengono segnalati usando IVssComponent::GetPartialFile. Il writer di test può essere configurato per aggiungere file parziali specificando i sottoelementi PartialFile in un elemento Component.

Di seguito è riportato un esempio di elemento Component con due sottoelementi 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>

È necessario specificare in questo modo solo i file parziali che corrispondono parzialmente a un ComponentFile esistente (come nel primo file parziale nell'esempio) o nuovi file parziali che si trovano nello stesso volume di un ComponentFile esistente (come nel secondo file parziale). Per questo componente, il richiedente deve eseguire il backup completo di tutti i file corrispondenti a c:\files\*.txt ad eccezione di partial.txt. Il richiedente deve quindi eseguire il backup degli intervalli specificati (in cui un intervallo è un offset seguito da una lunghezza) per i file c:\files\partial.txt e c:\files2\partial.txt.

Se il writer è configurato per controllare i ripristini dei file, verranno controllati in fase di ripristino solo gli intervalli di backup del file parziale. Le modifiche ad altre parti del file verranno annullate. Se l'attributo deletePartialFiles dell'elemento radice TestWriter è impostato, i file parziali vengono eliminati dal volume originale immediatamente dopo la creazione della copia shadow.

Aggiunta di file con differenze

Durante l'elaborazione di DoSnapshotSet, un writer può aggiungere file diversi a ogni componente. Questi file con differenza vengono segnalati usando IVssComponent::GetDifferencedFile. Il writer di test può essere configurato per aggiungere file differenzati specificando i sottoelementi DifferencedFile in un elemento Component.

Ecco un esempio di elemento Component con due sottoelementi 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 differenza dei file parziali, i file con differenza non devono mai corrispondere parzialmente a una specifica ComponentFile. La specifica del file in un elemento DifferencedFile deve corrispondere esattamente a Un ComponentFile (come nel primo file con differenza nell'esempio) o non deve corrispondere a esso, ma essere in un volume a cui si fa riferimento in un ComponentFile (come nel secondo file con differenza). I valori di data e ora devono essere relativi al fuso orario locale, ma verranno convertiti in GMT prima di essere segnalati al richiedente. Nell'esempio solo i file corrispondenti a c:\files\*.txt o c:\files2\*.txt modificati dal 1/22/2003:12:44:17 verranno sottoposti a backup.

Se il writer di test è configurato per controllare i ripristini dei file, verranno controllati solo i file modificati per il ripristino. Se l'attributo deleteDifferencedFiles dell'elemento radice TestWriter è impostato, i file differenzati vengono eliminati dal volume originale immediatamente dopo la creazione della copia shadow.

Nuove destinazioni

Alcuni writer consentono al richiedente di informarli che una nuova posizione è stata scelta per ripristinare determinati file. Il writer indica che supporta questa modalità come parte della maschera bit restituita da IVssExamineWriterMetadata::GetBackupSchema. Per impostazione predefinita, il writer di test supporta sempre nuove destinazioni. Questo supporto può essere disabilitato impostando l'attributo supportNewTarget nell'elemento radice TestWriter su "no".

Se un writer supporta nuove destinazioni, il richiedente può informare il writer di nuove destinazioni chiamando IVssBackupComponents::AddNewTarget. Il writer verificherà quindi la nuova posizione di destinazione per verificare il ripristino anziché la posizione originale.

Altre informazioni

Il writer di test supporta altre opzioni di configurazione che non sono descritte qui. Lo schema completo per tutte le funzionalità di configurazione del writer di test viene specificato in swriter.xml in %ProgramFiles%\Microsoft SDKs\Windows\v7.0\bin\x64\vsstools (per Windows a 64 bit) e %ProgramFiles%\Microsoft SDKs\Windows\v7.0\bin\vsstools (per Windows a 32 bit). Questo file contiene uno schema XML che descrive completamente tutti gli elementi e gli attributi che costituiscono un file di configurazione. Ogni elemento e ogni attributo in questo file viene commentato con una descrizione che documenta l'uso dell'elemento o dell'attributo.

Condividi tramite