CopyMove .NET API

 Top  Previous  Next

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:

•SharePointProducts.Platform.dll
•SharePointProducts.CopyMove.dll

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)

How-to instantiate the CopyMoveProcessor

Creating a new instance with the default constructor yields a new instance using the CopyMove settings stored in SharePoint and which will run as the current SharePoint user if the current thread has a SharePoint context. Otherwise, it will run as the current Windows user.

 

var processor = new CopyMoveProcessor();

There is also an overloaded constructor that makes it possible to specify the settings to user and the user to run as.

var settings = new CopyMoveSettings {

    TemporaryFilesLocation = @"D:\CopyMoveTemp",

    UseRecycleBin = false,

    KeepTemporaryFilesUntilCleanup = true

};

var processor = new CopyMoveProcessor(settings, @"SHAREPOINT\SYSTEM");

How-to Copy/Move a single file

The sample code below demonstrates how to use the CopyMove .NET API to move a single file from one location to another within the same SharePoint farm.

// Create a new instance of the CopyMoveProcessor class 

var processor = new CopyMoveProcessor();

 

// Prepare new CopyMove item transaction

var transaction = new CopyMoveItemTransaction();

transaction.FileExistsAction = CopyMoveFileExistsAction.Overwrite;

transaction.IncludeTimestamps = true;

transaction.IncludeUserInfo = true;

transaction.IncludeVersions = true;

transaction.IncludeSecurity = true;

transaction.HaltOnWarning = false;

 

// The absolute URL of the source file and the target file

transaction.SourceUrl = "https://host/sites/site1/doclib/folder/document.ext";

transaction.TargetUrl = "https://host/sites/site2/doclib/folder/newdocument.ext";

 

// Move the document and wait for the transaction to complete

CopyMoveResult result = processor.Move(transaction);

 

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

}

How-to Copy/Move multiple files

This example demonstrates how to use the CopyMove .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 CopyMoveProcessor class

var processor = new CopyMoveProcessor();

 

// Prepare new CopyMove item transaction

var transaction = new CopyMoveItemTransaction();

transaction.FileExistsAction = CopyMoveFileExistsAction.Overwrite;

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.SourceUrl = "https://host/sites/site1/doclib/folder";

 

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

transaction.TargetUrl = "https://host/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 transaction 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.

CopyMoveStatus status;

do

{

  Thread.Sleep(500);

   status = processor.GetStatus(transactionId);

 

   // TODO: Display progress to user

} while (status.IsRunning)

 

// 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.

How-to Export Files to ZIP

This example demonstrates how to use the CopyMove .NET API to export a folder and two documents from a document library to a ZIP file on disk.

// Create a new instance of the CopyMoveProcessor class

var processor = new CopyMoveProcessor();

 

// Prepare new CopyMove item transaction

var transaction = new CopyMoveItemTransaction();

transaction.IncludeTimestamps = true;

transaction.IncludeUserInfo = true;

transaction.IncludeVersions = true;

transaction.IncludeSecurity = true;

transaction.HaltOnWarning = false;

         

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

transaction.SourceUrl = "https://host/sites/site1/doclib/folder";

 

// The file path of the zip file to export

transaction.TargetUrl = @"D:\CopyMove\Export.zip";

 

// 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"

};

 

// Export the items and wait for the transaction to complete

CopyMoveResult result = processor.Export(transaction);

How-to Import Files from ZIP

Importing the files again is just as easy:

// Create a new instance of the CopyMoveProcessor class

var processor = new CopyMoveProcessor();

 

// Prepare new CopyMove item transaction

var transaction = new CopyMoveItemTransaction();

transaction.IncludeTimestamps = true;

transaction.IncludeUserInfo = true;

transaction.IncludeVersions = true;

transaction.IncludeSecurity = true;

transaction.HaltOnWarning = false;

 

// The file path of the zip file to import

transaction.SourceUrl = @"D:\CopyMove\Export.zip";

         

// The absolute URL of the destination folder

transaction.TargetUrl = "https://host/sites/site1/doclib/folder";

 

// Export the items and wait for the transaction to complete

CopyMoveResult result = processor.Import(transaction);