Interface IVssBackupComponents

The IVssBackupComponents class is used by a requester to poll writers about file status and to run backup/restore operations.

Inherited Members

IDisposable.Dispose()

Namespace: Alphaleonis.Win32.Vss

Assembly: AlphaVSS.Common.dll

Syntax

public interface IVssBackupComponents : IDisposable

Remarks

note

A IVssBackupComponents object can be used for only a single backup, restore, or Query operation.

After the backup, restore, or Query operation has either successfully finished or been explicitly terminated, a requester must release the IVssBackupComponents object by calling Dispose(). A IVssBackupComponents object must not be reused. For example, you cannot perform a backup or restore operation with the same IVssBackupComponents object that you have already used for a Query operation.

For information on how to retrieve an instance of IVssBackupComponents for the current operating system, see IVssFactory.

Properties

WriterComponents

A read-only list containing information about the components of each writer that has been stored in a requester's Backup Components Document.

Declaration

IList<IVssWriterComponents> WriterComponents { get; }

Property Value

Type	Description
IList<IVssWriterComponents>	A read-only list containing information about the components of each writer that has been stored in a requester's Backup Components Document.

Remarks

WriterComponents retrieves component information for a component stored in the Backup Components Document by earlier calls to AddComponent(Guid, Guid, VssComponentType, String, String).

The information in the components stored in the Backup Components Document is not static. If a writer updates a component during a restore, that change will be reflected in the component retrieved by WriterComponents. This is in contrast with component information found in the IVssWMComponent object returned by Components. That information is read-only and comes from the Writer Metadata Document of a writer process.

The IVssWriterComponents instances that are returned should not be cached, because the following IVssBackupComponents methods cause the instances that are returned by WriterComponents to be no longer valid:

• PrepareForBackup()
• DoSnapshotSet()
• BackupComplete()
• PreRestore()
• PostRestore()

If you call one of these methods after you have retrieved a IVssWriterComponents instance by calling WriterComponents, you cannot reuse that instance, because it is no longer valid. Instead, you must call WriterComponents again to retrieve a new IVssWriterComponents instance.

caution

This list must not be accessed after the IVssBackupComponents from which it was obtained has been disposed.

Exceptions

Type	Condition
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.

WriterMetadata

A read-only list containing metadata for the writers running on the systsem.

Declaration

IList<IVssExamineWriterMetadata> WriterMetadata { get; }

Property Value

Type	Description
IList<IVssExamineWriterMetadata>	A read-only list containing metadata for the writers running on the system. caution This list must not be accessed after the IVssBackupComponents from which it was obtained has been disposed.

Remarks

A requester must call the asynchronous operation GatherWriterMetadata() and wait for it to complete prior to using WriterMetadata.

Although GatherWriterMetadata() must be called prior to either a restore or backup operation, WriterMetadata is not typically used for restores.

Component information retrieved (during backup operations) using Components, where the IVssExamineWriterMetadata instance has been returned by WriterMetadata, comes from the Writer Metadata Document of a live writer process.

This is in contrast to the information returned by WriterComponents (during restore operations), which was stored in the Backup Components Document by calls to AddComponent(Guid, Guid, VssComponentType, String, String).

Exceptions

Type	Condition
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssInvalidXmlDocumentException	The XML document is not valid. Check the event log for details.
VssObjectNotFoundException	The specified shadow copy does not exist.

WriterStatus

A read-only list containing the status of the writers.

Declaration

IList<VssWriterStatusInfo> WriterStatus { get; }

Property Value

Type	Description
IList<VssWriterStatusInfo>	A read-only list containing VssWriterStatusInfo instances representing the returned status for each respective writer. caution This list must not be accessed after the IVssBackupComponents from which it was obtained has been disposed.

Remarks

A requester must call the asynchronous operation GatherWriterStatus() and wait for it to complete prior to using WriterStatus.

Exceptions

Type	Condition
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The specified shadow copy does not exist.

Methods

AbortBackup()

The AbortBackup method notifies VSS that a backup operation was terminated.

This method must be called if a backup operation terminates after the creation of a shadow copy set with StartSnapshotSet() and before DoSnapshotSet()returns.

If AbortBackup is called and no shadow copy or backup operations are underway, it is ignored.

Declaration

void AbortBackup()

Exceptions

Type	Condition
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized.

AddAlternativeLocationMapping(Guid, VssComponentType, String, String, String, String, Boolean, String)

The AddAlternativeLocationMapping method is used by a requester to indicate that an alternate location mapping was used to restore all the members of a file set in a given component.

Declaration

void AddAlternativeLocationMapping(Guid writerId, VssComponentType componentType, string logicalPath, string componentName, string path, string filespec, bool recursive, string destination)

Parameters

Type	Name	Description
Guid	writerId	Globally unique identifier (GUID) of the writer class that exported the component.
VssComponentType	componentType	Type of the component.
String	logicalPath	String containing the logical path to the component. The logical path can be null. There are no restrictions on the characters that can appear in a non-null logical path.
String	componentName	The component name.
String	path	The path to the directory that originally contained the file to be relocated. This path must be local to the VSS machine. The path can contain environment variables (for example, %SystemRoot%) but cannot contain wildcard characters. UNC paths are not supported. There is no requirement that the path end with a backslash ("\"). It is up to applications that retrieve this information to check.
String	filespec	String containing the original file specification. A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters.
Boolean	recursive	Boolean indicating whether the path specified by the path parameter identifies only a single directory or if it indicates a hierarchy of directories to be traversed recursively. The Boolean is true if the path is treated as a hierarchy of directories to be traversed recursively and false if not.
String	destination	The name of the directory where the file will be relocated. This path must be local to the VSS machine. UNC paths are not supported.

Exceptions

Type	Condition
ArgumentException	One of the parameters is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssInvalidXmlDocumentException	The XML document is not valid. Check the event log for details.
VssObjectNotFoundException	The specified component does not exist.

AddComponent(Guid, Guid, VssComponentType, String, String)

The AddComponent method is used to explicitly add to the backup set in the Backup Components Document all required components (nonselectable for backup components without a selectable for backup ancestor), and such optional (selectable for backup) components as the requester considers necessary. Members of component sets (components with a selectable for backup ancestor) are implicitly included in the backup set, but are not explicitly added to the Backup Components Document.

Declaration

void AddComponent(Guid instanceId, Guid writerId, VssComponentType componentType, string logicalPath, string componentName)

Parameters

Type	Name	Description
Guid	instanceId	Identifies a specific instance of a writer.
Guid	writerId	Writer class identifier.
VssComponentType	componentType	Identifies the type of the component.
String	logicalPath	String containing the logical path of the selectable for backup component. A logical path is not required when adding a component. Therefore, the value of this parameter can be null. There are no restrictions on the characters that can a logical path.
String	componentName	String containing the name of the selectable for backup component. The value of this parameter cannot be langword_csharp_nulL. There are no restrictions on the characters that can appear in a logical path.

Exceptions

Type	Condition
ArgumentException	One of the parameters is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssInvalidXmlDocumentException	The XML document is not valid. Check the event log for details.
VssObjectAlreadyExistsException	The object is a duplicate. A component with the same logical path and component name already exists.

AddNewTarget(Guid, VssComponentType, String, String, String, String, Boolean, String)

The AddNewTarget method is used by a requester during a restore operation to indicate that the backup application plans to restore files to a new location.

Declaration

void AddNewTarget(Guid writerId, VssComponentType componentType, string logicalPath, string componentName, string path, string fileName, bool recursive, string alternatePath)

Parameters

Type	Name	Description
Guid	writerId	Globally unique identifier (GUID) of the writer class containing the files that are to receive a new target.
VssComponentType	componentType	Identifies the type of the component, see the documentation for VssComponentType for more information.
String	logicalPath	String containing the logical path of the component containing the files that are to receive a new restore target. The value of the string containing the logical path used here should be the same as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String). The logical path can be null. There are no restrictions on the characters that can appear in a non-null logical path.
String	componentName	The name of the component containing the files that are to receive a new restore target. The string should not be null and should contain the same component name as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String). There are no restrictions on the characters that can appear in a non-NULL logical path.
String	path	The name of the directory or directory hierarchy containing the files to receive a new restore target. The path can contain environment variables (for example, %SystemRoot%) but cannot contain wildcard characters. There is no requirement that the path end with a backslash ("\"). It is up to applications that retrieve this information to check.
String	fileName	The file specification of the files to receive a new restore target. A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters.
Boolean	recursive	Boolean indicating whether only the files in the directory defined by path and matching the file specification provided by fileName are to receive a new restore target, or if all files in the hierarchy defined by pathand matching the file specification provided by fileName are to receive a new restore target.
String	alternatePath	The fully qualified path of the new restore target directory.

Remarks

note

This method is not supported on Windows XP

Exceptions

Type	Condition
ArgumentException	One of the parameters is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The component does not exist or the path and file specification do not match a component and file specification in the component.
VssInvalidXmlDocumentException	The XML document is not valid. Check the event log for details.
NotSupportedException	The operation is not supported on the current operating system.

AddRestoreSubcomponent(Guid, VssComponentType, String, String, String, String)

The AddRestoreSubcomponent method indicates that a Subcomponent member of a component set, which had been marked as nonselectable for backup but is marked selectable for restore, is to be restored irrespective of whether any other member of the component set will be restored.

Declaration

void AddRestoreSubcomponent(Guid writerId, VssComponentType componentType, string logicalPath, string componentName, string subcomponentLogicalPath, string subcomponentName)

Parameters

Type	Name	Description
Guid	writerId	Globally unique identifier (GUID) of the writer class containing the files that are to receive a new target.
VssComponentType	componentType	Identifies the type of the component, see the documentation for VssComponentType for more information.
String	logicalPath	String containing the logical path of the component in the backup document that defines the backup component set containing the Subcomponent to be added for restore. The logical path can be null. There are no restrictions on the characters that can appear in a non-null logical path.
String	componentName	The logical path of the component in the backup document that defines the backup component set containing the Subcomponent to be added for restore. The string should not be null and should contain the same component name as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String). There are no restrictions on the characters that can appear in a non-NULL component name.
String	subcomponentLogicalPath	The logical path of the Subcomponent to be added for restore. A logical path is required when adding a Subcomponent. Therefore, the value of this parameter cannot be null. There are no restrictions on the characters that can appear in a non-NULL logical path.
String	subcomponentName	The logical name of the Subcomponent to be added for restore. The value of this parameter cannot be null. There are no restrictions on the characters that can appear in a non-NULL component name.

Exceptions

Type	Condition
ArgumentException	One of the parameters is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The component does not exist.
VssInvalidXmlDocumentException	The XML document is not valid. Check the event log for details.

AddSnapshotToRecoverySet(Guid, String)

Specifies the volumes to be included in a LUN resynchronization operation. This method is supported only on Windows server operating systems.

Declaration

void AddSnapshotToRecoverySet(Guid snapshotId, string destinationVolume)

Parameters

Type	Name	Description
Guid	snapshotId	The identifier of the shadow copy that was returned by the AddToSnapshotSet(String, Guid) method during backup. This parameter is required and cannot be Guid.Empty.
String	destinationVolume	This parameter is optional and can be null. A value of null means that the contents of the shadow copy volume are to be copied back to the original volume. VSS identifies the original volume by the VDS_LUN_INFO information in the Backup Components Document.

Remarks

note

Windows XP, Windows 2003, Windows Vista, Windows 2008, Windows 7: This method requires Windows Server 2008 R2.

Exceptions

Type	Condition
ArgumentException	One of the parameter values is not valid.
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	Either there is no hardware provider that supports the operation, or the requester did not successfully add any volumes to the recovery set.
VssLegacyProviderException	This version of the hardware provider does not support this operation.
VssObjectNotFoundException	The snapshotId parameter specifies a shadow copy that the hardware provider does not own.
VssResyncInProgressException	Another LUN resynchronization operation is already in progress.
VssSnapshotNotInSetException	The snapshotId parameter specifies a shadow copy that does not exist in the Backup Components Document.
VssVolumeNotSupportedException	LUN resynchronization is not supported on this volume, because it is a dynamic volume, because the destination disk does not have a unique page 83 storage identifier, because the specified volume does not reside on a LUN managed by a VSS hardware provider, or because the destination disk is a cluster quorum disk.

