Area: Optimizely CMS
ARCHIVED This content is retired and no longer maintained. See the latest version here.

Recommended reading 

Table of Contents


EPiServer CMS can use Virtual Path Providers (VPP) to serve static files to visitors. The reason for using VPPs is to allow EPiServer CMS programmatic control of what files to send as well as additional security checks. VPP is the mechanism that ASP.NET uses to load and compile content. For a brief introduction, see ASP.NET Compilation Overview at MSDN. In the following the VPP concept and configuration are described in more detail.

Configuring the CMS Virtual Path Providers

In the EPiServer CMS File Manager, it is possible to define new starting points. In a standard installation of EPiServer CMS, a few default starting points, Global Files and Documents, and the Page Files will be set up. During installation a VPP directory is specified and this is the physical place in which the standard folders will be saved.

For page folders and the files connected to a page is stored in a special directory configured in web.config and is the only provider which must exist. The providers have a unique name in configuration and the page files provider name is referred to by the attribute pageFolderVirtualPathProvider of a siteSettings node. The provider for page files can be replaced with any custom provider implementation as long as it is built upon the EPiServer extension of the VPP API.

The configuration of starting points is done in episerverframework.config.

<virtualPath customFileSummary="~/FileSummary.config">
      <clear />
                 virtualName="Page Files"
                 indexingServiceCatalog="Web" />
                 virtualName="Global Files"
                 indexingServiceCatalog="Web" />
                 type="EPiServer.Web.Hosting.VirtualPathVersioningProvider,EPiServer" />

EPiServer CMS VPP Attributes

Attributes for EPiServer CMS VPPs:

Attribute Comments
name Unique name of provider instance.
type Type and Assembly information for instance creation using reflection API.
customFileSummary Definition of XForm holding custom META data for all file systems.

This provider supports the File Manager user interface. Must implement the EPiServer VPP extension interfaces. You have the following options:

  • True means that the starting point will be shown in the File Manager.
  • False means that the starting point will not be shown in the File Manager.
virtualPath Virtual Path to file system Root.
physicalPath The filesystem path to use as the root. By default Physical path has no value which points to a directory with virtual path provider name under base path. You can find the basePath in the episerver framewotk section in the episerver framework config file.
virtualName The (root catalog) name that will be shown in the File Manager. Displays in File Manager user interface instead of the virtual path root.

If access rights will be checked before supplying a file or directory. You have the following options:

  • True means that authorization will not be checked before an editor creates folders and uploads documents.
  • False means that authorization will always be checked.

If files should be routed to the Static Filer Handler. You have the following options:

  • True means that files under the specified virtualPath will automatically be routed to the the built-in handler, no further action required.
  • False means that you need to manually configure an ASP.NET handler to serve files from this location, such as EPiServer.Web.StaticFileHandler. See “Virtual Path Providers” in EPiServer Framework SDK for more details.
* Implementation specific. Can be any name and arbitrary in number.

VirtualPathVersioningProvider implementation specific:

Attribute Comments
maxVersions Numeric number of max versions a file can have.

Creating a Custom Provider Implementation

To create a custom implementation with user interface support your provider needs to be derived from VirtualPathUnifiedProvider. This gives you some utility methods and validation on required configuration parameters as well as access to them. The class is not intended to be used as a provider for delivering files and therefore abstract. It is mainly used to ease implementation of custom providers.

A VPP can be created without support in the File Manager user interface. Such a provider does not need to extend implementations from the EPiServer extended classes of the core API. Those classes can be derived directly from VirtualPathProvider, VirtualFile and VirtualDirectory. An example of this is the EPiServer.Web.Hosting.VirtualPathMappedProvider.

The other classes which wraps up a complete provider implementation are handlers for Directories, Files, Summary and Versions (if you intend for your file system to support it). The following base classes are available be derived from:

  • UnifiedFile
  • UnifiedDirectory
  • UnifiedSummary
  • UnifiedVersion
Note the difference from earlier EPiServer versions that the Unified classes are base classes, not top level abstraction classes. The abstraction layer is provided by ASP.NET and the implementation by you. Note again that the Unified classes are only there to ease your implementation if you want your provider to be supported in the edit and admin user interface.

If you want your provider to act for other purposes you should use the core Virtual Path Provider API. You can still use the EPiServer config section to register your provider.

Raising and Subscribing to Events

