IIS 7.0 : Managing Virtual Directories

You can use virtual directories to publish application content that does not reside under an application’s root virtual directory. Using virtual directories is an effective way to decouple the client-facing URL structure of your application from the physical structure of its content. You’ll also need virtual directories if your application content is located in a disparate set of physical locations.

Adding a New Virtual Directory

You can create a virtual directory to provide a virtual path mapping for resources outside the Web site root directory. Virtual directories and Web applications are two distinct types of objects in IIS 7.0, but they are closely related. This poses the following considerations when creating virtual directories:

• Each Web application must have a root virtual directory (having the "/" path) that is mapped to a physical path that becomes the physical root of the application. When you create an application, you will also create its root virtual directory.

• All virtual directories must belong to an existing application. Therefore, when you create a virtual directory, you must add it to an existing application or create a new application that has the desired virtual path.

• If the virtual directory must serve as an application root for an application framework, configure enabled IIS modules, or be associated with a specific application pool, you must create an application instead.

To use IIS Manager to create a virtual directory, expand the IIS computer node in the Connections pane, navigate to the Sites node, and select the Web site in which you want to create a virtual directory. You can also expand the selected Web site node and select a child application or folder node into which you’d like to add the virtual directory. Right-click the desired node and select Add Virtual Directory.

In the resulting dialog box, you can specify the alias of the virtual directory, which will combine with the current path at which it is being added to determine the virtual path for the virtual directory. You also specify the physical path to which the virtual directory’s URL namespace will map.

Configuring Access Credentials for the Virtual Directory

By default, the Web server will access the content in the physical path of the virtual directory using the IIS worker process identity as the process identity, and additionally insure that the authenticated user associated with the request as request identity has access to the requested resource. This means that the following identities need access to the content located on the share:

• The application pool identity (Network Service by default)

• The anonymous user (IUSR by default) if anonymous authentication is allowed

• The authenticated user identity for all users that are allowed to access the content in the virtual directory, if Windows-based authentication methods including Windows Authentication or Basic Authentication are used

Note

The default virtual directory behavior is identical to the pass-through authentication mechanism used for virtual directories mapped to UNC paths in IIS 6.0.

If you would like to have the Web server use a single set of credentials that have access to the resources in the virtual directory, you can configure those credentials in the Connect As dialog box. If you specify these credentials, the Web server will always impersonate these credentials to access all content and configuration located in this virtual directory, instead of the IIS worker process identity. It will also no longer check whether the authenticated user associated with the request has access to the physical resources.

Note

If specified, IIS always uses the credentials for a virtual directory to access the content and configuration files in that virtual directory, regardless of whether the physical location of the virtual directory is local or on a remote network share. This is unlike IIS 6.0, which only uses the provided credentials if the physical location resides on a network share indicated by a UNC path.

This provides a convenient mechanism for granting access to content located on remote network shares.

Creating Virtual Directory with AppCmd

You can also create virtual directories by using the AppCmd command line tool with the following command.

appcmd add vdir /app.name:string /path:string /physicalPath:string /userName:string
/password:string /logonMethod:enum /allowSubDirConfig:bool

The parameters for this command are listed in Table 1.

Table 1. Syntax for AppCmd to Add a Virtual Directory

Parameter	Description
app.name	The path of the parent application to which the virtual directory is added. This parameter is required.
path	The virtual path for the virtual directory. This is relative to the parent application’s virtual path. This parameter is required.
physicalPath	The physical path of the virtual directory. This parameter is required.
userName	The user name for virtual directory content access. If you do not specify this during virtual directory creation, it defaults to using pass-through authentication.
password	The password to use with the user name to access the virtual directory content.
logonMethod	The logon method used to create the logon token for the virtual directory credentials. Can be "Interactive", "Batch", "Network", or "ClearText". The default is "ClearText". For more information on these types, see "LogonUser Function" at http://msdn2.microsoft.com/en-us/library/aa378184.aspx.
allowSubDirConfig	Boolean that specifies whether or not the Web server will look for configuration files located in the subdirectories of this virtual directory. Setting this to false can improve performance on servers with very large numbers of web.config files, but doing so prevents IIS configuration from being read in subdirectories. Defaults to true.

The following example adds a new virtual directory named images within the Contoso Corp. Web site.

appcmd add vdir /app.name:"Contoso Corp/" /path:/images
    /physicalPath:g:\images

The command output shows that IIS creates a VDIR object that belongs to the Contoso Corp. root application. The virtual directory mapping forms the URL http://www.contoso.com/images, which links to image files residing in the physical folder g:\images.

VDIR object "Contoso Corp/images" added

Configuring Virtual Directories

When you are adding or changing a virtual directory, it is important to understand its underlying relationship with the Web application. For example, if you want to just enable references to an image folder on a remote share, the virtual directory does not need to be an application by itself. Instead, it can reside as part of the Web site’s root application.

To make changes to an existing virtual directory, select the virtual directory you want to edit and then click Basic Settings in the Actions pane. The result is shown in Figure 1. To delete a virtual directory, select the virtual directory and then click Remove in the Actions pane.

Warning

Removing a virtual directory does not delete the contents of the physical file system’s mapped path. It removes only the mapping relationship between the URL alias and physical folder.

Also note that it is not possible to remove a Web site’s root virtual directory or an application’s root virtual directory.

Figure 1. Configuring a virtual directory by using IIS Manager.