AddToSnapshotSet(String)

The AddToSnapshotSet(String) method adds an original volume to the shadow copy set using the default provider.

Declaration

Guid AddToSnapshotSet(string volumeName)

Parameters

Type	Name	Description
String	volumeName	String containing the name of the volume to be shadow copied. The name must be in one of the following formats: The path of a volume mount point with a backslash (\) A drive letter with backslash (\), for example, D:\ A unique volume name of the form "\\?\Volume{GUID}\" (where GUID is the unique global identifier of the volume) with a backslash (\)

Returns

Type	Description
Guid	Identifier of the added shadow copy.

Remarks

The maximum number of shadow copies in a single shadow copy set is 64.

Exceptions

Type	Condition
UnauthorizedAccessException	Caller does not have sufficient backup privileges or is not an administrator.
ArgumentException	One of the parameters is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssMaximumNumberOfVolumesReachedException	The maximum number of volumes has been added to the shadow copy set. The specified volume was not added to the shadow copy set.
VssMaximumNumberOfSnapshotsReachedException	The volume has been added to the maximum number of shadow copy sets. The specified volume was not added to the shadow copy set.
VssObjectNotFoundException	volumeName does not correspond to an existing volume.
VssProviderVetoException	Expected provider error. The provider logged the error in the event log.
VssVolumeNotSupportedException	No VSS provider indicates that it supports the specified volume.
VssVolumeNotSupportedByProviderException	The volume is not supported by the specified provider.
VssUnexpectedProviderErrorException	The provider returned an unexpected error code.

AddToSnapshotSet(String, Guid)

The AddToSnapshotSet(String, Guid) method adds an original volume to the shadow copy set.

Declaration

Guid AddToSnapshotSet(string volumeName, Guid providerId)

Parameters

Type	Name	Description
String	volumeName	String containing the name of the volume to be shadow copied. The name must be in one of the following formats: The path of a volume mount point with a backslash (\) A drive letter with backslash (\), for example, D:\ A unique volume name of the form "\\?\Volume{GUID}\" (where GUID is the unique global identifier of the volume) with a backslash (\)
Guid	providerId	The provider to be used. Empty can be used, in which case the default provider will be used.

Returns

Type	Description
Guid	Identifier of the added shadow copy.

Remarks

The maximum number of shadow copies in a single shadow copy set is 64.

If providerId is Empty, the default provider is selected according to the following algorithm:

Exceptions

Type	Condition
UnauthorizedAccessException	Caller does not have sufficient backup privileges or is not an administrator.
ArgumentException	One of the parameters is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssMaximumNumberOfVolumesReachedException	The maximum number of volumes has been added to the shadow copy set. The specified volume was not added to the shadow copy set.
VssMaximumNumberOfSnapshotsReachedException	The volume has been added to the maximum number of shadow copy sets. The specified volume was not added to the shadow copy set.
VssObjectNotFoundException	volumeName does not correspond to an existing volume.
VssProviderNotRegisteredException	providerId does not correspond to a registered provider.
VssProviderVetoException	Expected provider error. The provider logged the error in the event log.
VssVolumeNotSupportedException	The value of the providerId parameter is Empty and no VSS provider indicates that it supports the specified volume.
VssVolumeNotSupportedByProviderException	The volume is not supported by the specified provider.
VssUnexpectedProviderErrorException	The provider returned an unexpected error code.

BackupComplete()

This method causes VSS to generate a BackupComplete event, which signals writers that the backup process has completed.

Declaration

void BackupComplete()

Exceptions

Type	Condition
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssUnexpectedWriterErrorException	An unexpected error occurred during communication with writers. The error code is logged in the error log file.

BackupCompleteAsync(CancellationToken)

This method asynchronously causes VSS to generate a BackupComplete event, which signals writers that the backup process has completed.

Declaration

