Unified File System
|
Product version: |
4.61 |
|
Document version: |
1.0 |
|
Document creation date: |
07-06-2006 |
|
Document last saved: |
17-11-2006 |
Purpose
The contents of this document are directly taken from the EPiServer SDK. Please see the SDK for further technical information about EPiServer.
Table of Contents
Introduction
Configuration
- Issue Concerning EPiServer 4.60 / 4.61
- Configuration Essentials
- Configuration Documentation
How To…
- Add New Folders
- Add New Secure Folders
- Secure Existing Folders
- Move Special Page Folders to a Separate Folder
- Secure Special Page Folders
- Move Folders Around / Mappings
- Add a Versioned Share
Searching the File System
- IFilters
Unified File System Support for Templates
- Custom Templates
- File Listing Template
- Search Template
- Security Check List
Technical Details
Troubleshooting
- I Get a NullReferenceException in File Manager
- I Configured "/Upload" to be the Page Directory, but I Can't See it Anymore
- Is Impersonation Required/Recommended?
- Search Results Display Files that Users Don’t Have Access To
- Error Message "TransmitFile.." when Downloading Secured Files
The Unified File System enables the addition of a virtual share, giving access to files that are not exposed by Internet Information Server (IIS). (The virtual shares are handled by EPiServer and should not be confused with virtual folders in IIS.)
Files do not have to be located in a traditional file system; they can be stored in any source that can represent their data in a structured way. It is possible to customize the file system implementation to work with, for example Microsoft SharePoint, or a company file system with complete integration with EPiServer.
All folders, and therefore files, can be protected using EPiServer access permission security. Correct access permission is required to be able to view or download a file. Files corresponding to specific pages are protected by the same access permissions as the page. This feature must be activated as the original files need to be moved to a protected location so that EPiServer can handle all access.
If you use file access in templates to a protected folder, you must rewrite your solution to use the classes in the EPiServer.FileSystem namespace.
EPsUploadDir
Without any configuration, a handler will by default be set up to match whatever configuration made to the EPsUploadDir setting under the appSettings element in web.config.
After you add file system configuration, the EPsUploadDir setting will only act as the default folder opened in any graphical user interface in EPiServer. It will also act as the default folder for special page folders until you specify pageDirectory=”True” on a handler.
From EPiServer 4.60, the following registration in web.config is required for virtual unified file system handlers, i.e. those handled by EPiServer. Registration is done automatically at installation and upgrade. This module is responsible, for example, for making sure that "Documents/MyDocument.doc" is mapped to a file in versioned file system. It should be placed after SpiderSupport, which was previously reponsible for this functionality.
<httpModules>
<add name="SpiderSupport" type="EPiServer.Util.SpiderSupport, EPiServer" />
<add name="UnifiedFileSystem" type="EPiServer.FileSystem.UnifiedFileSystemModule, EPiServer" />
By default, EPiServer has no configuration information about the file system setup in web.config. It will, by default, configure a backward-compatible setup, based on the value in EPsUploadDir in web.config. Before configuring the Unified File System, make sure that the following information exists inside the root configuration element of your web.config file.
1. Add the configuration setting to let ASP.NET know you have your own section.
<configSections>
<sectionGroup name="episerver">
<section name="unifiedFileSystem"
allowDefinition="MachineToApplication"
allowLocation="false"
type="EPiServer.FileSystem.Handler.ConfigurationHandler,EPiServer" />
</sectionGroup>
</configSections>
It is important that the configSections tag is located at the top of web.config. This does not apply to the episerver section.
2. Add the configuration section for the default upload folder.
<episerver>
<unifiedFileSystem>
<handlers>
<handler
pageDirectory="False"
virtualName="upload"
virtualShare="False"
type="EPiServer.FileSystem.Handler.NativeFileSystem,EPiServer" />
</handlers>
</unifiedFileSystem>
</episerver>
3. When you save your changes, your installation should behave as before, as you have not yet changed any behavior.
Note The virtualName setting above can, of course, be set to another location in your installation, just check the value of EPsUploadDir.
Schema
<episerver>
<unifiedFileSystem>
<mappings>
<map
fromPath="<path>"
toPath="<path>"
type="<mapper type>" />
</mappings>
<handlers>
<handler
pageDirectory="<True|False>"
virtualName="<name>"
virtualShare="<True|False>"
type="<Class,Assembly>">
<customSettings <custom key>="<custom value>" />
</handler>
</handlers>
</unifiedFileSystem>
</episerver>
Element: map
|
Attribute |
Values |
Description |
|
fromPath |
Relative path |
Used to redirect all requests from this base path |
|
toPath |
Relative path |
Used to redirect all requests to this base path |
|
type |
Class,Assembly |
The class that will handle incoming mapping requests |
Element: handler
|
Attribute |
Values |
Description |
|
pageDirectory |
True or False |
Configures a folder to be used only as the special page folder container |
|
virtualName |
A name of the folder |
The root name of the folder in a site, must match the actual folder name when virtualShare is set to False. Otherwise it can be any name that does not match a existing folder name. |
|
virtualShare |
True or False |
If EPiServer should activate security and if files should be delivered through EPiServer and not IIS. |
|
Type |
Class,Assembly |
The type of file system that will handle this folder.
NativeFileSystem - This types stores and accesses files using a standard Windows folder structure. It has great performance and is simple to set up as you can map it to any existing structure. Searching is handled by Microsoft Indexing Service.
VersioningFileSystem - This type stores structure and versioning information in the EPiServer database and has more features such as check in/check out and version history. The actual files are stored as files on the disk, but contain no structural information. Searching is handled by the EPiServer Indexing Service. |
It is possible for editors to be able to access the images folder, which defines many images used in the Web site design.
- Add a new handler section which points out the local images folder.
<handler
pageDirectory="False"
virtualName="images"
virtualShare="False"
type="EPiServer.FileSystem.Handler.NativeFileSystem,EPiServer" />
The handler section is identical, but the virtualName is changed to images, which is the name of our folder. When you open the file manager in Edit mode, you should have two folders pointing to both the images folder and the upload folder.
Note It is important that you set the correct Windows ACL on folders exposed to editors to make sure they have enough permission to edit files and folders. On Windows 2000/XP, you should give the local ASPNET account Change permissions on the folder. On Windows Server 2003, use the IIS_WPG group or the actual process account configured in Internet Information Services (IIS)
The previous example adds a handler for folders that already exist on the Web site. In reality we make sure EPiServer can display them in Edit mode. When a user downloads an image from the images folder in the previous example, it will be served the Internet Information Services, just as we are used to.
To add a folder that will be secured by EPiServer, follow the instructions below.
1. Make sure the folder cannot be accessed by IIS. This would short-circuit the security check.
2. Add a new folder to "c:\inetpub" and call it SecureFiles.
3. Add a handler configuration section.
<handler
pageDirectory="False"
virtualName="Secure"
virtualShare="True"
type="EPiServer.FileSystem.Handler.NativeFileSystem,EPiServer">
<customSettings PhysicalPath="c:\inetpub\SecureFiles" />
</handler>
When you open the file manager in Edit mode, you will not see the new folder, because no one has been granted access yet. Go to Admin mode and click File management under the Tools section. When you select the Secure folder, you will see a new button, Security. Add the appropriate access levels.
The main difference from the previous configuration is that virtualShare is set to True. This tells EPiServer that files accessed in the SecureFiles folder must pass security checks, both when accessed from Edit mode and when downloading files.
Files that don’t get exposed by Internet Information Services can be downloaded anyway, because the technology is the same as that for simple address to pages in EPiServer. We add a custom Web form to handle traffic that results in "404 File Not Found from IIS". So if you access http://localhost/Secure/MyFile.doc, it will be delivered to the user by EPiServer instead and the user will not be able to see any difference. This makes it easy to take an existing folder and move it to a secure location without changing any links.
Securing an existing folder is not very different from adding secure folders. We assume that we have an Extranet folder on our Web site that contains documents we wish to secure.
1. Set up the configuration section in web.config.
<handler
pageDirectory="False"
virtualName="Extranet"
virtualShare="True"
type="EPiServer.FileSystem.Handler.NativeFileSystem,EPiServer">
<customSettings PhysicalPath="c:\inetpub\Extranet" />
</handler>
2. Take the existing Extranet folder and move it from "c:\inetpub\EPiServer\Extranet" to "c:\inetpub\Extranet". This means that we take it out of Web exposure as far as IIS is concerned.
3. Go to Admin mode and click File management under the Tools section. When you select the Extranet folder, you will get a new button, Security. Add the appropriate access levels.
You should now be able to access the files, but every file is checked for security by EPiServer, as defined in Admin mode.
EPiServer has a concept of special page folders, where every page can have its own folder with files that only apply to this specific page. These folders have previously been stored in the same upload folder as the rest of the files. For example "/upload/33/MyFile.doc", where ”33” is a folder created specifically for a page in EPiServer and filtered out of the other views of the upload folder.
Moving these folders to another location is very simple and the pageDirectory attribute is the key to success.
1. Create a new folder called pages on your Web site and add a configuration section for this folder.
<handler
pageDirectory="True"
virtualName="pages"
virtualShare="False"
type="EPiServer.FileSystem.Handler.NativeFileSystem,EPiServer" />
2. If you browse the file manager in Edit mode, you will not see the pages folder, but if you click Current page folder, you will be linked to a special folder for this page that resides in the pages folder.
Note If you are adding this configuration to an existing site, you have to move the actual numeric folders from the upload folder to the pages folder.
Sometimes Web sites have many different access levels or you may need to make sure that documents in the special page folder do not become accessible before the page. As seen in other configuration examples, we can secure page folders in the same way.
1. Move the folder created in Move Special Page Folders to a Separate Folder, or create a new one at "c:\inetpub\pages".
2. Change the page configuration (you cannot have more than one page folder of course).
<handler
pageDirectory="True"
virtualName="pages"
virtualShare="True"
type="EPiServer.FileSystem.Handler.NativeFileSystem,EPiServer">
<customSettings PhysicalPath="c:\inetpub\Pages" />
</handler>
You cannot browse page directories; you will only be able to access them directly in the file manager using the Current page folder.
Note If you access files in a page folder, they will receive the same security checks as a page would. For example, a page where the start publish date is forward in time will require Edit access to files in this folder, just as for the page itself.
When presented with this amount of configuration settings, you will probably find yourself in a situation where you need to move a folder from one location to another.
The functionality presented below was built to target existing EPiServer sites that want to enable security on some folders on their site. If you move existing secured folders, take the security notices into consideration.
For example, if you have files in "/upload/Documents" that you wish to move to the previously created folder Secure, all existing links would point to the wrong location. One solution is to find and change all links, so that they point to the new location. Another way is to use the mapping features in the file system, for example:
<mappings>
<map
fromPath="/upload/documents"
toPath="/Secure"
type="EPiServer.FileSystem.Mapping.SimpleMapping,EPiServer" />
</mappings>
This configuration will ensure that access to "/upload/documents/MyFile.doc" will be redirected to "/Secure/MyFile.doc". Mappings only work when the toPath is a virtualShare. Otherwise you should use IIS to redirect requests.
A more complex operation would be to only move the special page folders from the upload folder to the pages folder without changing the existing links. The example configuration requires that you have set up a secured pages folder.
<mappings>
<map
fromPath="/upload"
toPath="/pages"
type="EPiServer.FileSystem.Mapping.PageDirectoryMapping,EPiServer" />
</mappings>
As you can see, the PageDirectoryMapping type is used instead. The mapper will only redirect requests that start with "/upload", followed by one or more digits. For example, "/upload/45/Myfile.doc" will be redirected to "/pages/45/MyFile.doc".
File version control is available from EPiServer 4.50. The type VersioningFileSystem stores structure and versioning information in the EPiServer database and has more features such as check in/check out and version history. The actual files are stored as files on the disk, but contain no structural information. Searching is handled by the EPiServer Indexing Service.
To add a versioned share to the Unified File System, follow the instructions below.
1. Add a new folder to "c:\inetpub" that will contain the files to be available for version control.
2. Add a new handler section that points out the directory to be shared - c:\inetpub\Documents in the example below.
<handler
pageDirectory="False"
virtualName="Documents"
virtualShare="True"
type="EPiServer.FileSystem.Handler.VersioningFileSystem,EPiServer">
<customSettings
FilePath="c:\inetpub\Documents"
MaxVersions="10" />
</handler>
3. Open EPiServer Manager and go to the Capabilities section for the Web site in question. Click Enable in the Indexing section. If indexing is already enabled, you must disable indexing and then enable it again.
Note EPiServer Indexing stores the connection string of the site in c:\Program\EPiServer.IndexingService\EPiServer.IndexingService.exe.config. You must manually edit this file if you change the connection string of your site or the path to the versioned files. The EPiServer Indexing Service is a global service and can handle multiple configurations on the same machine. It will poll the databases for changes and add index information to the file path.
In the file manager in Edit mode, you have an option to search in the file system. This feature uses Microsoft Indexing Service. By default, this feature will search in the SYSTEM catalog, which by default in Windows allows search in all local drives. Sometimes this catalog is not available, so you have to map a new catalog. This is done by the following configuration in EPiServer:
<handler
pageDirectory="False"
virtualName="Extranet"
virtualShare="True"
type="EPiServer.FileSystem.Handler.NativeFileSystem,EPiServer">
<customSettings
IndexCatalog="ExtranetCatalog"
PhysicalPath="c:\inetpub\Extranet" />
</handler>
The catalog is created in Indexing Service and called ExtranetCatalog. It maps to a directory either identical to "c:\inetpub\Extranet" or any folder containing the Extranet folder. The file manager will automatically set scope for the search to the correct path, so the path of the folder does not have to match the path of the catalog. Remember that if you have more than one handler, you must configure IndexCatalog for all of them, for example by using the same Index Server catalog.
This will make sure you can search for files in Edit mode, but if you want the search template in EPiServer to search the same way, you have to make some changes to this template.
Important! If you are using a versioned share (see Add a Versioned Share) no Index Server configuration is needed as this handler has built in search capabilities.
To search content from within different file formats, Microsoft Indexing Service needs to have the appropriate IFilters installed. There are filters available for most common formats such as .pdf, .zip and Microsoft Office files (and many more). If the correlating filter for a certain file extension is not installed, the contents of those files will not be indexed end therefore not searchable. If you experience a lack of hits from a certain file type when searching your site, a missing IFilter could be the cause.
For a desciption of some of the more common IFilters, please visit Microsofts web site:
›› http://msdn2.microsoft.com/en-gb/library/ms692582.aspx
If you have other templates in your site that programmatically access files using Microsoft.NET API to any of the directories that will be secured, you must change this, so that they use the Unified File System API instead.
The Unified File System API is very similar to the Microsoft.NET API so there should not be any problems migrating code. Code that only accesses non-secured directories does not need to be modified. The recommendation is to always use our API as it is specifically designed for the Web and EPiServer.
//Example using Microsoft.NET API
FileInfo file = new FileInfo( Server.MapPath("~/securefolder") );
Response.Write(file.Length.ToString());
//Example using Unified File System API
UnifiedFile file = UnifiedFileSystem.GetFile("/securefolder");
Response.Write(file.Length.ToString());
The file listing template does not support Unified File System in versions before EPiServer 4.40. It was built to support Windows files and folders and must remain backward-compatible. The core of the file listing template is the FileTree control that must be changed to UnifiedFileTree, which has very similar syntax, but with some minor changes. The UnifiedFileTree only supports directories defined in Unified File System and should be considered for other reasons such as security concerns, as it will not let an editor set the path to a directory not defined in Unified File System.
You need to recompile the project for this change. Please see "Templates/Units/FileListing.ascx" in the EPiServer templates pack for example code.
If you want the search template in EPiServer to search through Unified File System to make sure the results reflect the user access rights, you must make a small code change.
This is the default code for the search template in "Templates/Units/Search.ascx". The settings MainScope and MainCatalog must be removed to transfer control to Unified File System:
<episerver:PageSearch
Runat="server"
ID="SearchResults"
SearchQuery='<%# SearchQuery.Text %>'
SearchFiles='<%# SearchFiles.Checked %>'
OnlyWholeWords='<%# OnlyWholeWords.Checked %>'
MainScope='<%# CurrentPage["MainScope"] %>'
MainCatalog='<%# CurrentPage["MainCatalog"]