Breaking down document locking in SharePoint

This is a topic I've been meaning to discuss in a while.

We open, change and close documents almost every day, and sometimes we collaborate with other people at the same time on those documents.

SharePoint brings all co-authoring features we need, straight out-of-the-box, but sometimes, there are problems.

While things are starting to look better on the cloud side, the concept of document locking is still very much up-to-date and understanding how it works and what to do when things go wrong is crucial.

In an article that has since disappeared the Microsoft Knowledge Base (but still available here), Microsoft explains it best:

When a document is opened by a client program, Windows SharePoint Services puts a write lock on the document on the server. The write lock times out after 10 minutes. Users cannot modify the document during the time when the document is locked.

In a scenario where the program that opens the document unexpectedly quits or crashes and you try to open the document again before the write lock times out, the message that you receive says that the document is locked by another user. This behavior occurs even though you are user who previously opened the document.

So, what do we know:

  • There's this thing called document lock
  • Locks get automatically created when documents are opened (in edit mode)
  • Locks go away when we close the document
  • If the document crashes, we won't have a chance to close it, so the lock will stay until the timeout expires
  • Locks aren't necessarily bad things. Word documents use "shared" locks, meaning that a user who enters edit mode doesn't prevent other users to also enter edit mode on the same document
  • In most versions of SharePoint, if an Excel document is edited through the Office Client, an "exclusive" lock is created, thus preventing co-authoring
  • There are properties are available which contain information about the lock:
    • vti_sourcecontrollockid - the ID of the lock which can be used to release the lock
    • vti_sourcecontrollocktype - the type of lock (0-Exclusive, 1-Shared, 2-None)
    • vti_sourcecontrollockexpiresvalue - the date (UTC) when the lock expires
    • vti_sourcecontroltimecheckedout - the date (UTC) when the lock began
    • vti_sourcecontrolcheckedoutby - the user who owns the lock

In the below diagram, I try to explain this very concept.



How to avoid document locks

The best way to avoid getting into a situation where you cannot change a document is to follow some best practices.

  • Save and close documents often
  • If possible, close all Office documents at the end of the working day
  • Ensure to have a stable connection to servers hosting the document (prefer cable over WiFi)
  • Avoid leaving documents open for long periods of time


What can be done to force release of the lock

There are a few ways to unlock a document, but most of them can only be performed by administrator, or be exposed in a user interface by a developer.

Option #1 - Server-side PowerShell

The most straight-forward way, if you're able to access the server, is to run SPFile.ReleaseLock.

This method will effectively release the lock from the document.

While you could simply run

$file = $web.GetFile($fileURL)

$file.ReleaseLock($file.LockId)

This may fail, as exclusive locks can only be released by their users.

So, to account for that, we could add a few extra lines as so:


Option #2 - Server-side component (C#)

If you want to expose this code in a page or web component, you could create a package and deploy this function as below.


Option #3 - HTML/Javascript page

Thanks to Peter Hoplar's post back in 2014 (!), we have a method in which we can allow users themselves to unlock documents that they have themselves locked.

There are some limitations, such as requiring Internet Explorer, but it is working today in SharePoint 2010/2013/2016/2019.

The idea is to create a page and add the script to the style library. Then add a Content Editor to the page and reference it to the URL of the script. The script will allow the user to input the Web URL and Document URL and allow to check the lock state and grant the option to force release the lock, if there is one.

Due to the length of the script, I'll just post a link to it here.





References

How To Use JavaScript To Delete Short-Term Locks From Documents Opened From SharePoint?

Can we unlock a ShortTerm lock via CSOM for SP2013

Behind the scenes: Opening a Document from a SharePoint 2010 Document Library

SPFile.LockType

SPFile.ReleaseLock

Excel file is locked for editing by another user (MS article on troubleshoot steps)

Comments

  1. Have you observed any changes (2023) in the use of vti_sourcecontrollockid on a locked file? Specifically, has SharePoint stopped outputting that value in the MetaInfo of a locked file?

    ReplyDelete
  2. I'm still able to get lock data but in Office 365 I'm replying on File.Properties instead, e.g., string propLockId = file.Properties["vti_sourcecontrollockid"].ToString()
    I'm also working on a method to unlock documents via CSOM which surprisingly works, the only problem is that I need to know the ClientID which is nearly impossible since it's an auto-generated GUID that changes over time. but if I'm able to run fiddler I can extract it from the CellStorageService call. It's just a bit of a cumbersome method unlike before. If I'm lucky I may post my findings in a new post

    ReplyDelete

Post a Comment

Popular posts from this blog

Mobile development opportunities

Working around X-Frame-Options for iframes