Task BackupCompleteAsync(CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
CancellationToken	cancellationToken	The token to monitor for cancellation requests. The default value is None.

Returns

Type	Description
Task	A Task that represents the asynchronous operation.

Exceptions

Type	Condition
OperationCanceledException	Thrown if the operation was canceled by the cancellationToken
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssUnexpectedWriterErrorException	An unexpected error occurred during communication with writers. The error code is logged in the error log file.

BeginBackupComplete(AsyncCallback, Object)

This method asynchronously causes VSS to generate a BackupComplete event, which signals writers that the backup process has completed.

Declaration

[Obsolete("This API has been deprecated and will be removed in a future version of AlphaVSS.  Consider using BackupCompleteAsync instead.")]
IVssAsyncResult BeginBackupComplete(AsyncCallback userCallback, object state)

Parameters

Type	Name	Description
AsyncCallback	userCallback	An optional asynchronous callback, to be called when the read is complete.
Object	state	A user-provided object that distinguishes this particular asynchronous read request from other requests.

Returns

Type	Description
IVssAsyncResult	An IVssAsyncResult instance that represents this asynchronous operation.

Remarks

Pass the IVssAsyncResult value returned to the EndBackupComplete(IAsyncResult) method to release operating system resources used for this asynchronous operation. EndBackupComplete(IAsyncResult) must be called once for every call to BeginBackupComplete(AsyncCallback, Object). You can do this either by using the same code that called BeginBackupComplete or in a callback passed to BeginBackupComplete.

BeginBreakSnapshotSet(Guid, VssHardwareOptions, AsyncCallback, Object)

Begins an asynchronous operation to break a shadow copy set according to requester-specified options.

Declaration

[Obsolete("This API has been deprecated and will be removed in a future version of AlphaVSS.  Consider using BreakSnapshotSetAsync instead.")]
IVssAsyncResult BeginBreakSnapshotSet(Guid snapshotSetId, VssHardwareOptions breakFlags, AsyncCallback userCallback, object state)

Parameters

Type	Name	Description
Guid	snapshotSetId	A shadow copy set identifier.
VssHardwareOptions	breakFlags	A bitmask of VssHardwareOptions flags that specify how the shadow copy set is broken.
AsyncCallback	userCallback	An optional asynchronous callback, to be called when the read is complete.
Object	state	A user-provided object that distinguishes this particular asynchronous read request from other requests.

Returns

Type	Description
IVssAsyncResult	An IVssAsyncResult instance that represents this asynchronous operation.

Remarks

This method is similar to BreakSnapshotSet(Guid), except that is has an extra parameter to specify how the shadow copy set is broken.

Like BreakSnapshotSet(Guid), this method can be used only for shadow copies that were created by a hardware shadow copy provider.

After this method returns, the shadow copy volume is still a volume, but it is no longer a shadow copy. For more information, see Breaking Shadow Copies.

BeginDoSnapshotSet(AsyncCallback, Object)

Commits all shadow copies in this set simultaneously as an asynchronous operation.

Declaration

[Obsolete("This API has been deprecated and will be removed in a future version of AlphaVSS.  Consider using DoSnapshotSetAsync instead.")]
IVssAsyncResult BeginDoSnapshotSet(AsyncCallback userCallback, object state)

Parameters

Type	Name	Description
AsyncCallback	userCallback	An optional asynchronous callback, to be called when the read is complete.
Object	state	A user-provided object that distinguishes this particular asynchronous read request from other requests.

Returns

Type	Description
IVssAsyncResult	An IVssAsyncResult instance that represents this asynchronous operation.

Remarks

Pass the IVssAsyncResult value returned to the EndDoSnapshotSet(IAsyncResult) method to release operating system resources used for this asynchronous operation. EndDoSnapshotSet(IAsyncResult) must be called once for every call to BeginDoSnapshotSet(AsyncCallback, Object). You can do this either by using the same code that called BeginDoSnapshotSet or in a callback passed to BeginDoSnapshotSet.

BeginGatherWriterMetadata(AsyncCallback, Object)

The BeginGatherWriterMetadata(AsyncCallback, Object) method asynchronously prompts each writer to send the metadata they have collected. The method will generate an Identify event to communicate with writers.

Declaration

[Obsolete("This API has been deprecated and will be removed in a future version of AlphaVSS.  Consider using GatherWriterMetadataAsync instead.")]
IVssAsyncResult BeginGatherWriterMetadata(AsyncCallback userCallback, object state)

Parameters

Type	Name	Description
AsyncCallback	userCallback	An optional asynchronous callback, to be called when the read is complete.
Object	state	A user-provided object that distinguishes this particular asynchronous read request from other requests.

Returns

Type	Description
IVssAsyncResult	An IVssAsyncResult instance that represents this asynchronous operation.

Remarks

BeginGatherWriterMetadata(AsyncCallback, Object) should be called only once during the lifetime of a given IVssBackupComponents object.

Pass the IVssAsyncResult value returned to the EndGatherWriterMetadata(IAsyncResult) method to release operating system resources used for this asynchronous operation. EndGatherWriterMetadata(IAsyncResult) must be called once for every call to BeginGatherWriterMetadata(AsyncCallback, Object). You can do this either by using the same code that called BeginGatherWriterMetadata or in a callback passed to BeginGatherWriterMetadata.

BeginGatherWriterStatus(AsyncCallback, Object)

The BeginGatherWriterStatus(AsyncCallback, Object) method asynchronously prompts each writer to send a status message.

Declaration

[Obsolete("This API has been deprecated and will be removed in a future version of AlphaVSS.  Consider using GatherWriterStatusAsync instead.")]
IVssAsyncResult BeginGatherWriterStatus(AsyncCallback userCallback, object state)

Parameters

Type	Name	Description
AsyncCallback	userCallback	An optional asynchronous callback, to be called when the read is complete.
Object	state	A user-provided object that distinguishes this particular asynchronous read request from other requests.

Returns

Type	Description
IVssAsyncResult	An IVssAsyncResult instance that represents this asynchronous operation.

Remarks

The caller of this method should also call FreeWriterStatus() after receiving the status of each writer.

Pass the IVssAsyncResult value returned to the EndGatherWriterStatus(IAsyncResult) method to release operating system resources used for this asynchronous operation. EndGatherWriterStatus(IAsyncResult) must be called once for every call to BeginGatherWriterStatus(AsyncCallback, Object). You can do this either by using the same code that called BeginGatherWriterStatus or in a callback passed to BeginGatherWriterStatus.

BeginImportSnapshots(AsyncCallback, Object)

The BeginImportSnapshots(AsyncCallback, Object) method asynchronously imports shadow copies transported from a different machine.

Declaration

IVssAsyncResult BeginImportSnapshots(AsyncCallback userCallback, object state)

Parameters

Type	Name	Description
AsyncCallback	userCallback	An optional asynchronous callback, to be called when the read is complete.
Object	state	A user-provided object that distinguishes this particular asynchronous read request from other requests.

Returns

Type	Description
IVssAsyncResult	An IVssAsyncResult instance that represents this asynchronous operation.

Remarks

Only one shadow copy can be imported at a time.

The requester is responsible for serializing the import shadow copy operation.

For more information see the MSDN documentation on IIVssBackupComponents::ImportSnapshots Method

Requires Windows Server 2008, Windows Server 2003 SP1, Windows Server 2003, Enterprise Edition, or Windows Server 2003, Datacenter Edition.

Pass the IVssAsyncResult value returned to the EndImportSnapshots(IAsyncResult) method to release operating system resources used for this asynchronous operation. EndImportSnapshots(IAsyncResult) must be called once for every call to BeginImportSnapshots(AsyncCallback, Object). You can do this either by using the same code that called BeginImportSnapshots or in a callback passed to BeginImportSnapshots.

BeginPostRestore(AsyncCallback, Object)

The BeginPostRestore(AsyncCallback, Object) method will asynchronously cause VSS to generate a PostRestore event, signaling writers that the current restore operation has finished.

Declaration

[Obsolete("This API has been deprecated and will be removed in a future version of AlphaVSS.  Consider using PostRestoreAsync instead.")]
IVssAsyncResult BeginPostRestore(AsyncCallback userCallback, object state)

Parameters

Type	Name	Description
AsyncCallback	userCallback	An optional asynchronous callback, to be called when the read is complete.
Object	state	A user-provided object that distinguishes this particular asynchronous read request from other requests.

Returns

Type	Description
IVssAsyncResult	An IVssAsyncResult instance that represents this asynchronous operation.

Remarks

Pass the IVssAsyncResult value returned to the EndPostRestore(IAsyncResult) method to release operating system resources used for this asynchronous operation. EndPostRestore(IAsyncResult) must be called once for every call to BeginPostRestore(AsyncCallback, Object). You can do this either by using the same code that called BeginPostRestore or in a callback passed to BeginPostRestore.

BeginPrepareForBackup(AsyncCallback, Object)

The BeginPrepareForBackup(AsyncCallback, Object) method will asynchronously cause VSS to generate a PrepareForBackup event, signaling writers to prepare for an upcoming backup operation. This makes a requester's Backup Components Document available to writers.

Declaration

[Obsolete("This API has been deprecated and will be removed in a future version of AlphaVSS.  Consider using PrepareForBackupAsync instead.")]
IVssAsyncResult BeginPrepareForBackup(AsyncCallback userCallback, object state)

Parameters

Type	Name	Description
AsyncCallback	userCallback	An optional asynchronous callback, to be called when the read is complete.
Object	state	A user-provided object that distinguishes this particular asynchronous read request from other requests.

Returns

Type	Description
IVssAsyncResult	An IVssAsyncResult instance that represents this asynchronous operation.

Remarks

BeginPrepareForBackup(AsyncCallback, Object) generates a PrepareForBackup event, which is handled by each instance of each writer through the CVssWriter::OnPrepareBackup method.

Before PrepareForBackup can be called, SetBackupState(Boolean, Boolean, VssBackupType, Boolean) must be called.

Pass the IVssAsyncResult value returned to the EndPrepareForBackup(IAsyncResult) method to release operating system resources used for this asynchronous operation. EndPrepareForBackup(IAsyncResult) must be called once for every call to BeginPrepareForBackup(AsyncCallback, Object). You can do this either by using the same code that called BeginPrepareForBackup or in a callback passed to BeginPrepareForBackup.

BeginPreRestore(AsyncCallback, Object)

The BeginPreRestore(AsyncCallback, Object) method will asynchronously cause VSS to generate a PreRestore event, signaling writers to prepare for a coming restore operation.

Declaration

[Obsolete("This API has been deprecated and will be removed in a future version of AlphaVSS.  Consider using PreRestoreAsync instead.")]
IVssAsyncResult BeginPreRestore(AsyncCallback userCallback, object state)

Parameters

Type	Name	Description
AsyncCallback	userCallback	An optional asynchronous callback, to be called when the read is complete.
Object	state	A user-provided object that distinguishes this particular asynchronous read request from other requests.

Returns

Type	Description
IVssAsyncResult	An IVssAsyncResult instance that represents this asynchronous operation.

Remarks

Pass the IVssAsyncResult value returned to the EndPreRestore(IAsyncResult) method to release operating system resources used for this asynchronous operation. EndPreRestore(IAsyncResult) must be called once for every call to BeginPreRestore(AsyncCallback, Object). You can do this either by using the same code that called BeginPreRestore or in a callback passed to BeginPreRestore.

BeginQueryRevertStatus(String, AsyncCallback, Object)

The BeginQueryRevertStatus(String, AsyncCallback, Object) method begins an asynchronous operation to determine the status of the revert operation. The returned IVssAsyncResult can be used to determine the outcome of the operation.

Declaration

[Obsolete("This API has been deprecated and will be removed in a future version of AlphaVSS.  Consider using QueryRevertStatusAsync instead.")]
IVssAsyncResult BeginQueryRevertStatus(string volumeName, AsyncCallback userCallback, object state)

Parameters

Type	Name	Description
String	volumeName	Name of the volume. The name of the volume to be checked must be in one of the following formats: The path of a volume mount point with a backslash (\) A drive letter with backslash (\), for example, D:\ A unique volume name of the form \\?\Volume{GUID}\ (where GUID is the unique global identifier of the volume) with a backslash (\)
AsyncCallback	userCallback	An optional asynchronous callback, to be called when the operation is complete.
Object	state	A user-provided object that distinguishes this particular asynchronous read request from other requests.

Returns

Type	Description
IVssAsyncResult	An IVssAsyncResult instance that represents this asynchronous operation.

Remarks

The revert operation will continue even if the computer is rebooted, and cannot be canceled or undone, except by restoring a backup created using another method.

note

Windows XP, Windows Server 2003 and Windows Vista: This method requires Windows Server 2008 or Windows Server 2003 SP1

BeginRecoverSet(VssRecoveryOptions, AsyncCallback, Object)

Begins an asynchronous operation that initiates a LUN resynchronization operation. This method is supported only on Windows server operating systems.

Declaration

[Obsolete("This API has been deprecated and will be removed in a future version of AlphaVSS.  Consider using RecoverSetAsync instead.")]
IVssAsyncResult BeginRecoverSet(VssRecoveryOptions options, AsyncCallback userCallback, object state)

Parameters

Type	Name	Description
VssRecoveryOptions	options	VssRecoveryOptions flags that specify how the resynchronization is to be performed.
AsyncCallback	userCallback	An optional asynchronous callback, to be called when the read is complete.
Object	state	A user-provided object that distinguishes this particular asynchronous read request from other requests.

Returns

Type	Description
IVssAsyncResult	An IVssAsyncResult instance that represents this asynchronous operation.

Remarks

Pass the IVssAsyncResult value returned to the EndRecoverSet(IAsyncResult) method to release operating system resources used for this asynchronous operation. EndRecoverSet(IAsyncResult) must be called once for every call to BeginRecoverSet(VssRecoveryOptions, AsyncCallback, Object). You can do this either by using the same code that called BeginRecoverSet or in a callback passed to BeginRecoverSet.

note

Windows XP, Windows 2003, Windows Vista, Windows 2008, Windows 7: This method requires Windows Server 2008 R2.

BreakSnapshotSet(Guid)

The BreakSnapshotSet method causes the existence of a shadow copy set to be "forgotten" by VSS.

Declaration

void BreakSnapshotSet(Guid snapshotSetId)

Parameters

Type	Name	Description
Guid	snapshotSetId	Shadow copy set identifier.

Remarks

BreakSnapshotSet can be used only for shadow copies created by a hardware shadow copy provider. This method makes these shadow copies regular volumes.

Exceptions

Type	Condition
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
ArgumentException	One of the parameters is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssProviderVetoException	The shadow copy was created by a software provider and cannot be broken.
VssObjectNotFoundException	The specified shadow copy does not exist.

BreakSnapshotSet(Guid, VssHardwareOptions)

Breaks a shadow copy set according to requester-specified options.

Declaration

void BreakSnapshotSet(Guid snapshotSetId, VssHardwareOptions breakFlags)

Parameters

Type	Name	Description
Guid	snapshotSetId	A shadow copy set identifier.
VssHardwareOptions	breakFlags	A bitmask of VssHardwareOptions flags that specify how the shadow copy set is broken.

Remarks

This method is similar to BreakSnapshotSet(Guid), except that is has an extra parameter to specify how the shadow copy set is broken.

Like BreakSnapshotSet(Guid), this method can be used only for shadow copies that were created by a hardware shadow copy provider.

After this method returns, the shadow copy volume is still a volume, but it is no longer a shadow copy. For more information, see Breaking Shadow Copies.

BreakSnapshotSetAsync(Guid, VssHardwareOptions, CancellationToken)

Begins an asynchronous operation to break a shadow copy set according to requester-specified options.

Declaration

Task BreakSnapshotSetAsync(Guid snapshotSetId, VssHardwareOptions breakFlags, CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
Guid	snapshotSetId	A shadow copy set identifier.
VssHardwareOptions	breakFlags	A bitmask of VssHardwareOptions flags that specify how the shadow copy set is broken.
CancellationToken	cancellationToken	The token to monitor for cancellation requests. The default value is None.

Returns

Type	Description
Task	A Task that represents the asynchronous operation.

Remarks

This method is similar to BreakSnapshotSet(Guid), except that is has an extra parameter to specify how the shadow copy set is broken.

Like BreakSnapshotSet(Guid), this method can be used only for shadow copies that were created by a hardware shadow copy provider.

After this method returns, the shadow copy volume is still a volume, but it is no longer a shadow copy. For more information, see Breaking Shadow Copies.

Exceptions

Type	Condition
OperationCanceledException	Thrown if the operation was canceled by the cancellationToken

DeleteSnapshot(Guid, Boolean)

The DeleteSnapshot method deletes a shadow copy..

Declaration

void DeleteSnapshot(Guid snapshotId, bool forceDelete)

Parameters

Type	Name	Description
Guid	snapshotId	Identifier of the shadow copy to be deleted.
Boolean	forceDelete	If the value of this parameter is true, the provider will do everything possible to delete the shadow copy. If it is false, no additional effort will be made.

Remarks

The requester is responsible for serializing the delete shadow copy operation.

During a backup, shadow copies are automatically released as soon as the IVssBackupComponents instance is disposed. In this case, it is not necessary to explicitly delete shadow copies.

Exceptions

Type	Condition
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
ArgumentException	One of the parameters is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssObjectNotFoundException	The specified shadow copy does not exist.
VssProviderVetoException	Expected provider error. The provider logged the error in the event log.
VssUnexpectedProviderErrorException	Unexpected provider error. The error code is logged in the error log.

DeleteSnapshotSet(Guid, Boolean)

The DeleteSnapshotSet method deletes a shadow copy set including any shadow copies in that set.

Declaration

int DeleteSnapshotSet(Guid snapshotSetId, bool forceDelete)

Parameters

Type	Name	Description
Guid	snapshotSetId	Identifier of the shadow copy set to be deleted.
Boolean	forceDelete	If the value of this parameter is true, the provider will do everything possible to delete the shadow copies in a shadow copy set. If it is false, no additional effort will be made.

Returns

Type	Description
Int32	The total number of snapshots that were deleted

Remarks

Multiple shadow copies in a shadow copy set are deleted sequentially. If an error occurs during one of these individual deletions, DeleteSnapshotSet will throw an exception immediately; no attempt will be made to delete any remaining shadow copies. The identifier of the undeleted shadow copy can be found in the instance of VssDeleteSnapshotsFailedException thrown.

The requester is responsible for serializing the delete shadow copy operation.

During a backup, shadow copies are automatically released as soon as the IVssBackupComponents instance is disposed. In this case, it is not necessary to explicitly delete shadow copies.

Exceptions

Type	Condition
VssDeleteSnapshotsFailedException	The deletion failed. This is the only exception actually thrown by this method. It wraps one of the other exceptions listed in this section as its inner exception.
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
ArgumentException	One of the parameters is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssObjectNotFoundException	The specified shadow copy does not exist.
VssProviderVetoException	Expected provider error. The provider logged the error in the event log.
VssUnexpectedProviderErrorException	Unexpected provider error. The error code is logged in the error log.

DisableWriterClasses(Guid[])

This method prevents a specific class of writers from receiving any events.

Declaration

void DisableWriterClasses(params Guid[] writerClassIds)

Parameters

Type	Name	Description
Guid[]	writerClassIds	An array containing one or more writer class identifiers.

Exceptions

Type	Condition
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
ArgumentException	One of the parameters is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.

DisableWriterInstances(Guid[])

This method disables a specified writer instance or instances.

Declaration

void DisableWriterInstances(params Guid[] writerInstanceIds)

Parameters

Type	Name	Description
Guid[]	writerInstanceIds	An array containing one or more writer instance identifiers.

Exceptions

Type	Condition
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
ArgumentException	One of the parameters is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.

DoSnapshotSet()

Commits all shadow copies in this set simultaneously.

Declaration

void DoSnapshotSet()

Exceptions

Type	Condition
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object has not been initialized or the prerequisite calls for a given shadow copy context have not been made prior to calling DoSnapshotSet.
VssInsufficientStorageException	The system or provider has insufficient storage space. If possible delete any old or unnecessary persistent shadow copies and try again.
VssFlushWritesTimeoutException	The system was unable to flush I/O writes. This can be a transient problem. It is recommended to wait ten minutes and try again, up to three times.
VssHoldWritesTimeoutException	The system was unable to hold I/O writes. This can be a transient problem. It is recommended to wait ten minutes and try again, up to three times.
VssProviderVetoException	The provider was unable to perform the request at this time. This can be a transient problem. It is recommended to wait ten minutes and try again, up to three times.
VssRebootRequiredException	The provider encountered an error that requires the user to restart the computer. Windows Server 2003 and Windows XP: This value is not supported until Windows Vista.
VssTransactionFreezeTimeoutException	The system was unable to freeze the Distributed Transaction Coordinator (DTC) or the Kernel Transaction Manager (KTM). Windows Server 2003 and Windows XP: This value is not supported until Windows Vista.
VssTransactionThawTimeoutException	The system was unable to freeze the Distributed Transaction Coordinator (DTC) or the Kernel Transaction Manager (KTM). Windows Server 2003 and Windows XP: This value is not supported until Windows Vista.
VssUnexpectedProviderErrorException	The provider returned an unexpected error code. This can be a transient problem. It is recommended to wait ten minutes and try again, up to three times.

DoSnapshotSetAsync(CancellationToken)

Commits all shadow copies in this set simultaneously as an asynchronous operation.

Declaration

Task DoSnapshotSetAsync(CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
CancellationToken	cancellationToken	The token to monitor for cancellation requests. The default value is None.

Returns

Type	Description
Task	A Task that represents the asynchronous operation.

Exceptions

Type	Condition
OperationCanceledException	Thrown if the operation was canceled by the cancellationToken
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object has not been initialized or the prerequisite calls for a given shadow copy context have not been made prior to calling DoSnapshotSet.
VssInsufficientStorageException	The system or provider has insufficient storage space. If possible delete any old or unnecessary persistent shadow copies and try again.
VssFlushWritesTimeoutException	The system was unable to flush I/O writes. This can be a transient problem. It is recommended to wait ten minutes and try again, up to three times.
VssHoldWritesTimeoutException	The system was unable to hold I/O writes. This can be a transient problem. It is recommended to wait ten minutes and try again, up to three times.
VssProviderVetoException	The provider was unable to perform the request at this time. This can be a transient problem. It is recommended to wait ten minutes and try again, up to three times.
VssRebootRequiredException	The provider encountered an error that requires the user to restart the computer.
VssTransactionFreezeTimeoutException	The system was unable to freeze the Distributed Transaction Coordinator (DTC) or the Kernel Transaction Manager (KTM).
VssTransactionThawTimeoutException	The system was unable to freeze the Distributed Transaction Coordinator (DTC) or the Kernel Transaction Manager (KTM).
VssUnexpectedProviderErrorException	The provider returned an unexpected error code. This can be a transient problem. It is recommended to wait ten minutes and try again, up to three times.

EnableWriterClasses(Guid[])

The EnableWriterClasses method enables the specified writers to receive all events.

Declaration

void EnableWriterClasses(params Guid[] writerClassIds)

Parameters

Type	Name	Description
Guid[]	writerClassIds	An array containing one or more writer class identifiers.

Remarks

Once this method is called, only enabled writer classes are subsequently called.

DisableWriterClasses(Guid[]) must be called prior to GatherWriterMetadata(). To obtain information about the writers currently running on the system, it may be necessary to call GatherWriterMetadata() from another instance of the IVssBackupComponents class.

After GatherWriterMetadata() is called, these calls have no effect.

Exceptions

Type	Condition
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.

EndBackupComplete(IAsyncResult)

Waits for a pending asynchronous operation to complete.

Declaration

[Obsolete("This API has been deprecated and will be removed in a future version of AlphaVSS.  Consider using BackupCompleteAsync instead.")]
void EndBackupComplete(IAsyncResult asyncResult)

Parameters

Type	Name	Description
IAsyncResult	asyncResult	The reference to the pending asynchronous request to finish.

Remarks

EndBackupComplete can be called once on every IVssAsyncResult from BeginBackupComplete(AsyncCallback, Object).

Exceptions

Type	Condition
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssUnexpectedWriterErrorException	An unexpected error occurred during communication with writers. The error code is logged in the error log file.

EndBreakSnapshotSet(IAsyncResult)

Waits for an asynchronous operation to complete.

Declaration

[Obsolete("This API has been deprecated and will be removed in a future version of AlphaVSS.  Consider using BreakSnapshotSetAsync instead.")]
void EndBreakSnapshotSet(IAsyncResult asyncResult)

Parameters

Type	Name	Description
IAsyncResult	asyncResult	The reference to the pending asynchronous request to finish.

Remarks

EndBreakSnapshotSet can be called once on every IVssAsyncResult from BeginBreakSnapshotSet(Guid, VssHardwareOptions, AsyncCallback, Object).

EndDoSnapshotSet(IAsyncResult)

Waits for a pending asynchronous operation to complete.

Declaration

[Obsolete("This API has been deprecated and will be removed in a future version of AlphaVSS.  Consider using DoSnapshotSetAsync instead.")]
void EndDoSnapshotSet(IAsyncResult asyncResult)

Parameters

Type	Name	Description
IAsyncResult	asyncResult	The reference to the pending asynchronous request to finish.

Remarks

EndDoSnapshotSet can be called once on every IVssAsyncResult from BeginDoSnapshotSet(AsyncCallback, Object).

Exceptions

Type	Condition
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object has not been initialized or the prerequisite calls for a given shadow copy context have not been made prior to calling DoSnapshotSet.
VssInsufficientStorageException	The system or provider has insufficient storage space. If possible delete any old or unnecessary persistent shadow copies and try again.
VssFlushWritesTimeoutException	The system was unable to flush I/O writes. This can be a transient problem. It is recommended to wait ten minutes and try again, up to three times.
VssHoldWritesTimeoutException	The system was unable to hold I/O writes. This can be a transient problem. It is recommended to wait ten minutes and try again, up to three times.
VssProviderVetoException	The provider was unable to perform the request at this time. This can be a transient problem. It is recommended to wait ten minutes and try again, up to three times.
VssRebootRequiredException	The provider encountered an error that requires the user to restart the computer. Windows Server 2003 and Windows XP: This value is not supported until Windows Vista.
VssTransactionFreezeTimeoutException	The system was unable to freeze the Distributed Transaction Coordinator (DTC) or the Kernel Transaction Manager (KTM). Windows Server 2003 and Windows XP: This value is not supported until Windows Vista.
VssTransactionThawTimeoutException	The system was unable to freeze the Distributed Transaction Coordinator (DTC) or the Kernel Transaction Manager (KTM). Windows Server 2003 and Windows XP: This value is not supported until Windows Vista.
VssUnexpectedProviderErrorException	The provider returned an unexpected error code. This can be a transient problem. It is recommended to wait ten minutes and try again, up to three times.

EndGatherWriterMetadata(IAsyncResult)

Waits for a pending asynchronous operation to complete.

Declaration

[Obsolete("This API has been deprecated and will be removed in a future version of AlphaVSS.  Consider using GatherWriterMetadataAsync instead.")]
void EndGatherWriterMetadata(IAsyncResult asyncResult)

Parameters

Type	Name	Description
IAsyncResult	asyncResult	The reference to the pending asynchronous request to finish.

Remarks

EndGatherWriterMetadata can be called once on every IVssAsyncResult from BeginGatherWriterMetadata(AsyncCallback, Object).

Exceptions

Type	Condition
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssWriterInfrastructureException	The writer infrastructure is not operating properly. Check that the Event Service and VSS have been started, and check for errors associated with those services in the error log.

EndGatherWriterStatus(IAsyncResult)

Waits for a pending asynchronous operation to complete.

Declaration

[Obsolete("This API has been deprecated and will be removed in a future version of AlphaVSS.  Consider using GatherWriterStatusAsync instead.")]
void EndGatherWriterStatus(IAsyncResult asyncResult)

Parameters

Type	Name	Description
IAsyncResult	asyncResult	The reference to the pending asynchronous request to finish.

Remarks

EndGatherWriterStatus can be called once on every IVssAsyncResult from BeginGatherWriterStatus(AsyncCallback, Object).

Exceptions

Type	Condition
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssWriterInfrastructureException	The writer infrastructure is not operating properly. Check that the Event Service and VSS have been started, and check for errors associated with those services in the error log.

EndImportSnapshots(IAsyncResult)

Waits for a pending asynchronous operation to complete.

Declaration

void EndImportSnapshots(IAsyncResult asyncResult)

Parameters

Type	Name	Description
IAsyncResult	asyncResult	The reference to the pending asynchronous request to finish.

Remarks

EndImportSnapshots can be called once on every IVssAsyncResult from BeginImportSnapshots(AsyncCallback, Object).

Exceptions

Type	Condition
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.

EndPostRestore(IAsyncResult)

Waits for a pending asynchronous operation to complete.

Declaration

[Obsolete("This API has been deprecated and will be removed in a future version of AlphaVSS.  Consider using PostRestoreAsync instead.")]
void EndPostRestore(IAsyncResult asyncResult)

Parameters

Type	Name	Description
IAsyncResult	asyncResult	The reference to the pending asynchronous request to finish.

Remarks

EndGatherWriterStatus can be called once on every IVssAsyncResult from BeginPostRestore(AsyncCallback, Object).

Exceptions

Type	Condition
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The specified volume was not found or was not available.
VssProviderVetoException	Expected provider error. The provider logged the error in the event log.

EndPrepareForBackup(IAsyncResult)

Waits for a pending asynchronous operation to complete.

Declaration

[Obsolete("This API has been deprecated and will be removed in a future version of AlphaVSS.  Consider using PrepareForBackupAsync instead.")]
void EndPrepareForBackup(IAsyncResult asyncResult)

Parameters

Type	Name	Description
IAsyncResult	asyncResult	The reference to the pending asynchronous request to finish.

Remarks

EndGatherWriterStatus can be called once on every IVssAsyncResult from BeginPrepareForBackup(AsyncCallback, Object).

Exceptions

Type	Condition
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.

EndPreRestore(IAsyncResult)

Waits for a pending asynchronous operation to complete.

Declaration

[Obsolete("This API has been deprecated and will be removed in a future version of AlphaVSS.  Consider using PreRestoreAsync instead.")]
void EndPreRestore(IAsyncResult asyncResult)

Parameters

Type	Name	Description
IAsyncResult	asyncResult	The reference to the pending asynchronous request to finish.

Remarks

EndGatherWriterStatus can be called once on every IVssAsyncResult from BeginPreRestore(AsyncCallback, Object).

Exceptions

Type	Condition
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.

EndQueryRevertStatus(IAsyncResult)

Waits for a pending asynchronous operation to complete.

Declaration

[Obsolete("This API has been deprecated and will be removed in a future version of AlphaVSS.  Consider using QueryRevertStatusAsync instead.")]
void EndQueryRevertStatus(IAsyncResult asyncResult)

Parameters

Type	Name	Description
IAsyncResult	asyncResult	The reference to the pending asynchronous request to finish.

Remarks

EndQueryRevertStatus can be called once on every IVssAsyncResult from BeginQueryRevertStatus(String, AsyncCallback, Object).

Exceptions

Type	Condition
ArgumentException	One of the parameter values is not valid.
UnauthorizedAccessException	The calling process has insufficient privileges.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The specified parameter is not a valid volume.
VssVolumeNotSupportedException	Revert is not supported on this volume.
NotImplementedException	The provider for the volume does not support revert operations.
NotSupportedException	This operation is not supported on the current operating system.

EndRecoverSet(IAsyncResult)

Waits for a pending asynchronous operation to complete.

Declaration

[Obsolete("This API has been deprecated and will be removed in a future version of AlphaVSS.  Consider using RecoverSetAsync instead.")]
void EndRecoverSet(IAsyncResult asyncResult)

Parameters

Type	Name	Description
IAsyncResult	asyncResult	The reference to the pending asynchronous request to finish.

Remarks

EndRecoverSet can be called once on every IVssAsyncResult from BeginRecoverSet(VssRecoveryOptions, AsyncCallback, Object).

Exceptions

Type	Condition
ArgumentException	One of the parameter values is not valid.
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
NotImplementedException	The provider for the volume does not support LUN resynchronization.
VssBadStateException	Possible reasons for this return value include: There is no hardware provider that supports the operation. The requester did not successfully add any volumes to the recovery set. The method was called in WinPE or in Safe mode. he caller did not call the InitializeForRestore(String) method before calling this method.
VssLegacyProviderException	This version of the hardware provider does not support this operation.
VssProviderVetoException	An unexpected provider error occurred. If this error code is returned, the error must be described in an entry in the application event log, giving the user information on how to resolve the problem.
VssUnselectedVolumeException	The resynchronization destination contained a volume that was not explicitly included.
VssCannotRevertDiskIdException	The MBR signature or GPT ID for one or more disks could not be set to the intended value. Check the Application event log for more information.

ExposeSnapshot(Guid, String, VssVolumeSnapshotAttributes, String)

The ExposeSnapshot method exposes a shadow copy either by mounting it as a device on a drive letter or mount point, or as a file share.

Declaration

string ExposeSnapshot(Guid snapshotId, string pathFromRoot, VssVolumeSnapshotAttributes attributes, string expose)

Parameters

Type	Name	Description
Guid	snapshotId	Shadow copy identifier.
String	pathFromRoot	The path to the portion of the volume made available when exposing a shadow copy as a file share. The value of this parameter must be NULL when exposing a shadow copy locally; that is, by mounting to a drive letter or a mount point. The path cannot contain environment variables (for example, %MyEnv%) or wildcard characters. There is no requirement that the path end with a backslash ("\"). It is up to applications that retrieve this information to check.
VssVolumeSnapshotAttributes	attributes	Attributes of the exposed shadow copy indicating whether it is exposed locally or remotely. The value must be either the ExposedLocally or the ExposedRemotely value of VssVolumeSnapshotAttributes.
String	expose	When a shadow copy is exposed as a file share, the value of this parameter is the share name. If a shadow copy is exposed by mounting it as a device, the parameter value is a drive letter followed by a colon, for example, "X:" or a mount point path (for example, "X:\a\b"). If the value of this parameter is null, then VSS determines the share name or drive letter if the attributes parameter is ExposedRemotely.

Returns

Type	Description
String	The exposed name of the shadow copy. This is either a share name, a drive letter followed by a colon, or a mount point.

Remarks

When exposing a persistent shadow copy, it remains exposed through subsequent boots.

When exposing a shadow copy of a volume, the shadow copy may be treated either as a mountable device or as a file system available for file sharing.

When it is exposed as a device, as with other mountable devices, the shadow copy of a volume is exposed at its mount point starting with its root.

When exposed as a file share, subsets (indicated by pathFromRoot) of the volume can be shared.

Exceptions

Type	Condition
ArgumentException	One of the parameter values is not valid.
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The specified shadow copy does not exist.
VssProviderVetoException	Expected provider error. The provider logged the error in the event log.
VssUnexpectedProviderErrorException	Unexpected provider error. The error code is logged in the error log.

FreeWriterMetadata()

The FreeWriterMetadata method frees system resources allocated when GatherWriterMetadata() was called.

Declaration

void FreeWriterMetadata()

Remarks

This method should never be called prior to the completion of GatherWriterMetadata(). The result of calling the method prior to completion of the metadata gather is undefined.

Once writer metadata has been freed, it cannot be recovered by the current instance of the IVssBackupComponents class. It will be necessary to create a new instance of IVssBackupComponents, and call the GatherWriterMetadata() method again.

Exceptions

Type	Condition
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.

FreeWriterStatus()

The FreeWriterStatus method frees system resources allocated during the call to GatherWriterStatus().

Declaration

void FreeWriterStatus()

Exceptions

Type	Condition
OutOfMemoryException	The caller is out of memory or other system resources.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.

GatherWriterMetadata()

The GatherWriterMetadata() method prompts each writer to send the metadata they have collected. The method will generate an Identify event to communicate with writers.

Declaration

void GatherWriterMetadata()

Remarks

GatherWriterMetadata() should be called only once during the lifetime of a given IVssBackupComponents object.

Exceptions

Type	Condition
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssWriterInfrastructureException	The writer infrastructure is not operating properly. Check that the Event Service and VSS have been started, and check for errors associated with those services in the error log.

GatherWriterMetadataAsync(CancellationToken)

The GatherWriterMetadataAsync(CancellationToken) method asynchronously prompts each writer to send the metadata they have collected. The method will generate an Identify event to communicate with writers.

Declaration

Task GatherWriterMetadataAsync(CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
CancellationToken	cancellationToken	The token to monitor for cancellation requests. The default value is None.

Returns

Type	Description
Task	A Task that represents the asynchronous operation.

Remarks

GatherWriterMetadataAsync(CancellationToken) should be called only once during the lifetime of a given IVssBackupComponents object.

Exceptions

Type	Condition
OperationCanceledException	Thrown if the operation was canceled by the cancellationToken
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssWriterInfrastructureException	The writer infrastructure is not operating properly. Check that the Event Service and VSS have been started, and check for errors associated with those services in the error log.

GatherWriterStatus()

The GatherWriterStatus() method prompts each writer to send a status message.

Declaration

void GatherWriterStatus()

Remarks

The caller of this method should also call FreeWriterStatus() after receiving the status of each writer.

Exceptions

Type	Condition
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssWriterInfrastructureException	The writer infrastructure is not operating properly. Check that the Event Service and VSS have been started, and check for errors associated with those services in the error log.

GatherWriterStatusAsync(CancellationToken)

The GatherWriterStatusAsync(CancellationToken) method asynchronously prompts each writer to send a status message.

Declaration

Task GatherWriterStatusAsync(CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task	A Task that represents the asynchronous operation.

Remarks

The caller of this method should also call FreeWriterStatus() after receiving the status of each writer.

The token to monitor for cancellation requests. The default value is None.

Exceptions

Type	Condition
OperationCanceledException	Thrown if the operation was canceled by the cancellationToken
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssWriterInfrastructureException	The writer infrastructure is not operating properly. Check that the Event Service and VSS have been started, and check for errors associated with those services in the error log.

GetRootAndLogicalPrefixPaths(String, Boolean)

Normalizes a local volume path or UNC share path so that it can be passed to the AddToSnapshotSet(String) method.

Declaration

VssRootAndLogicalPrefixPaths GetRootAndLogicalPrefixPaths(string filePath, bool normalizeFQDNforRootPath)

Parameters

Type	Name	Description
String	filePath	The path to be normalized.
Boolean	normalizeFQDNforRootPath	If filePath is a UNC share path, the server name portion can be A host name A fully qualified domain name An IP address This parameter specifies whether host name format or fully qualified domain name format should be used in the server name portion of the normalized root path that is returned in the RootPath property of the returned instance. If this parameter is false, simple host name format will be used. If this parameter is true, fully qualified domain name will be used. In a deployment where a host name could exist in multiple domain suffixes, this parameter should be true.

Returns

Type	Description
VssRootAndLogicalPrefixPaths	The root and logical prefix paths.

GetSessionId()

Gets the requester's session identifier.

Declaration

Guid GetSessionId()

Returns

Type	Description
Guid	The requester's session identifier.

Remarks

The session identifier is an opaque value that uniquely identifies a backup or restore session. It is used to distinguish the current session among multiple parallel backup or restore sessions.

As a best practice, writers and requesters should include the session ID in all diagnostics messages used for event logging and tracing.

note

Windows XP, Windows 2003, Windows Vista, Windows 2008: This method requires Windows 7 or Windows Server 2008 R2.

Exceptions

Type	Condition
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.

GetSnapshotProperties(Guid)

The GetSnapshotProperties(Guid) method gets the properties of the specified shadow copy.

Declaration

VssSnapshotProperties GetSnapshotProperties(Guid snapshotId)

Parameters

Type	Name	Description
Guid	snapshotId	The identifier of the shadow copy of a volume as returned by AddToSnapshotSet(String, Guid).

Returns

Type	Description
VssSnapshotProperties	A VssSnapshotProperties instance containing the shadow copy properties.

Exceptions

Type	Condition
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
ArgumentException	One of the parameter values is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The specified shadow copy does not exist.
VssProviderVetoException	Expected provider error. The provider logged the error in the event log.
VssUnexpectedProviderErrorException	Unexpected provider error. The error code is logged in the error log.

ImportSnapshots()

The ImportSnapshots method imports shadow copies transported from a different machine.

Declaration

void ImportSnapshots()

Remarks

Only one shadow copy can be imported at a time.

The requester is responsible for serializing the import shadow copy operation.

For more information see the MSDN documentation on IIVssBackupComponents::ImportSnapshots Method

Requires Windows Server 2008, Windows Server 2003 SP1, Windows Server 2003, Enterprise Edition, or Windows Server 2003, Datacenter Edition.

Exceptions

Type	Condition
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.

ImportSnapshotsAsync(CancellationToken)

The ImportSnapshotsAsync(CancellationToken) method asynchronously imports shadow copies transported from a different machine.

Declaration

Task ImportSnapshotsAsync(CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
CancellationToken	cancellationToken	The token to monitor for cancellation requests. The default value is None.

Returns

Type	Description
Task	A Task that represents the asynchronous operation.

Remarks

Only one shadow copy can be imported at a time.

The requester is responsible for serializing the import shadow copy operation.

For more information see the MSDN documentation on IIVssBackupComponents::ImportSnapshots Method

Exceptions

Type	Condition
OperationCanceledException	Thrown if the operation was canceled by the cancellationToken
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.

InitializeForBackup(String)

The InitializeForBackup(String) method initializes the backup components metadata in preparation for backup.

Declaration

void InitializeForBackup(string xml)

Parameters

Type	Name	Description
String	xml	During imports of transported shadow copies, this parameter must be the original document generated when creating the saved shadow copy and saved using SaveAsXml(). This parameter may be null

Remarks

The XML document supplied to this method initializes the IVssBackupComponents object with metadata previously stored by a call to SaveAsXml(). Users should not tamper with this metadata document.

Exceptions

Type	Condition
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssInvalidXmlDocumentException	The XML document is not valid. Check the event log for details.

InitializeForRestore(String)

The InitializeForRestore(String) method initializes the IIVssBackupComponents interface in preparation for a restore operation.

Declaration

void InitializeForRestore(string xml)

Parameters

Type	Name	Description
String	xml	XML string containing the Backup Components Document generated by a backup operation and saved by SaveAsXml().

Remarks

The XML document supplied to this method initializes the IVssBackupComponents object with metadata previously stored by a call to SaveAsXml(). Users should not tamper with this metadata document.

Exceptions

Type	Condition
ArgumentNullException	xml is null
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssInvalidXmlDocumentException	The load operation of the specified XML document failed.

IsVolumeSupported(String)

The IsVolumeSupported method determines whether any provider supports shadow copies on the specified volume.

Declaration

bool IsVolumeSupported(string volumeName)

Parameters

Type	Name	Description
String	volumeName	Name of the volume. The name of the volume to be checked must be in one of the following formats: The path of a volume mount point with a backslash (\) A drive letter with backslash (\), for example, D:\ A unique volume name of the form \\?\Volume{GUID}\ (where GUID is the unique global identifier of the volume) with a backslash (\)

Returns

Type	Description
Boolean	true if shadow copies are supported on the specified volume. If the value is false, shadow copies are not supported on the specified volume.

Remarks

IsVolumeSupported(String, Guid) will return true if it is possible to create shadow copies on the given volume, even if the current configuration does not allow the creation of shadow copies on that volume at the present time.

For example, if the maximum number of shadow copies has been reached on a given volume (and therefore no more shadow copies can be created on that volume), the method will still indicate that the volume can be shadow copied.

Exceptions

Type	Condition
ArgumentNullException	volumeName is null
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The specified volume was not found or was not available.

IsVolumeSupported(String, Guid)

The IsVolumeSupported method determines whether the specified provider supports shadow copies on the specified volume.

Declaration

bool IsVolumeSupported(string volumeName, Guid providerId)

Parameters

Type	Name	Description
String	volumeName	Name of the volume. The name of the volume to be checked must be in one of the following formats: The path of a volume mount point with a backslash (\) A drive letter with backslash (\), for example, D:\ A unique volume name of the form \\?\Volume{GUID}\ (where GUID is the unique global identifier of the volume) with a backslash (\)
Guid	providerId	Provider identifier. If the value is Empty, IsVolumeSupported(String, Guid) checks whether any provider supports the volume.

Returns

Type	Description
Boolean	true if shadow copies are supported on the specified volume. If the value is false, shadow copies are not supported on the specified volume.

Remarks

IsVolumeSupported(String, Guid) will return true if it is possible to create shadow copies on the given volume, even if the current configuration does not allow the creation of shadow copies on that volume at the present time.

For example, if the maximum number of shadow copies has been reached on a given volume (and therefore no more shadow copies can be created on that volume), the method will still indicate that the volume can be shadow copied.

Exceptions

Type	Condition
ArgumentNullException	volumeName is null
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The specified volume was not found or was not available.

PostRestore()

The PostRestore() method will cause VSS to generate a PostRestore event, signaling writers that the current restore operation has finished.

Declaration

void PostRestore()

Exceptions

Type	Condition
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The specified volume was not found or was not available.
VssProviderVetoException	Expected provider error. The provider logged the error in the event log.

PostRestoreAsync(CancellationToken)

The PostRestoreAsync(CancellationToken) method will asynchronously cause VSS to generate a PostRestore event, signaling writers that the current restore operation has finished.

Declaration

Task PostRestoreAsync(CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
CancellationToken	cancellationToken	The token to monitor for cancellation requests. The default value is None.

Returns

Type	Description
Task	A Task that represents the asynchronous operation.

Exceptions

Type	Condition
OperationCanceledException	Thrown if the operation was canceled by the cancellationToken
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The specified volume was not found or was not available.
VssProviderVetoException	Expected provider error. The provider logged the error in the event log.

PrepareForBackup()

The PrepareForBackup() method will cause VSS to generate a PrepareForBackup event, signaling writers to prepare for an upcoming backup operation. This makes a requester's Backup Components Document available to writers.

Declaration

void PrepareForBackup()

Remarks

PrepareForBackup() generates a PrepareForBackup event, which is handled by each instance of each writer through the CVssWriter::OnPrepareBackup method.

Before PrepareForBackup can be called, SetBackupState(Boolean, Boolean, VssBackupType, Boolean) must be called.

Exceptions

Type	Condition
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.

PrepareForBackupAsync(CancellationToken)

The PrepareForBackupAsync(CancellationToken) method will asynchronously cause VSS to generate a PrepareForBackup event, signaling writers to prepare for an upcoming backup operation. This makes a requester's Backup Components Document available to writers.

Declaration

Task PrepareForBackupAsync(CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
CancellationToken	cancellationToken	The token to monitor for cancellation requests. The default value is None.

Returns

Type	Description
Task	A Task that represents the asynchronous operation.

Remarks

PrepareForBackupAsync(CancellationToken) generates a PrepareForBackup event, which is handled by each instance of each writer through the CVssWriter::OnPrepareBackup method.

Before PrepareForBackup can be called, SetBackupState(Boolean, Boolean, VssBackupType, Boolean) must be called.

Exceptions

Type	Condition
OperationCanceledException	Thrown if the operation was canceled by the cancellationToken
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.

PreRestore()

The PreRestore() method will cause VSS to generate a PreRestore event, signaling writers to prepare for a coming restore operation.

Declaration

void PreRestore()

Exceptions

Type	Condition
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.

PreRestoreAsync(CancellationToken)

The PreRestoreAsync(CancellationToken) method will asynchronously cause VSS to generate a PreRestore event, signaling writers to prepare for a coming restore operation.

Declaration

Task PreRestoreAsync(CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
CancellationToken	cancellationToken	The token to monitor for cancellation requests. The default value is None.

Returns

Type	Description
Task	A Task that represents the asynchronous operation.

Exceptions

Type	Condition
OperationCanceledException	Thrown if the operation was canceled by the cancellationToken
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.

QueryProviders()

The QueryProviders() method queries providers on the system. The method can be called only during backup operations.

Declaration

IEnumerable<VssProviderProperties> QueryProviders()

Returns

Type	Description
IEnumerable<VssProviderProperties>	A list of VssProviderProperties objects representing the requested information.

Remarks

The method may be called only during backup operations and must be preceded by calls to InitializeForBackup(String) and SetContext(VssSnapshotContext).

Exceptions

Type	Condition
ArgumentException	One of the parameter values is not valid.
UnauthorizedAccessException	The caller is not an administrator or a backup operator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The queried object is not found.
VssProviderVetoException	Expected provider error. The provider logged the error in the event log.
VssUnexpectedProviderErrorException	Unexpected provider error. The error code is logged in the error log.

QueryRevertStatusAsync(String, CancellationToken)

The QueryRevertStatusAsync(String, CancellationToken) method begins an asynchronous operation to determine the status of the revert operation. The returned IVssAsyncResult can be used to determine the outcome of the operation.

Declaration

Task QueryRevertStatusAsync(string volumeName, CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
String	volumeName	Name of the volume. The name of the volume to be checked must be in one of the following formats: The path of a volume mount point with a backslash (\) A drive letter with backslash (\), for example, D:\ A unique volume name of the form \\?\Volume{GUID}\ (where GUID is the unique global identifier of the volume) with a backslash (\)
CancellationToken	cancellationToken	The token to monitor for cancellation requests. The default value is None.

Returns

Type	Description
Task	A Task that represents the asynchronous operation.

Remarks

The revert operation will continue even if the computer is rebooted, and cannot be canceled or undone, except by restoring a backup created using another method.

Exceptions

Type	Condition
OperationCanceledException	Thrown if the operation was canceled by the cancellationToken
ArgumentException	One of the parameter values is not valid.
UnauthorizedAccessException	The calling process has insufficient privileges.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The specified parameter is not a valid volume.
VssVolumeNotSupportedException	Revert is not supported on this volume.
NotImplementedException	The provider for the volume does not support revert operations.
NotSupportedException	This operation is not supported on the current operating system.

QuerySnapshots()

The QuerySnapshots() method queries the completed shadow copies in the system that reside in the current context. The method can be called only during backup operations.

Declaration

IEnumerable<VssSnapshotProperties> QuerySnapshots()

Returns

Type	Description
IEnumerable<VssSnapshotProperties>	A list of VssSnapshotProperties objects representing the requested information.

Remarks

Because QuerySnapshots() returns only information on completed shadow copies, the only shadow copy state it can disclose is Created.

The method may be called only during backup operations and must be preceded by calls to InitializeForBackup(String) and SetContext(VssSnapshotContext).

The method will return only information about shadow copies with the current context (set by SetContext(VssSnapshotContext)). For instance, if the VssSnapshotContext context is set to Backup, QuerySnapshots() will not return information on a shadow copy created with a context of FileShareBackup.

Exceptions

Type	Condition
ArgumentException	One of the parameter values is not valid.
UnauthorizedAccessException	The caller is not an administrator or a backup operator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The queried object is not found.
VssProviderVetoException	Expected provider error. The provider logged the error in the event log.
VssUnexpectedProviderErrorException	Unexpected provider error. The error code is logged in the error log.

RecoverSet(VssRecoveryOptions)

Initiates a LUN resynchronization operation. This method is supported only on Windows server operating systems.

Declaration

void RecoverSet(VssRecoveryOptions options)

Parameters

Type	Name	Description
VssRecoveryOptions	options	VssRecoveryOptions flags that specify how the resynchronization is to be performed.

Remarks

note

Windows XP, Windows 2003, Windows Vista, Windows 2008, Windows 7: This method requires Windows Server 2008 R2.

Exceptions

Type	Condition
ArgumentException	One of the parameter values is not valid.
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
NotImplementedException	The provider for the volume does not support LUN resynchronization.
VssBadStateException	Possible reasons for this return value include: There is no hardware provider that supports the operation. The requester did not successfully add any volumes to the recovery set. The method was called in WinPE or in Safe mode. he caller did not call the InitializeForRestore(String) method before calling this method.
VssLegacyProviderException	This version of the hardware provider does not support this operation.
VssProviderVetoException	An unexpected provider error occurred. If this error code is returned, the error must be described in an entry in the application event log, giving the user information on how to resolve the problem.
VssUnselectedVolumeException	The resynchronization destination contained a volume that was not explicitly included.
VssCannotRevertDiskIdException	The MBR signature or GPT ID for one or more disks could not be set to the intended value. Check the Application event log for more information.

RecoverSetAsync(VssRecoveryOptions, CancellationToken)

Begins an asynchronous operation that initiates a LUN resynchronization operation. This method is supported only on Windows server operating systems.

Declaration

Task RecoverSetAsync(VssRecoveryOptions options, CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
VssRecoveryOptions	options	VssRecoveryOptions flags that specify how the resynchronization is to be performed.
CancellationToken	cancellationToken	The token to monitor for cancellation requests. The default value is None.

Returns

Type	Description
Task	A Task that represents the asynchronous operation.

Remarks

Pass the IVssAsyncResult value returned to the EndRecoverSet(IAsyncResult) method to release operating system resources used for this asynchronous operation. EndRecoverSet(IAsyncResult) must be called once for every call to BeginRecoverSet(VssRecoveryOptions, AsyncCallback, Object). You can do this either by using the same code that called BeginRecoverSet or in a callback passed to BeginRecoverSet.

note

Windows Vista, Windows 2008, Windows 7: This method requires Windows Server 2008 R2.

Exceptions

Type	Condition
OperationCanceledException	Thrown if the operation was canceled by the cancellationToken
ArgumentException	One of the parameter values is not valid.
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
NotImplementedException	The provider for the volume does not support LUN resynchronization.
VssBadStateException	Possible reasons for this return value include: There is no hardware provider that supports the operation. The requester did not successfully add any volumes to the recovery set. The method was called in WinPE or in Safe mode. he caller did not call the InitializeForRestore(String) method before calling this method.
VssLegacyProviderException	This version of the hardware provider does not support this operation.
VssProviderVetoException	An unexpected provider error occurred. If this error code is returned, the error must be described in an entry in the application event log, giving the user information on how to resolve the problem.
VssUnselectedVolumeException	The resynchronization destination contained a volume that was not explicitly included.
VssCannotRevertDiskIdException	The MBR signature or GPT ID for one or more disks could not be set to the intended value. Check the Application event log for more information.

RevertToSnapshot(Guid, Boolean)

The RevertToSnapshot(Guid, Boolean) method reverts a volume to a previous shadow copy. Only shadow copies created with persistent contexts (AppRollback, ClientAccessible, ClientAccessibleWriters or NasRollback) are supported.

Declaration

void RevertToSnapshot(Guid snapshotId, bool forceDismount)

Parameters

Type	Name	Description
Guid	snapshotId	The identifier of the shadow copy to revert
Boolean	forceDismount	If this parameter is true, the volume will be dismounted and reverted even if the volume is in use.

Remarks

This operation cannot be canceled, or undone once completed. If the computer is rebooted during the revert operation, the revert process will continue when the system is restarted.

note

Windows XP, Windows Server 2003 and Windows Vista: This method requires Windows Server 2008 or Windows Server 2003 SP1

Exceptions

Type	Condition
ArgumentException	One of the parameter values is not valid.
UnauthorizedAccessException	The calling process has insufficient privileges.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The snapshotId parameter is not a valid shadow copy.
VssProviderNotRegisteredException	The provider was not found.
VssRevertInProgressException	The volume already has a revert in process.
VssUnsupportedContextException	Revert is only supported for persistent shadow copies.
VssVolumeInUseException	The forceDismount parameter was false, and the volume could not be locked.
VssVolumeNotSupportedException	Revert is not supported on this volume.
NotImplementedException	The provider for the volume does not support revert operations.
NotSupportedException	This operation is not supported on the current operating system.

SaveAsXml()

The SaveAsXml method saves the Backup Components Document containing a requester's state information to a specified string. This XML document, which contains the Backup Components Document, should always be securely saved as part of a backup operation.

Declaration

string SaveAsXml()

Returns

Type	Description
String	The Backup Components Document containing a requester's state information.

Remarks

For a typical backup operation, SaveAsXml should not be called until after both writers and the requester are finished modifying the Backup Components Document.

Writers can continue to modify the Backup Components Document until their successful return from handling the PostSnapshot event (CVssWriter::OnPostSnapshot), or equivalently upon the completion of DoSnapshotSet().

Requesters will need to continue to modify the Backup Components Document as the backup progresses. In particular, a requester will store a component-by-component record of the success or failure of the backup through calls to the SetBackupSucceeded(Guid, Guid, VssComponentType, String, String, Boolean) method.

Once the requester has finished modifying the Backup Components Document, the requester should use SaveAsXml() to save a copy of the document to the backup media.

A Backup Components Document can be saved at earlier points in the life cycle of a backup operation, for instance, to support the generation of transportable shadow copies to be handled on remote machines.

However, SaveAsXml() should never be called prior to PrepareForBackup(), because the Backup Components Document will not have been filled by the requester and the writers.

Exceptions

Type	Condition
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.

SetAdditionalRestores(Guid, VssComponentType, String, String, Boolean)

The SetAdditionalRestores method is used by a requester during incremental or differential restore operations to indicate to writers that a given component will require additional restore operations to completely retrieve it.

Declaration

void SetAdditionalRestores(Guid writerId, VssComponentType componentType, string logicalPath, string componentName, bool additionalResources)

Parameters

Type	Name	Description
Guid	writerId	Writer identifier.
VssComponentType	componentType	Type of the component.
String	logicalPath	The logical path of the component to be added. For more information, see Logical Pathing of Components. The value of the string containing the logical path used here should be the same as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String). The logical path can be null. There are no restrictions on the characters that can appear in a non-null logical path.
String	componentName	The name of the component. The value of the string should not be null, and should contain the same component as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String).
Boolean	additionalResources	If the value of this parameter is true, additional restores of the component will follow this restore. If the value is false, additional restores of the component will not follow this restore.

Remarks

The information provided by the SetAdditionalRestores(Guid, VssComponentType, String, String, Boolean) method is typically used by writers that support an explicit recovery mechanism as part of their PostRestore event handler (CVssWriter::OnPostRestore)�for instance, the Exchange Server, and database applications such as SQL Server. For these applications, it is often not possible to perform additional differential, incremental, or log restores after such a recovery is performed.

Therefore, if SetAdditionalRestores(Guid, VssComponentType, String, String, Boolean) for a component is set to true, this means that such a writer should not execute its explicit recovery mechanism and should expect that additional differential, incremental, or log restores will be done.

When SetAdditionalRestores(Guid, VssComponentType, String, String, Boolean) on a component is set to false, then after the component is restored, the application can complete its recovery operation and be brought back online.

This method must be called before PreRestore().

Exceptions

Type	Condition
ArgumentNullException	One of the arguments that cannot be null was null
ArgumentException	One of the parameter values is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The backup component does not exist.
VssInvalidXmlDocumentException	The XML document is not valid. Check the event log for details.

SetAuthoritativeRestore(Guid, VssComponentType, String, String, Boolean)

Marks the restore of a component as authoritative for a replicated data store.

Declaration

void SetAuthoritativeRestore(Guid writerId, VssComponentType componentType, string logicalPath, string componentName, bool isAuthorative)

Parameters

Type	Name	Description
Guid	writerId	The globally unique identifier (GUID) of the writer class.
VssComponentType	componentType	Type of the component.
String	logicalPath	The logical path of the component to be added. For more information, see Logical Pathing of Components. The value of the string containing the logical path used here should be the same as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String). The logical path can be null. There are no restrictions on the characters that can appear in a non-null logical path.
String	componentName	The name of the component. The value of the string should not be null, and should contain the same component as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String).
Boolean	isAuthorative	true to indicate that the restore of the component is authoritative; otherwise, false.

Remarks

note

Windows XP and Windows 2003: This method requires Windows Vista or Windows Server 2008.

Exceptions

Type	Condition
ArgumentNullException	One of the arguments that cannot be null was null
ArgumentException	One of the parameter values is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	This method was not called during a restore operation.
VssObjectNotFoundException	The specified component was not found.

SetBackupOptions(Guid, VssComponentType, String, String, String)

Sets a string of private, or writer-dependent, backup parameters for a component.

Declaration

void SetBackupOptions(Guid writerId, VssComponentType componentType, string logicalPath, string componentName, string backupOptions)

Parameters

Type	Name	Description
Guid	writerId	Writer identifier.
VssComponentType	componentType	Type of the component.
String	logicalPath	The logical path of the component to be added. For more information, see Logical Pathing of Components. The value of the string containing the logical path used here should be the same as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String). The logical path can be null. There are no restrictions on the characters that can appear in a non-null logical path.
String	componentName	The name of the component. The value of the string should not be null, and should contain the same component as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String).
String	backupOptions	String containing the backup parameters to be set.

Remarks

The exact syntax and content of the backup options set by the wszBackupOptions parameter of the SetBackupOptions(Guid, VssComponentType, String, String, String) method will depend on the specific writer being contacted.

This method must be called before PrepareForBackup().

Exceptions

Type	Condition
ArgumentNullException	One of the arguments that cannot be null was null
ArgumentException	One of the parameter values is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The backup component does not exist.
VssInvalidXmlDocumentException	The XML document is not valid. Check the event log for details.

SetBackupState(Boolean, Boolean, VssBackupType, Boolean)

Defines an overall configuration for a backup operation.

Declaration

void SetBackupState(bool selectComponents, bool backupBootableSystemState, VssBackupType backupType, bool partialFileSupport)

Parameters

Type	Name	Description
Boolean	selectComponents	Indicates whether a backup or restore operation will be in component mode. Operation in component mode supports selectively backing up designated individual components (which can allow their exclusion), or only supports backing up all files and components on a volume. The Boolean is true if the operation will be conducted in component mode and false if not.
Boolean	backupBootableSystemState	Indicates whether a bootable system state backup is being performed.
VssBackupType	backupType	A VssBackupType enumeration value indicating the type of backup to be performed.
Boolean	partialFileSupport	If the value of this parameter is true, partial file support is enabled. The default value for this argument is false.

Remarks

Applications must call SetBackupState(Boolean, Boolean, VssBackupType, Boolean) prior to calling PrepareForBackup().

Exceptions

Type	Condition
ArgumentNullException	One of the arguments that cannot be null was null
ArgumentException	One of the parameter values is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssInvalidXmlDocumentException	The XML document is not valid. Check the event log for details.

SetBackupSucceeded(Guid, Guid, VssComponentType, String, String, Boolean)

Indicates whether the backup of the specified component of a specific writer was successful.

Declaration

void SetBackupSucceeded(Guid instanceId, Guid writerId, VssComponentType componentType, string logicalPath, string componentName, bool succeeded)

Parameters

Type	Name	Description
Guid	instanceId	Globally unique identifier of the writer instance.
Guid	writerId	Globally unique identifier of the writer class.
VssComponentType	componentType	Type of the component.
String	logicalPath	The logical path of the component to be added. For more information, see Logical Pathing of Components. The value of the string containing the logical path used here should be the same as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String). The logical path can be null. There are no restrictions on the characters that can appear in a non-null logical path.
String	componentName	The name of the component. The value of the string should not be null, and should contain the same component as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String).
Boolean	succeeded	The value of this parameter is true if the component was successfully backed up, and false if it was not.

Remarks

When working in component mode (when SetBackupState(Boolean, Boolean, VssBackupType, Boolean) is called with its select components argument set to true), writers the state of each components backup using BackupSucceeded.

Therefore, a well-behaved backup application (requester) must call SetBackupSucceeded(Guid, Guid, VssComponentType, String, String, Boolean) after each component has been processed and prior to calling BackupComplete().

Exceptions

Type	Condition
ArgumentNullException	One of the arguments that cannot be null was null
ArgumentException	One of the parameter values is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The backup component does not exist.
VssInvalidXmlDocumentException	The XML document is not valid. Check the event log for details.

SetContext(VssSnapshotContext)

Sets the context for subsequent shadow copy-related operations.

Declaration

void SetContext(VssSnapshotContext context)

Parameters

Type	Name	Description
VssSnapshotContext	context	The context to be set. The context must be one of the supported values of VssSnapshotContext or a supported bit mask (or bitwise OR) of VssVolumeSnapshotAttributes with a valid VssSnapshotContext.

Remarks

The default context for VSS shadow copies is Backup.

Windows XP: The only supported context is the default context, Backup. Therefore, calling this method under Windows XP throws a NotImplementedException.

SetContext(VssSnapshotContext) can be called only once, and it must be called prior to calling most VSS functions.

For details on how the context set by this method affects how a shadow copy is created and managed, see Implementation Details for Creating Shadow Copies.

For a complete discussion of the permitted shadow copy contexts, see VssSnapshotContext and VssVolumeSnapshotAttributes.

Exceptions

Type	Condition
ArgumentException	One of the parameter values is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.

SetContext(VssVolumeSnapshotAttributes)

Sets the context for subsequent shadow copy-related operations.

Declaration

void SetContext(VssVolumeSnapshotAttributes context)

Parameters

Type	Name	Description
VssVolumeSnapshotAttributes	context	The context to be set. The context must be one of the supported values of VssSnapshotContext or a supported bit mask (or bitwise OR) of VssVolumeSnapshotAttributes with a valid VssSnapshotContext.

Remarks

The default context for VSS shadow copies is Backup.

Windows XP: The only supported context is the default context, Backup. Therefore, calling this method under Windows XP throws a NotImplementedException.

This method be called only once, and it must be called prior to calling most VSS functions.

For details on how the context set by this method affects how a shadow copy is created and managed, see Implementation Details for Creating Shadow Copies.

For a complete discussion of the permitted shadow copy contexts, see VssSnapshotContext and VssVolumeSnapshotAttributes.

Exceptions

Type	Condition
ArgumentException	One of the parameter values is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.

SetFileRestoreStatus(Guid, VssComponentType, String, String, VssFileRestoreStatus)

Indicates whether some, all, or no files were successfully restored.

Declaration

void SetFileRestoreStatus(Guid writerId, VssComponentType componentType, string logicalPath, string componentName, VssFileRestoreStatus status)

Parameters

Type	Name	Description
Guid	writerId	Globally unique identifier of the writer class.
VssComponentType	componentType	Type of the component.
String	logicalPath	The logical path of the component. For more information, see Logical Pathing of Components. The value of the string containing the logical path used here should be the same as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String). The logical path can be null. There are no restrictions on the characters that can appear in a non-null logical path.
String	componentName	The name of the component. The value of the string should not be null, and should contain the same component as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String).
VssFileRestoreStatus	status	If all of the files were restored, the value of this parameter is All. If some of the files were restored, the value of this parameter is Failed. If none of the files were restored, the value of this parameter is None.

Remarks

This method should be called between calls to PreRestore() and PostRestore().

Exceptions

Type	Condition
ArgumentNullException	One of the arguments that cannot be null was null
ArgumentException	One of the parameter values is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The backup component does not exist.
VssInvalidXmlDocumentException	The XML document is not valid. Check the event log for details.

SetPreviousBackupStamp(Guid, VssComponentType, String, String, String)

Sets the backup stamp of an earlier backup operation, upon which a differential or incremental backup operation will be based.

The method can be called only during a backup operation.

Declaration

void SetPreviousBackupStamp(Guid writerId, VssComponentType componentType, string logicalPath, string componentName, string previousBackupStamp)

Parameters

Type	Name	Description
Guid	writerId	Writer identifier.
VssComponentType	componentType	Type of the component.
String	logicalPath	The logical path of the component. For more information, see Logical Pathing of Components. The value of the string containing the logical path used here should be the same as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String). The logical path can be null. There are no restrictions on the characters that can appear in a non-null logical path.
String	componentName	The name of the component. The value of the string should not be null, and should contain the same component as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String).
String	previousBackupStamp	The backup stamp to be set.