The UnifiedFile and UnifiedDirectory classes provide handlers for events. They can be raised and subscribed to for most of the events mapped to user interface actions. For example rename, add and delete handlers. They all have pre and post mechanisms, which means an On[eventName]ing handler for an action about to take place and an On[eventName]ed after which the action is fulfilled.

A subscriber (for example a workflow) can, if it for some reason disapproves with the action to be executed, set the Cancel property of the event to true and the action will be aborted. It is up to the implementing provider to raise events. The Unified classes define a set of standard events but a provider can define its own events and raise those for certain actions or call the standard set, or even both.
The implementation in VersioningFile for delete action is shown below.

Both directory and file events work on a generic event class UnifiedVirtualPathEventArgs. The first argument is the new virtual path the file will accept for the action. In delete this has no purpose and is set to null. In other actions it might be of importance, for instance for rename, copy and move.

OnDeleting raises the action to listeners which have the option to cancel the action. In such case an exception is thrown which is handled in the user interface. If a custom implementation throws any other exception this is not handled in the user interface. Only exceptions of type InvalidOperationException and UnauthorizedAccessException are supported.

If no cancellation is made the post event is raised after the action is complete. As mentioned before, raising events is an option you can use in your own provider implementation.

When the virtual path handler gets initialized, event listeners for adding file, adding directory, moving file, and moving directory gets created. Those listeners will check for illegal characters and cancel the operation if the file or directory contains illegal characters. The validation is done using regular expression, and the default expression looks like "%|&|\+|/COM[0-9]([/\.]|$)|/LPT[0-9]([/\.]|$)|/PRN([/\.]|$)|/CLOCK\$([/\.]|$)|/AUX([/\.]|$)|/NUL([/\.]|$)|/CON([/\.]|$)|/.+\.$|\.\.". This value can be overwritten by setting the attribute IllegalCharactersRegEx on the virtualPath element in the configuration file.

To add validation to the default validation, remove the event listeners created by EPiServer, and create new event listeners. In the event listeners, get the property with illegal characters and add validation to the string. Then use the validation string in a regular expression match.

UnifiedDirectory.UnifiedFileAdding -= VirtualPathHandler.Instance.ValidateCharacters;
UnifiedDirectory.UnifiedDirectoryMoving -= VirtualPathHandler.Instance.ValidateCharacters;
UnifiedDirectory.UnifiedDirectoryAdding -= VirtualPathHandler.Instance.ValidateCharacters;
UnifiedFile.UnifiedFileMoving -= VirtualPathHandler.Instance.ValidateCharacters;


UnifiedDirectory.UnifiedFileAdding += new UnifiedDirectoryEventHandler(ValidateCharacters);
UnifiedDirectory.UnifiedDirectoryMoving += new UnifiedDirectoryEventHandler(ValidateCharacters);
UnifiedDirectory.UnifiedDirectoryAdding += new UnifiedDirectoryEventHandler(ValidateCharacters);
UnifiedFile.UnifiedFileMoving += new UnifiedFileEventHandler(ValidateCharacters);


private void ValidateCharacters(UnifiedFile sender, UnifiedVirtualPathEventArgs e)

private void ValidateCharacters(UnifiedDirectory sender, UnifiedVirtualPathEventArgs e)

private void ValidateCharacters(UnifiedVirtualPathEventArgs e)
     string regEx = EPiServerSection.Instance.VirtualPathSettings.IllegalCharactersRegEx;
     regEx += @"|\.jpg$";

     Regex illegalCharRegex = new Regex(regEx, RegexOptions.Compiled | RegexOptions.IgnoreCase);
     if (illegalCharRegex.IsMatch(e.NewVirtualPath))
          e.Cancel = true;
          e.Reason = String.Format(System.Globalization.CultureInfo.InvariantCulture, LanguageManager.Instance.Translate("/filemanager/illegalname"), EPiServerSection.Instance.VirtualPathSettings.IllegalCharactersDisplayString);

400 Bad Request Errors

When a file contains dots after each other (test.jpg), ASP.NET will by default throw an exception. In EPiServer CMS, this is illegal by default but can be overridden as described earlier. If the validation is overridden, and you want “double dots” to be legal, read the article Microsoft Support EN-US;826437.

See Also

More information on file management and Virtual Path Providers in EPiServer can be found in the following sections:

Do you find this information helpful? Please log in to provide feedback.

Last updated: Mar 25, 2013

Recommended reading