Improved API support for working with files in the SharePoint recycle bin

SharePoint team

June 22nd, 2021 0

We’re rolling out some improvements for working with files in the SharePoint recycle bin. Once these changes are active, files and folders that are recycled will be placed into new “recycle bin libraries”. Contents of recycled files in these new libraries can be accessed by APIs with the use of a special request header.

[Updated 4th of August 2023] – This feature is has been rolled back and is not currently enabled in production.

These new recycle bin libraries will have some special behaviors:

By default, they will be hidden from APIs which enumerate or otherwise interact with lists or libraries
By default, files and folders within them will not be accessible by the UI or APIs
They will not have forms or views
They are implicitly created when files or folders are recycled and cannot be created directly
They mirror the schema and settings of the source library from which files and folders are recycled

Accessing Recycled Files with a new x-RecycleBinContentAware Header

Recycle bin libraries, and the items within them, can be accessed by including the following request header:

  x-RecycleBinContentAware: True

Providing this header when setting up the Context of an SPSite or SPWeb will:

Allow the SPList object for recycle bin libraries to be enumerated
Allow the SPFile, SPFolder, and SPListItem objects within recycle bin libraries to be enumerated
Treat the SPSite, and associated SPWeb, as read-only in the scope of the request for all content
Append a query parameter to pre-authenticated URLs on recycled files that enable content download

New ChangeLog Behavior

Because these new libraries are hidden from the UI and APIs by default, these changes should not generally have any impact on end-users or applications with one exception; change log operations for files and folders moving to and from the SharePoint recycle bin will look different. Applications that consume operations from the change log, by using the Site.GetChanges and Web.GetChanges APIs for example, may need to be updated to understand this new behavior.

When a file or folder is recycled, the new behavior will be to:

Ensure a recycle bin library exists corresponding to the library the file/folder is in.
Create a folder in the recycle bin library to correspond to the recycle bin item.
Break inheritance on the recycle bin item folder and copy the permissions to match the effective permissions of the file/folder being recycled.
Move the recycled file/folder to the new folder.

When a file or folder is restored, the new behavior will be to:

Move the recycled file/folder from the recycle bin item folder back to its original location.
Delete the folder

When a file or folder is purged, the new behavior will be to:

Delete the recycle bin item folder (including its contents)

To support this new behavior, two new properties called MoveWasForRecyle and MoveWasForRestore will be added to change log operations to help distinguish the scenarios mentioned above.

Here’s an example of what these updated operations might look like for each of the above scenarios.

File operation – Recycle a file/folder

Example change log operations (BEFORE)

ChangeType: Delete
Id: 1
UniqueId: 3275877d-229e-4767-bfee-83020b81826d
BeforeId: 1
AfterId: 1
ListId: 42782c92-928b-463e-bc3a-85b315c2eab7
BeforeListId: 42782c92-928b-463e-bc3a-85b315c2eab7
AfterListId: 42782c92-928b-463e-bc3a-85b315c2eab7
MoveWasForRecycle: False
MoveWasForRestore: False
ObjectType: Item
Token: 1;1;090d6057-a037-4c7f-9e38-40ae9bc9a820;637480701247470000;4493

Example change log operations (AFTER)

ChangeType: Add
Id: 2
UniqueId: 525dec27-ba55-4bde-9fe0-555369d9636e
BeforeId: 2
AfterId: 2
ListId: d2812400-908e-4236-b2ec-ded5598ae029
BeforeListId: d2812400-908e-4236-b2ec-ded5598ae029
AfterListId: d2812400-908e-4236-b2ec-ded5598ae029
MoveWasForRecycle: False
MoveWasForRestore: False
ObjectType: Item
Token: 1;1;090d6057-a037-4c7f-9e38-40ae9bc9a820;637480701259930000;4515

ChangeType: AssignmentAdd
Id: 2
UniqueId: 525dec27-ba55-4bde-9fe0-555369d9636e
BeforeId: 2
AfterId: 2
ListId: d2812400-908e-4236-b2ec-ded5598ae029
BeforeListId: d2812400-908e-4236-b2ec-ded5598ae029
AfterListId: d2812400-908e-4236-b2ec-ded5598ae029
MoveWasForRecycle: False
MoveWasForRestore: False
ObjectType: Item
Token: 1;1;090d6057-a037-4c7f-9e38-40ae9bc9a820;637480701259930000;4516

ChangeType: ScopeAdd
Id: 2
UniqueId: 525dec27-ba55-4bde-9fe0-555369d9636e
BeforeId: 2
AfterId: 2
ListId: d2812400-908e-4236-b2ec-ded5598ae029
BeforeListId: d2812400-908e-4236-b2ec-ded5598ae029
AfterListId: d2812400-908e-4236-b2ec-ded5598ae029
MoveWasForRecycle: False
MoveWasForRestore: False
ObjectType: Item
Token: 1;1;090d6057-a037-4c7f-9e38-40ae9bc9a820;637480701259930000;4517