Remarks

This method should be called before PrepareForBackup().

Only requesters can call this method.

The backup stamp set by SetPreviousBackupStamp(Guid, VssComponentType, String, String, String) applies to all files in the component and any nonselectable Subcomponents it has.

Requesters merely store the backup stamps in the Backup Components Document. They cannot make direct use of the backup stamps, do not know their format, and do not know how to generate them.

Therefore, the value set with SetPreviousBackupStamp(Guid, VssComponentType, String, String, String) should either be retrieved from the stored Backup Components Document of an earlier backup operation (using BackupStamp for the correct component), or from information stored by the requester into its own internal records.

A writer will then obtain this value (using IVssComponent::GetPreviousBackupStamp) and using it will be able to mark the appropriate files for participation in an incremental or differential backup.

Exceptions

Type	Condition
ArgumentNullException	One of the arguments that cannot be null was null
ArgumentException	One of the parameter values is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The backup component does not exist.
VssInvalidXmlDocumentException	The XML document is not valid. Check the event log for details.

SetRangesFilePath(Guid, VssComponentType, String, String, Int32, String)

This method is used when a partial file operation requires a ranges file, and that file has been restored to a location other than its original one.

Declaration

void SetRangesFilePath(Guid writerId, VssComponentType componentType, string logicalPath, string componentName, int partialFileIndex, string rangesFile)

