DocumentSetVersionCollection Class
Represents a collection of DocumentSetVersion snapshot objects.
Inheritance Hierarchy
System.Object
Microsoft.Office.DocumentManagement.DocumentSets.DocumentSetVersionCollection
Namespace: Microsoft.Office.DocumentManagement.DocumentSets
Assembly: Microsoft.Office.DocumentManagement (in Microsoft.Office.DocumentManagement.dll)
Syntax
'Declaration
<PermissionSetAttribute(SecurityAction.Demand, Name := "FullTrust")> _
<PermissionSetAttribute(SecurityAction.InheritanceDemand, Name := "FullTrust")> _
Public Class DocumentSetVersionCollection _
Implements IEnumerable(Of DocumentSetVersion), IEnumerable
'Usage
Dim instance As DocumentSetVersionCollection
[PermissionSetAttribute(SecurityAction.Demand, Name = "FullTrust")]
[PermissionSetAttribute(SecurityAction.InheritanceDemand, Name = "FullTrust")]
public class DocumentSetVersionCollection : IEnumerable<DocumentSetVersion>,
IEnumerable
Remarks
Captures, restores, and enumerates snapshots of document sets. Snapshots are sorted in descending order from latest to oldest. For performance considerations, this class is implemented with delay loading, so the contents are not loaded until one of its public members is accessed. Using this class requires versioning to be enabled on the parent list of the DocumentSet object.
To access any of the properties of this class, users must have SPBasePermissions.ViewListItems permissions. Get an object of the DocumentSetVersionCollection class only from DocumentSetVersionCollection property.
Examples
using System;
using System.Collections;
using System.Collections.Generic;
using Microsoft.SharePoint;
using Microsoft.Office.DocumentManagement.DocumentSets;
// Required project references:
// * Microsoft.Sharepoint
// * Microsoft.Office.DocumentManagement
// Assumptions:
// - SPSite exists on site specified by siteUrl
// - SPDocumentLibrary exists on the above site with title specified by listName
// - Aformentioned library has document set content type enable with the name specified by docSetContentTypeName
// - There is at least one document set in the specified library
// - There are at least a few documents in the aformentioned document set
// - User running the code has contributor permisisons, specifically SPBasePermissions.EditListItems permissions.
namespace Microsoft.SDK.Office.DocumentManagement.DocumentSet.Samples
{
/// <summary>
/// This class provides code samples that demonstrate use of
/// DocumentSetVersion and DocumentSetVersionCollection classes.
/// </summary>
/// <remarks>
/// In Main function, uncomment:
/// - DocumentSetVersionSample to run the sample for DocumentSetVersion
/// - DocumentSetVersionCollectionSample to run the sample for DocumentSetVersionCollectionSample
/// </remarks>
class Program
{
const string siteUrl = "https://localhost";
const string listName = "Documents";
const string docSetContentTypeName = "Document Set";
static void Main(string[] args)
{
DocumentSetVersionSample();
DocumentSetVersionCollectionSample();
}
/// <summary>
/// The following code sample covers retrieving an instance
/// of DocumentSetVersion as well as common operations:
/// - accessing common properties
/// - displaying its metadata
/// - displaying its items
/// - deleting the instance from the collection
/// </summary>
static void DocumentSetVersionSample()
{
using (SPSite site = new SPSite(siteUrl))
{
using (SPWeb web = site.RootWeb)
{
SPList list = web.Lists[listName];
EnsureVersioningOnList(list);
SPContentType docsetCT = list.ContentTypes[docSetContentTypeName];
// Find and perform sample actions on the first available Document Set
foreach (SPFolder subFolder in list.RootFolder.SubFolders)
{
if (subFolder.Item != null && subFolder.Item.ContentType.Id == docsetCT.Id)
{
Microsoft.Office.DocumentManagement.DocumentSets.DocumentSet docSet =
Microsoft.Office.DocumentManagement.DocumentSets.DocumentSet.GetDocumentSet(subFolder);
try
{
DocumentSetVersionCollection snapshots = docSet.VersionCollection;
// We need at least one snapshot to work with the sample
if (docSet.VersionCollection.Count == 0)
{
Console.WriteLine("Capturing a sample Document Set version snapshot...\n");
docSet.VersionCollection.Add(true, "A version for DocumentSetVersion API code sample.");
}
DocumentSetVersion snapshot = docSet.VersionCollection[0];
// The following example demonstrates the use of common properties
Console.WriteLine("Snapshot version {0} was captured by {1} on {2}.",
snapshot.VersionLabel,
snapshot.CreatedBy,
snapshot.Created);
Console.WriteLine("It captured latest checked-in {0} versions.",
snapshot.IsLastMajor ? "major" : "minor or major");
if (!string.IsNullOrEmpty(snapshot.Comments))
{
Console.WriteLine("Captured with the comment: {0}.", snapshot.Comments);
}
// The following example displays the metadata fields for the
// snapshot. Only fields that are still defined in the document
// set are output:
Console.WriteLine();
Console.WriteLine("Metadata field(s) for snapshot version {0}:", snapshot.VersionLabel);
foreach (DocumentSetVersionField field in snapshot.GetDisplayFields())
{
Console.WriteLine("Field \"{0}\" had value \"{1}\".",
list.Fields[field.Id].Title,
(field.Value == null) ? "" : field.Value);
}
// The following example displays the item versions captured in the
// snapshot. The information displayed contains the item name
// without extension and version captured. The URL to the item's
// latest version is also provided:
Console.WriteLine();
Console.WriteLine("Item(s) captured in this version:");
foreach (DocumentSetVersionItem item in snapshot.GetDisplayContents())
{
if (item.IsItemFound)
{
System.Console.Write("Item \"{0}\" was at version \"{1}\". ", item.Title, item.VersionLabel);
System.Console.WriteLine("The latest version of the item is at {0}", item.ItemUrl);
}
}
// The following example deletes the snapshot from the collection,
// if it exists:
Console.WriteLine();
Console.WriteLine("There {0} {1} snapshot{2} before deleting the above. Deleting...",
snapshots.Count == 1 ? "is" : "are",
snapshots.Count,
snapshots.Count == 1 ? "" : "s");
snapshot.Delete();
Console.WriteLine("After deletion, there {0} {1} snapshot{2} left.",
snapshots.Count == 1 ? "is" : "are",
snapshots.Count,
snapshots.Count == 1 ? "" : "s");
}
catch (InvalidOperationException ioe)
{
Console.WriteLine("Unable to perfrom the action because: {0}", ioe.ToString());
}
catch (ArgumentException ae) // Also catches subset of ArgumentOutOfRangeException
{
Console.WriteLine("Unable to perfrom the action because: {0}", ae.ToString());
}
catch (Exception ex)
{
Console.WriteLine("Unexpected error: {0}", ex.ToString());
}
break;
}
}
}
}
}
/// <summary>
/// The following code sample covers retrieving an instance
/// of DocumentSetVersionCollection as well as common operations:
/// - accessing common properties
/// - capturing a snapshot
/// - retrieving the latest snapshot and using indexers
/// - restoring Document Set metadata and items using snapshots
/// - using the restore point snapshot captured before restoring
/// - using the DocumentSetVersionCollection enumertor to list snapshots
/// - deleting all snapshots
/// </summary>
public static void DocumentSetVersionCollectionSample()
{
using (SPSite site = new SPSite(siteUrl))
{
using (SPWeb web = site.RootWeb)
{
SPList list = web.Lists[listName];
EnsureVersioningOnList(list);
SPContentType docsetCT = list.ContentTypes[docSetContentTypeName];
foreach (SPFolder subFolder in list.RootFolder.SubFolders)
{
if (subFolder.Item != null && subFolder.Item.ContentType.Id == docsetCT.Id)
{
Microsoft.Office.DocumentManagement.DocumentSets.DocumentSet docSet =
Microsoft.Office.DocumentManagement.DocumentSets.DocumentSet.GetDocumentSet(subFolder);
try
{
DocumentSetVersionCollection snapshots = docSet.VersionCollection;
// The following example demonstrates use of Folder and List
// properties of DocumentSetVersionCollection:
Console.WriteLine("DocumentSet \"{0}\" found in list \"{1}\".",
snapshots.Folder.Name, snapshots.List.Title);
// The following example demonstrates how to capture a snapshot.
// Note that we can only capture major version if minor versions
// are disabled:
Console.WriteLine();
Console.WriteLine("Capturing a sample Document Set version snapshot...");
bool captureMajorOnly = !snapshots.List.EnableMinorVersions;
snapshots.Add(captureMajorOnly, "A version for DocumentSetVersionCollection API code sample.");
string docSetUrl = snapshots.Folder.Url;
RefreshDocSetAndVersions(list, docSetUrl, false,
ref docSet, ref snapshots);
// The following example demonstrates how to use the Item
// and Count properties to retrieve the latest version:
DocumentSetVersion latestSnapshot = snapshots[0];
string originalVersionLabel = latestSnapshot.VersionLabel;
Console.WriteLine("Latest snapshot version (captured above) is {0}.",
originalVersionLabel);
// The following example demonstrates how to use the Item
// indexer via the label. It retrieves the latest snapshot:
latestSnapshot = snapshots[latestSnapshot.VersionLabel];
// The following example demonstrates how to restore document
// set metadata and items:
// First, change the document set title:
string originalDocSetTitle = docSet.Item.Name;
string newDocSetTile = string.Format("Name at {0}",
DateTime.Now.Millisecond);
docSet.Item["Name"] = newDocSetTile;
RefreshDocSetAndVersions(list, docSetUrl, true,
ref docSet, ref snapshots);
Console.WriteLine();
Console.WriteLine("Changed Document Set title from \"{0}\" to \"{1}\".",
originalDocSetTitle, docSet.Item.Name);
// Second, restore document set to values in the original snapshot:
Console.WriteLine("Now restoring documet set to version {0}. Name should become \"{1}\"...",
originalVersionLabel,
originalDocSetTitle);
Hashtable unrestoredItems = snapshots.Restore(originalVersionLabel);
DisplayUnrestoredItems(unrestoredItems);
RefreshDocSetAndVersions(list, docSetUrl, false,
ref docSet, ref snapshots);
Console.WriteLine("Now Document Set title is \"{0}\".",
docSet.Item.Name);
// The following example demonstrates use of enumerator (descending order) to
// show that when Restore() runs, it creates a restore point as the latest version:
Console.WriteLine();
Console.Write("Document Set has snapshot version(s): ");
string oldestSnapshotLabel = snapshots[snapshots.Count - 1].VersionLabel;
foreach (DocumentSetVersion snapshot in snapshots)
{
Console.Write("{0}{1}",
snapshot.VersionLabel,
// add separator for all but last snapshot
snapshot.VersionLabel == oldestSnapshotLabel ? ".\n" : ", ");
}
// The following example demonstrates use of restore
// point to reset document set title to the new value:
string restorePointVersionLabel = snapshots[0].VersionLabel;
Console.WriteLine();
Console.WriteLine("Restoring documet set to restore point - version {0}...",
restorePointVersionLabel);
unrestoredItems.Clear();
unrestoredItems = snapshots.Restore(restorePointVersionLabel);
DisplayUnrestoredItems(unrestoredItems);
RefreshDocSetAndVersions(list, docSetUrl, false,
ref docSet, ref snapshots);
Console.WriteLine("Restored Document Set title to \"{0}\" and the expected was \"{1}\".",
docSet.Item.Name, newDocSetTile);
// The following example demonstrates how to delete all the versions
// and check whether a certain version exists in the collection:
Console.WriteLine();
Console.WriteLine("Deleting all snapshots...");
snapshots.DeleteAll();
Console.Write("There are {0} snapshots left. ", snapshots.Count);
Console.WriteLine("Restore point version {0} is in the collection: {1}",
restorePointVersionLabel,
snapshots.Contains(restorePointVersionLabel));
}
catch (InvalidOperationException ioe)
{
Console.WriteLine("Unable to perfrom the action because: {0}", ioe.ToString());
}
catch (ArgumentException ae) // Also catches ArgumentOutOfRangeException, ArgumentNullException
{
Console.WriteLine("Unable to perfrom the action because: {0}", ae.ToString());
}
catch (KeyNotFoundException knfe)
{
Console.WriteLine("Unable to retrieve an item because: {0}", knfe.ToString());
}
catch (Exception ex)
{
Console.WriteLine("Unexpected error: {0}", ex.ToString());
}
}
}
}
}
}
/// <summary>
/// Ensures the list has versioning enabled.
/// </summary>
/// <remarks>
/// To use DocumentSetVersionCollection, the list must have
/// versioning enabled.
/// </remarks>
/// <param name="list">
/// An SPList representing list where versioning must
/// be ensured.
/// </param>
private static void EnsureVersioningOnList(SPList list)
{
if (!list.EnableVersioning)
{
list.EnableVersioning = true;
list.Update();
Console.WriteLine("Enabled versioning to use DocumentSetVersionCollection.");
}
}
/// <summary>
/// Refetches the documenst set and its snapshots
/// from the document set at url specified by <paramref name="docSetUrl"/>
/// parameter in the list specified by <paramref name="list"/> parameter.
/// </summary>
/// <param name="list">
/// An SPList representing the list where the document set resides.
/// </param>
/// <param name="docSetUrl">
/// A DocumentSet.Folder.Url string representing the folder url
/// of the document set.
/// </param>
/// <param name="updateDocSet">
/// A boolean that when true calls SPListItem.Update() on the
/// document set before refetching; otherwise no changes before
/// refetching are done.
/// </param>
/// <param name="docSet">
/// A DocumentSet which will be set after refetching the document set.
/// </param>
/// <param name="snapshots">
/// A DocumentSetVersionCollection which will be set after
/// refetching the document set.
/// </param>
private static void RefreshDocSetAndVersions(
SPList list,
string docSetUrl,
bool updateDocSet,
ref Microsoft.Office.DocumentManagement.DocumentSets.DocumentSet docSet,
ref DocumentSetVersionCollection snapshots)
{
if (updateDocSet)
{
docSet.Item.SystemUpdate();
}
SPListItem docSetItem = list.Items[docSet.Item.UniqueId];
docSet = Microsoft.Office.DocumentManagement.DocumentSets.DocumentSet.GetDocumentSet(docSetItem.Folder);
snapshots = docSet.VersionCollection;
}
/// <summary>
/// Displays the document set items that failed to restore
/// as specified by <paramref name="unrestoredItems"/>
/// </summary>
/// <param name="unrestoredItems">
/// Result of DocumentSetVersionCollection.Restore(sting) call,
/// representing collection of items that failed to restore.
/// </param>
private static void DisplayUnrestoredItems(Hashtable unrestoredItems)
{
if (unrestoredItems == null || unrestoredItems.Count == 0)
{
Console.WriteLine("All Document Set items restored successfully.");
return;
}
foreach (DictionaryEntry item in unrestoredItems)
{
Console.WriteLine("Failed to restore \"{0}\" because {1}.",
item.Key, item.Value);
}
}
}
}
Thread Safety
Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.