This documentation is archived and is not being maintained.

Preventing Document Modification in Windows SharePoint Services 3.0

Windows SharePoint Services 3

Summary:  Learn how you can allow users to modify metadata but not file contents in Windows SharePoint Services 3.0 by using event handlers and handling short-term and long-term check-out processes.

Visual How To

Applies to:  Windows SharePoint Services 3.0

Microsoft Corporation

June 2008


Windows SharePoint Services 3.0 provides a versioning capability that prevents documents from being overwritten by creating a version of the file each time a change is made to either the file or the metadata. However, there may be specific situations, such as archival or records-management scenarios, in which you want to let users modify metadata but not modify the file contents; that is, there is always only one version of the file. This Microsoft Office Visual How To shows how you can enable this in specific scenarios by using event handlers and handling short-term and long-term check-outs.

Code It

This example deals with two basic types of check-out processes in Windows SharePoint Services: short term and long term. Short-term check-outs are implicit and are done when a document is opened for editing. A lock is applied to the file while it is being edited in the client application so that no other users can modify it. After the client application is closed, the lock is released. Long-term check-outs are explicit and lock the document regardless of whether it is opened and being edited in the client application. It remains checked out until it is explicitly checked back in.

In this example, you allow modification of metadata but prevent modification of the file by handling both long- and short-term check-outs in three ways:

  • Preventing the user from performing a long-term check-out process on a file

  • Handling a short-term check-out process created by an application, such as Microsoft Office Word

  • Preventing a check-in process if a long term check-out process has been automatically initiated, such as during the file upload process

These situations are handled with a custom EventReceiver registered on the document library, using the ItemCheckingOut and ItemUpdating event handlers. Additionally, it is important to note that the document library must have versioning enabled, but the Require Check Out setting and the Allow Major/Minor versions setting must both be set to No. Setting required check-out to No, together with the event handlers, enables you to modify the metadata without overwriting the file contents.

Figure 1. Require check out

Require check out

To prevent the user from doing a long-term check-out process, such as by clicking the Check Out link in the Edit Control Block (ECB), the ItemCheckingOut event is canceled any time it is executed. To do this, override the ItemCheckingOut method, and set the properties.Status to the CancelNoError enumeration. This displays the default system message to the user and cancels the check-out process.

PublicOverridesSub ItemCheckingOut(ByVal properties As SPItemEventProperties)
                properties.Status = SPEventReceiverStatus.CancelNoError

Although you prevent the user from performing a check-out process, there may be situations where a file is checked out in some other way. Examples include a short-term check-out process performed by a client application, or a long-term check-out automatically done when you upload a file that does not have all the required metadata. Both situations involve a check-out process that would occur outside the control of the ItemCheckingOut event. These check-out processes are handled in the ItemUpdating event handler.

If either of these types of check-out process occurs, it may appear at first glance that you can prevent the original file from being overwritten by preventing the checked-out file from being checked in. However, if a checked-in version does not already exist, you must allow the first checked-in version to proceed.

You can determine if a checked-in version exists by evaluating the Level property of the file. Files that have been uploaded to the system and checked in have a level equal to SPFileLevel.Published. If a file does not have a level of Published, meaning a checked-in version does not exist, you let processing continue, and the file is checked in. Note that the check of the published status is why major/minor versioning must be disabled on the library. This ensures that only files with checked-in versions have a level of Published.

If a file has a level of Published and is also checked out, you want to prevent it from being checked in and continue to evaluate the check-out status. The check-out status indicates either a short-term or long-term check-out process has been performed. If the status is a short-term check-out, you set the status and cancel properties of the SPItemEventProperties object to stop further processing. For a long-term check-out, you first undo the check-out, so that the file is checked back in and any changes undone, and then you set the Status property and the Cancel property to stop further processing. For both short-term and long-term check-out processes, this prevents the file from being checked in and overwriting the original.

PublicOverridesSub ItemUpdating(ByVal properties As SPItemEventProperties)
Dim file As SPFile = properties.ListItem.File
If file.Level = SPFileLevel.Published And file.CheckOutStatus <> SPFile.SPCheckOutStatus.None Then
If (file.CheckOutStatus = SPFile.SPCheckOutStatus.LongTerm) Then
                    properties.Status = SPEventReceiverStatus.CancelWithError
                    properties.Cancel = True
Read It

The check-out functionality provided by Windows SharePoint Services is an important part of this example. Even though you are preventing the file from being overwritten in event handlers, the user can still modify the metadata. This is because you set Require Check Out to No on the library. This allows changes to be made to the metadata without requiring the user to check out the file. However, if a file is checked out in an attempt to overwrite the file, you handle the check-out process and prevent the file from being overwritten.

In this example, you are handling both short- and long-term check-out processes to prevent the file from being overwritten and helping users perform the right task, but it is not a replacement for security. For example, alternative methods for attempting to overwrite a file, such as Windows Explorer/WebDav, would bypass the event handlers and allow an existing file to be overwritten. Indeed, it is only because the standard Windows SharePoint Services Upload page checks out uploaded files that this approach works. This approach does not necessarily apply to other ways of adding content to Windows SharePoint Services.

Additionally, the user still can upload a file through the out-of-the-box functionality to add and overwrite an existing file with the same name, by selecting the Overwrite existing files check box on the Upload page. To learn how to handle this situation by implementing a solution with a custom Upload page, see Preventing Record Modification but Allowing Metadata Modification by Overriding the Upload Page in Windows SharePoint Services 3.0.

As such, you should take the advice in this Visual How To as one part of a larger effort to lock down records. The individual requirements for locking down records vary widely, as do the available ways that information workers access records. Any solution for locking down records should also take into account the variety of ways that records can be accessed.

See It

Preventing Document Modification

Watch the Video

Length: 9:46 | Size: 6.55 MB | Type: WMV

Explore It