Parameters

Type	Name	Description
Guid	writerId	Globally unique identifier (GUID) of the writer class containing the files involved in the partial file operation
VssComponentType	componentType	Type of the component.
String	logicalPath	The logical path of the component containing the files that are participating in the partial file operation. For more information, see Logical Pathing of Components. The value of the string containing the logical path used here should be the same as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String). The logical path can be null. There are no restrictions on the characters that can appear in a non-null logical path.
String	componentName	The name of the component containing the files that are participating in the partial file operation. The value of the string should not be null, and should contain the same component as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String).
Int32	partialFileIndex	Index number of the partial file. The value of this parameter is an integer between 0 and n-1, where n is the total number of partial files associated with a given component. The value of n is the number of items in PartialFiles.
String	rangesFile	The fully qualified path of a ranges file.

Remarks

Calling SetRangesFilePath(Guid, VssComponentType, String, String, Int32, String) is not necessary if ranges files are restored in place.

note

Windows XP and Windows Vista: This method requires Windows Server 2008 or Windows Server 2003

Exceptions

Type	Condition
ArgumentNullException	One of the arguments that cannot be null was null
ArgumentException	One of the parameter values is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The backup component does not exist.
VssInvalidXmlDocumentException	The XML document is not valid. Check the event log for details.
NotSupportedException	The operation is not supported by the current operating system.