ChangeType: MoveAway
Id: 1
UniqueId: 10e02ee2-b76f-46ce-b084-9030607d92da
BeforeId: 1
AfterId: 1
ListId: 14d4eefa-1c3c-491e-8b5b-14b993f35bde
BeforeListId: 14d4eefa-1c3c-491e-8b5b-14b993f35bde
AfterListId: d2812400-908e-4236-b2ec-ded5598ae029
MoveWasForRecycle: True
MoveWasForRestore: False
ObjectType: Item
Token: 1;1;090d6057-a037-4c7f-9e38-40ae9bc9a820;637480701260000000;4518

ChangeType: MoveInto
Id: 1
UniqueId: 10e02ee2-b76f-46ce-b084-9030607d92da
BeforeId: 1
AfterId: 1
ListId: d2812400-908e-4236-b2ec-ded5598ae029
BeforeListId: 14d4eefa-1c3c-491e-8b5b-14b993f35bde
AfterListId: d2812400-908e-4236-b2ec-ded5598ae029
MoveWasForRecycle: True
MoveWasForRestore: False
ObjectType: Item
Token: 1;1;090d6057-a037-4c7f-9e38-40ae9bc9a820;637480701260000000;4519

File operation – Restore a file/folder

Example change log operations (BEFORE)

ChangeType: Restore
Id: 1
UniqueId: 3275877d-229e-4767-bfee-83020b81826d
BeforeId: 1
AfterId: 1
ListId: 42782c92-928b-463e-bc3a-85b315c2eab7
BeforeListId: 42782c92-928b-463e-bc3a-85b315c2eab7
AfterListId: 42782c92-928b-463e-bc3a-85b315c2eab7
MoveWasForRecycle: False
MoveWasForRestore: False
ObjectType: Item
Token: 1;1;090d6057-a037-4c7f-9e38-40ae9bc9a820;637480701247700000;4494

Example change log operations (AFTER)

ChangeType: MoveAway
Id: 1
UniqueId: 10e02ee2-b76f-46ce-b084-9030607d92da
BeforeId: 1
AfterId: 1
ListId: d2812400-908e-4236-b2ec-ded5598ae029
BeforeListId: d2812400-908e-4236-b2ec-ded5598ae029
AfterListId: 14d4eefa-1c3c-491e-8b5b-14b993f35bde
MoveWasForRecycle: False
MoveWasForRestore: True
ObjectType: Item
Token: 1;1;090d6057-a037-4c7f-9e38-40ae9bc9a820;637480701260200000;4520

ChangeType: MoveInto
Id: 1
UniqueId: 10e02ee2-b76f-46ce-b084-9030607d92da
BeforeId: 1
AfterId: 1
ListId: 14d4eefa-1c3c-491e-8b5b-14b993f35bde
BeforeListId: d2812400-908e-4236-b2ec-ded5598ae029
AfterListId: 14d4eefa-1c3c-491e-8b5b-14b993f35bde
MoveWasForRecycle: False
MoveWasForRestore: True
ObjectType: Item
Token: 1;1;090d6057-a037-4c7f-9e38-40ae9bc9a820;637480701260200000;4521

ChangeType: Delete
Id: 2
UniqueId: 525dec27-ba55-4bde-9fe0-555369d9636e
BeforeId: 2
AfterId: 2
ListId: d2812400-908e-4236-b2ec-ded5598ae029
BeforeListId: d2812400-908e-4236-b2ec-ded5598ae029
AfterListId: d2812400-908e-4236-b2ec-ded5598ae029
MoveWasForRecycle: False
MoveWasForRestore: False
ObjectType: Item
Token: 1;1;090d6057-a037-4c7f-9e38-40ae9bc9a820;637480701260230000;4522

File operation – Purge a file/folder

Example change log operations (BEFORE)

ChangeType: Delete
Id: 1
UniqueId: 3275877d-229e-4767-bfee-83020b81826d
BeforeId: 1
AfterId: 1
ListId: 42782c92-928b-463e-bc3a-85b315c2eab7
BeforeListId: 42782c92-928b-463e-bc3a-85b315c2eab7
AfterListId: 42782c92-928b-463e-bc3a-85b315c2eab7
MoveWasForRecycle: False
MoveWasForRestore: False
ObjectType: Item
Token: 1;1;090d6057-a037-4c7f-9e38-40ae9bc9a820;637480701251170000;4495

Example change log operations (AFTER)

ChangeType: Delete
Id: 3
UniqueId: be147871-1f43-497f-8235-4b247844cc1a
BeforeId: 3
AfterId: 3
ListId: d2812400-908e-4236-b2ec-ded5598ae029
BeforeListId: d2812400-908e-4236-b2ec-ded5598ae029
AfterListId: d2812400-908e-4236-b2ec-ded5598ae029
MoveWasForRecycle: False
MoveWasForRestore: False
ObjectType: Item
Token: 1;1;090d6057-a037-4c7f-9e38-40ae9bc9a820;637480701263770000;4528

“Sharing is caring”

SharePoint Team, Microsoft – 22nd of June 2021