Virtual path providers
Describes how to use virtual path providers to map physical paths to virtual paths in the site.
Optimizely Content Management System (CMS) products use Virtual Path Providers (VPP) to map physical paths to virtual paths in the site. Protected modules use VPPs, so you can have a single physical location for the modules even though the virtual path on the site is configurable.
ASP.NET uses VPP to load and compile content. See ASP.NET Compilation Overview at MSDN.
When ASP.NET gets a request to supply a file based on a virtual path, it looks at the registered chain of providers and feeds the virtual path to the first provider in the chain.
The provider interprets the path to determine if it is a file that belongs in the provider's underlying file system. If so, it serves the file back to ASP.NET or calls the next provider to serve it.
A provider can accept the virtual path as valid for the file system even if the file does not exist. In this case, it returns a null reference and eventually turns up as an HTTP 404 response.
A file served from a provider must extend the abstract class of System.Web.Hosting.VirtualFile. For serving directories, the base class is System.Web.Hosting.VirtualDirectory. The core API is intended only for serving files but extends this behavior in the Optimizely products.
You must provide a virtual path (relative to a URL) when you request instances using the HostingEnvironment
. The following table shows examples of virtual paths (assuming the application root folder is http://localhost/EPiServerSample
.
Virtual path | Absolute URL |
---|---|
~/folder | http://localhost/EPiServerSample/folder |
/EPiServerSample/folder | http://localhost/EPiServerSample/folder |
/folder | http://localhost/folder |
Note
The two first examples map to the same URL. The provider implementation handles the two different virtual path requests similarly.
A virtual path cannot be relative to a host subfolder because the hosting environment cannot determine what it is relative to. A virtual path must be absolute from the host (as above) or resolved to absolute if in the syntax of ~/
. It also follows the URI syntax of an HTTP path: forward slash (/), no query string, and so on.
Use the System.Web.VirtualPathUtility
 class to convert between relative and absolute paths and to handle slashes.
There is a specific distinction between ~/myfolder
and ~/myfolder/
. The first refers to a file, the second to a directory.
Configure a Virtual Path Provider
ASP.NET does not have a configuration section in web.config
for registering providers. You can register providers only by API calls at runtime. Episerver Framework has a configuration section that lets you do this in the configuration file. The section is under the node /configuration/episerver.framework/virtualPathProviders
.
Note
The order of the configured providers matters. The provider at top are instantiated first and added to the top of the provider chain. The next provider also is added to the top of the chain, pushing the previous down one step and so on.
The following example shows the configuration from the /configuration/episerver.framework/virtualPathProviders
section:
<virtualPathProviders>
<add name="EPiServerUrlMappingVPP"
type="EPiServer.Web.Hosting.VirtualPathMappedProvider, EPiServer.Framework.AspNet"/>
<add name="EPiServerNonUnifiedVPP"
virtualPath="~/other/"
physicalPath="C:\files\other"
type="EPiServer.Web.Hosting.VirtualPathNonUnifiedProvider, EPiServer.Framework.AspNet"/>
</virtualPathProviders>
Attribute | Comments |
---|---|
name | Unique name of provider instance. |
type | Type and Assembly information for instance creation using reflection API. |
* | Implementation specific. Can be any name and arbitrary in number. |
The filesystem
path to use as the root. If the physical path has no value, then it points to a directory with virtual path provider name under basePath*
. You can also re-base a PhysicalPath
if it starts with [appDataPath]
(for example, [appDataPath]\Folder1
) which means it re-bases the value of the physical path from basePath*
.
You can find the basePath
in the Episerver framework section in the Episerver.framework
configuration file.
Note
VirtualPathMappedProvider
uses the/configuration/episerver.framework/virtualPathMappings
section to map paths.
IIS Location Settings
The following example shows how to configure the static file handler in IIS:
<location path="Upload">
<staticFile expirationTime="1.0:0:0"/>
<system.webServer>
<handlers>
<add name="wildcard"
path="*"
verb="*"
type="EPiServer.Web.StaticFileHandler, EPiServer.Framework.AspNet"/>
</handlers>
</system.webServer>
</location>
Updated 4 months ago