SetRestoreName(Guid, VssComponentType, String, String, String)

Assigns a new logical name to a component that is being restored.

Declaration

void SetRestoreName(Guid writerId, VssComponentType componentType, string logicalPath, string componentName, string restoreName)

Parameters

Type	Name	Description
Guid	writerId	The globally unique identifier (GUID) of the writer class.
VssComponentType	componentType	The type of the component.
String	logicalPath	A string containing the logical path of the component. For more information, see Logical Pathing of Components. The value of the string containing the logical path used here should be the same as the string that was used when the component was added. The logical path can be null. There are no restrictions on the characters that can appear in a logical path.
String	componentName	The name of the component. The string cannot be null and should contain the same component name as was the component name that was used when the component was added to the backup set using the AddComponent(Guid, Guid, VssComponentType, String, String) method.
String	restoreName	String containing the restore name to be set for the component.

Remarks

note

Windows XP and Windows 2003: This method requires Windows Vista or Windows Server 2008.

Exceptions

Type	Condition
ArgumentNullException	One of the arguments that cannot be null was null
ArgumentException	One of the parameter values is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	This method was not called during a restore operation.
VssObjectNotFoundException	The specified component was not found.

SetRestoreOptions(Guid, VssComponentType, String, String, String)

Sets a string of private, or writer-dependent, restore parameters for a writer component.

