Using the CopyMove .NET API

Integrating server side code with CopyMove is best done using the CopyMove .NET API, which is exposed through the SharePointProducts.CopyMove.CopyMoveProcessor class in addition to the input and output parameter classes outlined in the previous section. To work with the API in Visual Studio it is necessary to add a reference to the following .NET assemblies located in the Global Assembly Cache:

The CopyMoveProcessor class contains the public methods listed below. The Copy, Move, Export and Import methods are synchronous and will not return before the transaction completes whereas the CopyAsync, MoveAsync, ExportAsync and ImportAsync methods are asynchronous. The latter methods launches a background worker thread and returns to the caller with the transaction id. The method GetStatus can in turn be used to track the progress of a specific transaction without blocking the caller. Finally, the GetResult method is used to obtain the result of an asynchronous transaction. Calling the method before the worker thread has completed the transaction blocks the caller until the transaction has completed and an instance of the CopyMoveResult class is ready to return.

public CopyMoveResult Copy(CopyMoveItemTransaction transaction)

public string CopyAsync(CopyMoveItemTransaction transaction)

public CopyMoveResult Move(CopyMoveItemTransaction transaction)

public string MoveAsync(CopyMoveItemTransaction transaction)

public CopyMoveResult Export(CopyMoveItemTransaction transaction)

public CopyMoveResult Export(CopyMoveListTransaction transaction)

public string ExportAsync(CopyMoveItemTransaction transaction)

public string ExportAsync(CopyMoveListTransaction transaction)

public CopyMoveResult Import(CopyMoveItemTransaction transaction)

public string ImportAsync(CopyMoveItemTransaction transaction)

public CopyMoveStatus GetStatus(string transactionId)

public CopyMoveResult GetResult(string transactionId)

The following example demonstrates how to use the .NET API to move a folder and two documents from one document library to another document library within the same SharePoint farm.

// Create a new instance of the CopyMove API facade class

var processor = new CopyMoveProcessor();

// Prepare new CopyMove item transaction

var transaction = new CopyMoveItemTransaction();

transaction.OverwriteFiles = true;

transaction.IncludeTimestamps = true;

transaction.IncludeUserInfo = true;

transaction.IncludeVersions = true;

transaction.IncludeSecurity = false;

transaction.HaltOnWarning = false;

// The absolute URL of the source folder or source list

transaction.SourceFolder = "http://server/sites/site1/doclib/folder";

// The absolute URL of the target folder or target list

transaction.TargetFolder = "http://server/sites/site2/doclib/folder";

// The source items to copy. Each item can be specified by its

// absolute URL, server relative URL, filename, list item GUID or list item ID.

// In this example, we just specify the filenames of a folder and two documents

// in the source folder specified above.

transaction.Items = new string[]

{

  "Test Folder", "Test Document.doc", "Test Document.pdf",

};

// Optional: Exclude one or more list columns

transaction.ExcludeProperties = new string[] { "FieldName1", "FieldName2" };

// Start the Move process in a separate thread. The MoveAsync method returns

// immediately after launching the background thread that does the actual

// copying of items.

string transactionId = processor.MoveAsync(transaction);

// CopyMove keeps track of the progress in the worker thread

// and you can optionally ask for it using the GetStatus method.

while (true)

{

  Thread.Sleep(500);

  CopyMoveStatus status = processor.GetStatus(transactionId);

   // TODO: Display progress to user

  if (status.ProgressPct == 100) break;

}

// Get the final result of the transaction. The GetResult

// method blocks until the transaction has completed or

// was aborted by an error

CopyMoveResult result = processor.GetResult(transactionId);

if (result.ErrorCode == 0)

{

  // Success - the transaction completed without errors or warnings

} else if (result.ErrorCode == 1)

{

  // Warning - the transaction completed with warnings

} else if (result.ErrorCode == 2)

{

  // Error - the transaction was aborted with errors

}

The sample code shown above can also be found in the Form1.cs file of the Visual Studio project named API Sample. It is included in the CopyMove product download.