The Application Programming Interface for CopyMove enables SharePoint software developers to integrate CopyMove with their own SharePoint applications. Basically, the API supports the operations; copy, move, export and import. They can respectively be leveraged to copy, move, export and import one or more folders, documents and list items at a time. The items are handled with full fidelity including Metadata, version history and item level permissions. In this context, the Metadata includes the created and modified timestamps, the created by and modified by users, other system Metadata and custom Metadata.
The API is exposed as a .NET object model for use in server side code and as a WCF service for remote client use. The .NET API exposes the following methods:
CopyMoveResult Copy(CopyMoveItemTransaction transaction);
CopyMoveResult Move(CopyMoveItemTransaction transaction);
CopyMoveResult Export(CopyMoveItemTransaction transaction);
CopyMoveResult Import(CopyMoveItemTransaction transaction);
CopyMoveStatus GetStatus(string transactionId);
where the WCF service is currently only exposing the Copy, Move and GetStatus methods. There are also some differences with respect to asynchronous invocation of the operations - but more about this later.
The Copy, Move, Export and Import methods all take an instance of the CopyMoveItemTransaction class as input and returns an instance of the CopyMoveResult class when the transaction is completed or aborted by errors or warnings. Larger transactions can take some time to complete and the GetStatus method can then be used to track the progress from another thread or from the same thread if the operations are invoked asynchronously as demonstrated later in this chapter. The following class diagram outlines the details of the input and output parameter classes in the API. The facade classes are documented in the next two sections.
The following tables documents each class and its properties shown in the class diagram above.
CopyMoveStatus An instance of this class is returned by the GetStatus method and it contains progress information for the specified transaction. |
||
|---|---|---|
Property |
Type |
Description |
Message |
string |
Gets a textual message about the current progress of the copy or move transaction. The value of this property is designed to be used directly in a user interface. CopyMove displays the message together with the progress bar during a transaction. |
ProgressByteCount |
long |
Gets the number of bytes copied or moved so far. Only document library files and list item attachments count. |
ProgressFileCount |
int |
Gets the number of files copied or moved so far by the transaction. |
ProgressFolderCount |
int |
Gets the number of folders copied or moved so far by the transaction. |
ProgressItemCount |
int |
Gets the number of list items copied or moved so far by the transaction. |
ProgressPct |
int |
Gets the progress in percent. |
ProgressTime |
int |
Gets the number of miliseconds that the transaction has been working. |
Running |
bool |
Gets a value indicating whether the transaction is still running. |
State |
int |
Gets the current state of the transaction. |
TotalByteCount |
long |
Gets the total number of bytes to be copied or moved. Only document library files and list item attachments count. |
TotalFileCount |
int |
Gets the total number of files to be copied or moved by the transaction. |
TotalFolderCount |
int |
Gets the total number of folders to be copied or moved by the transaction. |
TotalItemCount |
int |
Gets the total number of list items to be copied or moved by the transaction. |
CopyMoveTransaction |
||
|---|---|---|
Property |
Type |
Description |
Id |
string |
Gets or sets the transaction id. |
IncludeTimestamps |
bool |
Gets or sets a value indicating whether to include and preserve the created time and modified time on items. The default value is true. |
IncludeUserInfo |
bool |
Gets or sets a value indicating whether to include and preserve the created by user and the last modified by user. The default value is true. |
IncludeVersions |
bool |
Gets or sets a value indicating whether to include and preserve version history, if any. The default value is true. |
IncludeSecurity |
bool |
Gets or sets a value indicating whether to include item level permissions or not. The default value is false. |
IncludeFolders |
bool |
Gets or sets a value indicating whether to include sub-folders when copying, moving or exporting content. The default value is false. |
ExcludeProperties |
string[] |
Optional. Gets or sets an array of Metadata property names to exclude. To exclude values for a specific list column, include the internal name of that column here. |
OverwriteFiles |
bool |
Gets or sets a value indicating whether to overwrite existing files. Deprecated - instead use the FileExistsAction property. |
FileExistsAction |
enum |
Gets or sets the action for existing files. Possible values are: 1 = CopyMoveFileExistsAction.Skip = The existing destination file is left as is and the source file is not copied/moved. 2 = CopyMoveFileExistsAction.Overwrite = The existing destination file is deleted and replaced with a copy of the source file. 3 = CopyMoveFileExistsAction.Rename = The existing destination file is left as is and the source file is renamed with a new unique file name. 4 = CopyMoveFileExistsAction.AddAsNewVersion = The source file is added as a new version to the existing destination file. However, only if versioning is enabled. |
ExportFilter |
string |
Optional. Get or sets a SharePoint CAML query to only export matching items. Applies to exports only. |
HaltOnNonFatalError |
bool |
Gets or sets a value indicating if the transaction should abort on non fatal errors.The default is true. |
HaltOnWarning |
bool |
Gets or sets a value indicating if the transaction should abort on warnings. A typical warning is when copying or moving a file and it already exists in the destination. The CopyMove UI always starts with this property set to true. Any warnings will abort the transaction and CopyMove displays them to the user for confirmation. If the user confirms the warnings then CopyMove restarts the transaction with the HaltOnWarning property set to false. The default value is true. |
SourceUrl |
string |
Gets or sets the absolute URL of the source list or the source folder in SharePoint. For import transactions this property must specify the Windows server file path to the ZIP archive or file system folder containing the content to import. |
TargetUrl |
string |
Gets or sets the absolute URL of the destination list or the destination folder in SharePoint. For export transactions this property must specify the Windows server path to a folder where the resulting ZIP archive should be saved to. |
CopyMoveItemTransaction |
||
|---|---|---|
Property |
Type |
Description |
ContentTypeMapings |
string[] |
Gets or sets an array of content type mappings in the string format <SourceContentTypeId>:<TargetContentTypeId> |
DefaultFieldValues |
string[] |
Gets or sets an array of default values for required fields where the source item does not provide a value for the column in the destination. |
EnforceRequiredFieldValues |
bool |
Gets or sets a value that determines whether CopyMove will enforce missing values on required fields. The default value is true. |
Items |
string[] |
Gets or sets an array of the folders, documents or items to include in the transaction. Each source item can be specified by its absolute URL, server relative URL, filename, list item GUID or list item ID. All items must exist in the source folder specified by the SourceUrl property. |
Recursive |
bool |
Obsolete. Use the IncludeFolders property instead. |
SourceFolder |
string |
Obsolete. Gets or sets the absolute URL of the source list or source folder. |
TargetFolder |
string |
Obsolete. Gets or sets the absolute URL of the destination list or source folder. It can be any compatible folder in the SharePoint farm. |
CopyMoveResult An instance of this class is returned by the Copy and Move methods when the transaction ends. |
||
|---|---|---|
Property |
Type |
Description |
ByteCount |
long |
Gets the total number of bytes copied or moved. Only document library files and list item attachments count. |
ErrorCode |
int |
Gets the overall status of the completed transaction. Possible values are: 0 = Ok 1 = Transaction aborted with warnings 2 = Transaction aborted with errors |
Errors |
CopyMoveMessage[] |
Gets an array of detailed error messages if the ErrorCode=2 |
ExecutionTime |
int |
Gets the total number of miliseconds it took to execute the transaction. |
FileCount |
int |
Gets the total number of files that were copied or moved by the transaction. |
FolderCount |
int |
Gets the total number of folders that were copied or moved by the transaction. |
ItemCount |
int |
Gets the total number of list items that were copied or moved by the transaction. |
Items |
CopyMoveItem[] |
Gets an array holding one entry with information for each destination item that was created during a copy, move or import transaction. |
Message |
string |
Gets a textual message describing the outcome of the transaction. The value of this property is designed to be used directly in a user interface. CopyMove displays this message to the user when a transaction completes. |
TransactionId |
string |
Gets the id of the transaction that produced the result. |
Warnings |
CopyMoveMessage[] |
Gets an array of detailed warning messages if the ErrorCode=1 |
CopyMoveMessage Represents a message from CopyMove. |
||
|---|---|---|
Property |
Type |
Description |
Exception |
Exception |
If the message represents an error then this property contains the Exception that triggered it. |
Id |
int |
Gets the message id, which can be any of the following values defined as public constants in the class: Warning_FileExist = 101; Warning_FilesExist = 102; Warning_LossOfMajorVersionHistory = 110; Warning_LossOfMinorVersionHistory = 111; Warning_LossOfContentType = 112; Warning_LossOfListFieldValue = 113; Warning_LossOfPageLayout = 115; Warning_LossOfPartialMajorVersionHistory = 116; Warning_LossOfWebPart = 117; Warning_MoveInPlaceRecord = 145; Warning_MoveItemOnHold = 146; Error_InvalidTarget = 200; Error_SiteNotFound = 201; Error_ListNotFound = 202; Error_FolderNotFound = 203; Error_ItemNotFound = 204; Error_SourceNotFound = 205; Error_InvalidSource = 206; Error_MissingManifest = 207; Error_SQL = 208; Error_IO = 209; Error_AccessDenied_OpenSite = 210; Error_AccessDenied_CopyItem = 211; Error_AccessDenied_MoveItem = 212; Error_AccessDenied_ExportItem = 215; Error_AccessDenied_ImportItem = 216; Error_AccessDenied_SourceList = 217; Error_AccessDenied_SourceFolder = 218; Error_AccessDenied_TargetList = 219; Error_AccessDenied_TargetFolder = 220; Error_AccessDenied_OverwriteTargetItem = 221; Error_FileTargetUrlTooLong = 230; Error_FolderTargetUrlTooLong = 231; Error_IncompatibleTargetList = 232; Error_TransactionItemCountExceeded = 234; Error_TransactionFileCountExceeded = 235; Error_TransactionFolderCountExceeded = 236; Error_TransactionFileSizeExceeded = 237; Error_TargetFolderIsLinkStub = 238; Error_CannotCreateFoldersInDocumentSet = 239; Error_OverwriteCheckedOutFile = 240; Error_OverwriteLockedFile = 241; Error_OverwriteInPlaceRecord = 242; Error_MoveCheckedOutFile = 243; Error_MoveLockedFile = 244; Error_MoveInPlaceRecord = 245; Error_MoveFolderToSelf = 246; Error_MoveItemOnHold = 247; Error_TargetFolderCreationNotAllowed = 248; Error_DuplicateTargetFiles = 249; Error_CannotDeleteSourceItem = 250; Error_ConcurrentMove = 251; Error_NoItems = 252; Error_CannotExportWebPart = 253; Error_CannotImportWebPart = 254; Error_FileSizeExceeded = 255; Error_FileVersionSizeExceeded = 256; Error_StorageQuotaExceeded = 257; Error_TargetSiteNoPublishing = 260; Error_MissingRequiredField = 301; |
Text |
string |
Gets the message text. |