Declaration

void SetRestoreOptions(Guid writerId, VssComponentType componentType, string logicalPath, string componentName, string restoreOptions)

Parameters

Type	Name	Description
Guid	writerId	Writer identifier.
VssComponentType	componentType	Type of the component.
String	logicalPath	The logical path of the component. For more information, see Logical Pathing of Components. The value of the string containing the logical path used here should be the same as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String). The logical path can be null. There are no restrictions on the characters that can appear in a non-null logical path.
String	componentName	The name of the component. The value of the string should not be null, and should contain the same component as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String).
String	restoreOptions	The private string of restore parameters. For more information see Setting VSS Restore Options.

Remarks

This method must be called before PreRestore().

The exact syntax and content of the restore options set by the restoreOptions parameter of the SetRestoreOptions(Guid, VssComponentType, String, String, String) method will depend on the specific writer being contacted.

Exceptions

Type	Condition
ArgumentNullException	One of the arguments that cannot be null was null
ArgumentException	One of the parameter values is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The backup component does not exist.
VssInvalidXmlDocumentException	The XML document is not valid. Check the event log for details.

SetRestoreState(VssRestoreType)

Defines an overall configuration for a restore operation.

Declaration

void SetRestoreState(VssRestoreType restoreType)

Parameters

Type	Name	Description
VssRestoreType	restoreType	The type of restore to be performed.