To set configuration settings on an existing virtual directory, use the following command.

appcmd set vdir VirtualDirectoryName /physicalPath: string
    /userName: string /password: string /logonMethod:enum /allowSubDirConfig:bool

To delete an existing virtual directory, use the following syntax.

appcmd delete vdir VirtualDirectoryName

The parameters for this command are listed in Table 2.

Table 2. Syntax for AppCmd to Configure a Virtual Directory

Parameter	Description
VirtualDirectoryName	The full virtual path of the virtual directory that uniquely identifies it. This is required to edit or delete an existing virtual directory.
physicalPath	The physical path of the virtual mapping.
userName	The user name for virtual directory content access. If this is not specified during virtual directory creation, it defaults to using pass-through authentication.
password	The password to use with the user name to access the virtual directory content.
logonMethod	The logon method used to create the logon token for the virtual directory credentials. Can be "Interactive", "Batch", "Network", or "ClearText". The default is "ClearText". For more information on these types, see "LogonUser Function" at http://msdn2.microsoft.com/en-us/library/aa378184.aspx.
allowSubDirConfig	Boolean that specifies whether or not the Web server will look for configuration files located in the subdirectories of this virtual directory. Setting this to false can improve performance on servers with very large numbers of web.config files, but doing so prevents IIS configuration from being read in subdirectories. Defaults to true.

To delete an existing virtual directory, you must specify the full virtual path of the virtual directory, as in this example.

appcmd delete vdir "Contoso Corp/oldimages"

Imagine that Contoso Corp.’s legal department has published a new set of corporate images on its file share server. To change the virtual directory mapping and specify a custom user account named "Webuser" to access the remote share, use the following command.

appcmd set vdir "Contoso Corp/images"
    /physicalPath:\\ContosoLegal\pub\images\ /userName:"Webuser"
    /password:"passw@rd1"

Along with site information, virtual directory configuration is defined in a <virtualDirectory> element within a <site> element in the applicationHost.config file. The following shows the configuration that results from executing the previous command.

    <site name="Contoso Corp" id="1">
        <application path="/">
            <virtualDirectory path="/" physicalPath="d:\contoso" />
            <virtualDirectory path="/images"
                physicalPath="\\ContosoLegal\pub\images" userName:"Webuser"
                password=
"[enc:AesProvider:oGSyoej3RKswi3gsrYarpbMQrx0rVIY6nFHkPmjQAhE=:enc]"/>
        </application>
        <application path="/payment" applicationPool="MyAppPool">
            <virtualDirectory path="/" physicalPath="d:\KDbank" />
        </application>
        ...
     </site>

Note that, by default, the user credential for a virtual directory is stored inside the applicationHost.config file and is encrypted using the Microsoft Advanced Encryption Standard (AES) cryptographic provider. The application path "/" indicates the root application of the Web site and that the virtual directory "/images" belongs to the root application.

Searching Virtual Directories

When managing many Web sites with hundreds of virtual directories and applications, you sometimes need to locate or find a specific virtual directory or a group of virtual directories belonging to an application or Web site. IIS 6.0 provides limited tools and UI features to locate specific virtual directories. But in IIS 7.0, IIS Manager enables you to quickly find and display a list of virtual directories defined in the Web server.

To use IIS Manager to find and list virtual directories, expand the IIS computer node in the Connections pane, navigate to the Sites node, and select the Web site for which you want to list virtual directories. In the Actions pane, click View Virtual Directories. The result is shown in Figure 2.

If the virtual directory itself is not an application and belongs to the Web site root application, it is displayed as a root application in the Application Path column. The Identity column shows the request user account will be used as a request identity when accessing the virtual directory’s content.

Note

If the identity field is not populated, pass-through authentication is being used for content access. For example, in anonymous authentication, the default IUSR account is the request identity.

Figure 2. Viewing virtual directories by using IIS Manager.

Use the following AppCmd command to display mapping details of virtual directories.

appcmd list vdir VirtualDirectoryPath /app.name:string

The parameters for this command are listed in Table 3.

Table 3. Syntax for AppCmd to Search a Virtual Directory

Parameter	Description
VirtualDirectoryPath	The string represents the full virtual path of the virtual directory. If a value is omitted, the query displays all virtual directories of the Web server. This string can also be a URL, which will make the URL be resolved to the closest parent virtual directory.
app.name	The application virtual path. If specified, all of the virtual directories belonging to the application will be returned.

The following command queries the "/images" virtual directory configuration detail.

appcmd list vdir "Contoso Corp/images"

As shown in the resulting output, the virtual directory is mapped to a UNC share.

VDIR "Contoso Corp/images" (physicalPath:\\ContosoLegal\pub\images)

To list all of the Web server’s virtual directories, enter the following command.

appcmd list vdir

The resulting output lists all virtual directories, as shown in the following example.

VDIR "Contoso Corp/" (physicalPath:d:\contoso)
VDIR "Contoso Corp/images" (physicalPath:\\ContosoLegal\pub\images)
VDIR "Contoso Corp/payment" (physicalPath:d:\KDbank)
VDIR "Fabrikam HR/" (physicalPath:d:\FabrikamHR)

You can also specify filtering expressions based on any virtual directory configuration property, such as path or user name, to list all of the virtual directories that satisfy these filter expressions. Additionally, you can search for virtual directories that belong to a specific site.