Unified File System
Total Page:16
File Type:pdf, Size:1020Kb
Unified File System Product version: 4.50 Document version: 1.0 Document creation date: 10-05-2005 Purpose The contents of this document are directly taken from the EPiServer SDK. Please see the SDK for further technical information about EPiServer. The contents of this document are protected by copyright. Contents of the document may be freely copied and distributed, either digitally or in printed format, to all EPiServer users. EPiServer® is a registered trademark of ElektroPost Stockholm AB. Other product and company names mentioned in this document may be the trademarks for their respective owners. 2 | Unified File System Table of Contents INTRODUCTION 2 CONFIGURATION 3 Configuration Essentials 3 Configuration Documentation 3 HOW TO… 4 Add New Folders 4 Add New Secure Folders 5 Secure Existing Folders 5 Move Special Page Folders to a Separate Folder 6 Secure Special Page Folders 6 Move Folders Around / Mappings 7 Add a Versioned Share 7 SEARCHING THE FILE SYSTEM 8 UNIFIED FILE SYSTEM SUPPORT FOR TEMPLATES 8 Custom Templates 8 File Listing Template 9 Search Template 9 Security Check List 9 TECHNICAL DETAILS 10 TROUBLESHOOTING 10 I Get a NullReferenceException in File Manager. 10 I Configured "/Upload" to be the Page Directory, but I Can't See it Anymore 10 Is Impersonation Required/Recommended? 10 Search Results Display Files that Users Don’t Have Access To 10 Error Message "TransmitFile.." when Downloading Secured Files 11 Introduction 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. Copyright © ElektroPost Stockholm AB - www.episerver.com Configuration | 3 Configuration 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. Configuration Essentials 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. Configuration Documentation Schema <episerver> <unifiedFileSystem> <mappings> <map fromPath="<path>" toPath="<path>" type="<mapper type>" /> </mappings> <handlers> Copyright © ElektroPost Stockholm AB - www.episerver.com 4 | Unified File System <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. How To… Add New Folders 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. Copyright © ElektroPost Stockholm AB - www.episerver.com How To… | 5 <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) Add New Secure Folders 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. Secure Existing Folders 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> Copyright © ElektroPost Stockholm AB - www.episerver.com 6 | Unified File System 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.