Remarks

Typically, most restore operations will not need to override the default restore type Undefined.

If applications need to call SetRestoreState(VssRestoreType), it should be called prior to calling PreRestore().

note

Windows XP: This method requires Windows Vista, Windows Server 2008 or Windows Server 2003

Exceptions

Type	Condition
ArgumentException	One of the parameter values is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The backup component does not exist.
VssInvalidXmlDocumentException	The XML document is not valid. Check the event log for details.

SetRollForward(Guid, VssComponentType, String, String, VssRollForwardType, String)

Sets the roll-forward operation type for a component and specifies the restore point for a partial roll-forward operation.

Declaration

void SetRollForward(Guid writerId, VssComponentType componentType, string logicalPath, string componentName, VssRollForwardType rollType, string rollForwardPoint)

Parameters

Type	Name	Description
Guid	writerId	The globally unique identifier (GUID) of the writer class.
VssComponentType	componentType	Type of the component.
String	logicalPath	The logical path of the component. For more information, see Logical Pathing of Components. The value of the string containing the logical path used here should be the same as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String). The logical path can be null. There are no restrictions on the characters that can appear in a non-null logical path.
String	componentName	The name of the component. The value of the string should not be null, and should contain the same component as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String).
VssRollForwardType	rollType	A VssRollForwardType enumeration value indicating the type of roll-forward operation to be performed.
String	rollForwardPoint	A null-terminated wide character string specifying the roll-forward restore point. The format of this string is defined by the writer, and can be a timestamp, a log sequence number (LSN), or any marker defined by the writer.

Remarks

note

Windows XP and Windows 2003: This method requires Windows Vista or Windows Server 2008.

Exceptions

Type	Condition
ArgumentNullException	One of the arguments that cannot be null was null
ArgumentException	One of the parameter values is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	This method was not called during a restore operation.
VssObjectNotFoundException	The backup component does not exist.

SetSelectedForRestore(Guid, VssComponentType, String, String, Boolean)

Indicates whether the specified selectable component is selected for restoration.

Declaration

void SetSelectedForRestore(Guid writerId, VssComponentType componentType, string logicalPath, string componentName, bool selectedForRestore)

Parameters

Type	Name	Description
Guid	writerId	Writer identifier.
VssComponentType	componentType	Type of the component.
String	logicalPath	The logical path of the component. For more information, see Logical Pathing of Components. The value of the string containing the logical path used here should be the same as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String). The logical path can be null. There are no restrictions on the characters that can appear in a non-null logical path.
String	componentName	The name of the component. The value of the string should not be null, and should contain the same component as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String).
Boolean	selectedForRestore	If the value of this parameter is true, the selected component has been selected for restoration. If the value is false, the selected component has not been selected for restoration.

Remarks

SetSelectedForRestore has meaning only for restores taking place in component mode.

SetSelectedForRestore(Guid, VssComponentType, String, String, Boolean) can only be called for components that were explicitly added to the backup document at backup time using AddComponent(Guid, Guid, VssComponentType, String, String). Restoring a component that was implicitly selected for backup as part of a component set must be done by calling SetSelectedForRestore(Guid, VssComponentType, String, String, Boolean) on the closest ancestor component that was added to the document. If only this component's data is to be restored, that should be accomplished through AddRestoreSubcomponent(Guid, VssComponentType, String, String, String, String); this can only be done if the component is selectable for restore.

This method must be called before PreRestore().

Exceptions

Type	Condition
ArgumentNullException	One of the arguments that cannot be null was null
ArgumentException	One of the parameter values is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The backup component does not exist.
VssInvalidXmlDocumentException	The XML document is not valid. Check the event log for details.

SetSelectedForRestore(Guid, VssComponentType, String, String, Boolean, Guid)

Indicates whether the specified selectable component is selected for restoration to a specified writer instance.

Declaration

void SetSelectedForRestore(Guid writerId, VssComponentType componentType, string logicalPath, string componentName, bool selectedForRestore, Guid instanceId)

Parameters

Type	Name	Description
Guid	writerId	Globally unique identifier (GUID) of the writer class.
VssComponentType	componentType	Type of the component.
String	logicalPath	The logical path of the component. For more information, see Logical Pathing of Components. The value of the string containing the logical path used here should be the same as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String). The logical path can be null. There are no restrictions on the characters that can appear in a non-null logical path.
String	componentName	The name of the component. The value of the string should not be null, and should contain the same component as was used when the component was added to the backup set using AddComponent(Guid, Guid, VssComponentType, String, String).
Boolean	selectedForRestore	If the value of this parameter is true, the selected component has been selected for restoration. If the value is false, the selected component has not been selected for restoration.
Guid	instanceId	GUID of the writer instance.

Remarks

SetSelectedForRestore, which moves a component to a different writer instance, can be called only for a writer that supports running multiple writer instances with the same class ID and supports a requester moving a component to a different writer instance at restore time. To determine whether a writer provides this support, call the BackupSchema method.

SetSelectedForRestore has meaning only for restores taking place in component mode.

SetSelectedForRestore can be called only for components that were explicitly added to the backup document at backup time using AddComponent. Restoring a component that was implicitly selected for backup as part of a component set must be done by calling SetSelectedForRestore on the closest ancestor component that was added to the document. If only this component's data is to be restored, that should be accomplished through the AddRestoreSubcomponent(Guid, VssComponentType, String, String, String, String) method; this can be done only if the component is selectable for restore (see Working with Selectability and Logical Paths).

This method must be called before the PreRestore() method.

The distinction between the instanceId and writerId parameters is necessary because it is possible that multiple instances of the same writer are running on the computer.

If the value of the instanceId parameter is Empty, this is equivalent to calling the SetSelectedForRestore(Guid, VssComponentType, String, String, Boolean).

The instanceId parameter is used to specify that the component is to be restored to a different writer instance. If the value of the instanceId parameter is not Empty, it must match the instance ID of a writer instance with the same writer class ID specified in in the writerId parameter.

A writer's class identifier, instance identifier, and instance name can be found in the properties of IVssExamineWriterMetadata.

note

Windows XP and Windows 2003: This method is not supported until Windows 2003 SP1.

Exceptions

Type	Condition
ArgumentNullException	One of the arguments that cannot be null was null
ArgumentException	One of the parameter values is not valid.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The backup component does not exist.
VssInvalidXmlDocumentException	The XML document is not valid. Check the event log for details.

StartSnapshotSet()

Creates a new, empty shadow copy set.

Declaration

Guid StartSnapshotSet()

Returns

Type	Description
Guid	Shadow copy set identifier.

Remarks

This method must be called before PrepareForBackup() during backup operations.

Exceptions

Type	Condition
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssSnapshotSetInProgressException	The creation of a shadow copy is in progress, and only one shadow copy creation operation can be in progress at one time. Either wait to try again or return with a failure error code.

UnexposeSnapshot(Guid)

Unexposes a shadow copy either by deleting the file share or by removing the drive letter or mount point.

Declaration

void UnexposeSnapshot(Guid snapshotId)

Parameters

Type	Name	Description
Guid	snapshotId	The shadow copy identifier. The value of this identifier should be the same as the value that was used when the shadow copy was exposed.

Remarks

note

Windows XP and Windows 2003: This method requires Windows Vista or Windows Server 2008.

Exceptions

Type	Condition
ArgumentException	One of the parameter values is not valid.
UnauthorizedAccessException	The caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	Out of memory or other system resources.
SystemException	Unexpected VSS system error. The error code is logged in the event log.
VssBadStateException	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VssObjectNotFoundException	The specified shadow copy does not exist or is not exposed.
VssProviderVetoException	Expected provider error. The provider logged the error in the event log.
VssUnexpectedProviderErrorException	Unexpected provider error. The error code is logged in the error log.

See Also

IVssFactory