Configuring Virtual Path Providers

Table of Contents

• Introduction
• Configuring CMS Virtual Path Providers
• EPiServer CMS VPP Attributes
• Creating a Custom Provider Implementation
• Raising and Subscribing to Events
• 400 Bad Request Errors
• See Also

Introduction

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">
   <providers>
      <clear />
          <add 
                 showInFileManager="true"
                 virtualName="Page Files"
                 virtualPath="~/PageFiles/"
                 bypassAccessCheck="false"
                 useRouting="true"
                 name="SitePageFiles"
                 type="EPiServer.Web.Hosting.VirtualPathVersioningProvider,EPiServer"
                 indexingServiceCatalog="Web" />
          <add 
                 showInFileManager="true"
                 virtualName="Global Files"
                 virtualPath="~/Global/"
                 bypassAccessCheck="false"
                 useRouting="true"
                 name="SiteGlobalFiles"
                 type="EPiServer.Web.Hosting.VirtualPathVersioningProvider,EPiServer"
                 indexingServiceCatalog="Web" />
          <add 
                 showInFileManager="true"
                 virtualName="Documents"
                 virtualPath="~/Documents/"
                 bypassAccessCheck="false"
                 useRouting="true"
                 maxVersions="5"
                 name="SiteDocuments"
                 type="EPiServer.Web.Hosting.VirtualPathVersioningProvider,EPiServer" />
   ...  
</virtualPath>

EPiServer CMS VPP Attributes

Attributes for EPiServer CMS VPPs:

VirtualPathVersioningProvider implementation specific:

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

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)
{
     ValidateCharacters(e);
}

private void ValidateCharacters(UnifiedDirectory sender, UnifiedVirtualPathEventArgs e)
{
     ValidateCharacters(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:

• The Virtual Path Providers section in the EPiServer Framework SDK
• File System and VPPs in the EPiServer CMS SDK
• Accessing Files and Folders in the EPiServer CMS SDK
• Listening and Subscribing to File Events in the EPiServer CMS SDK