Programmatically Administering the Home Directory Property Sheet

As shown in Figure 9.5, the configuration of a home directory path is vital to the establishment of a new Web site.

Using the properties in this section, you can determine the origin of content when accessing a resource, determine permissions and default behavior of the files and directories in the root virtual directory, and define the configuration of a Web application.

Figure 9.5. Default Web Site Properties Configuration dialog box ”Home Directory tab.

graphics/09fig05.gif

To begin, you must determine from where the content should be derived. In IIS 4.0, you have three options:

A directory located on this computer
A share located on another computer
A redirection to a URL

Local Home Directory

To access content stored on the local machine, you need only define the Path property for the Root virtual directory. To do this, simply bind the Root virtual directory for the site and assign a new value to the Path property.

Querying the Local Path Property for a Site's Root Virtual Directory Using Visual Basic

To find the current path assigned to the bound Web site, use the following Visual Basic code:

 Dim VirtualDirectory As IADs Dim ServerName As String Dim Index As Long Dim RetVal as String ServerName = "IIS_Server_Name" Index = Site_Index_Value Set VirtualDirectory = GetObject("IIS://" & ServerName & "/W3SVC/" & Index & "/ROOT") RetVal = VirtualDirectory.Path Debug.Print RetVal

Modifying the Local Path Property for a Site's Root Virtual Directory Using Visual Basic

Use the following Visual Basic code to modify the path to the Root virtual directory for the default Web site:

 Dim VirtualDirectory As IADs Dim ServerName As String Dim Index As Long Dim NewVirtualDirPath As String ServerName = "IIS_Server_Name" Index = Site_Index_Value NewVirtualDirPath = "New_Path_for_Site" Set VirtualDirectory = GetObject("IIS://" & ServerName & "/W3SVC/" & Index & "/ROOT") VirtualDirectory.Path = NewVirtualDirPath VirtualDirectory.SetInfo

Remote Home Directory

As shown in Figure 9.6, IIS allows you to establish a connection to a remote directory to serve the files for a particular site.

Figure 9.6. Default Web Site Properties dialog box ”Home Directory tab (remote path).

graphics/09fig06.gif

To access content stored on a remote machine, assign the site's Root virtual directory Path property to a share name . Use the Universal Naming Convention (UNC) path for the resource (\\ server \ share ) and define the username and password to make the connection using the UNCUserName and UNCPassword properties.

Querying the Remote Path Property and UNC Connection Information for a Site's Root Virtual Directory Using Visual Basic

Using the Path , UNCUserName , and UNCPassword properties, you can find the configuration settings for a remote home directory. Use the following Visual Basic code as a guide:

 Dim VirtualDirectory As IADs Dim ServerName As String Dim Index As Long Dim RetVal As String ServerName = "IIS_Server_Name" Index = Site_Index_Value Set VirtualDirectory = GetObject("IIS://" & ServerName & "/W3SVC/" & Index & "/ROOT") Debug.Print VirtualDirectory.Path Debug.Print VirtualDirectory.UNCUserName Debug.Print VirtualDirectory.UNCPassword

Warning

Like all password- related information stored in the IIS Metabase, the password can be viewed in clear text using ADSI. When designing your site, you should take into consideration the fact that anyone with the proper knowledge, tools, and access can compromise this account .

Under no circumstances should an account with any significant level of privileges be used for the IUSR, IWAM, or UNC credentials due to this security "feature."

Modifying the Remote Path Property for a Site's Root Virtual Directory Using Visual Basic

To create a new remote home directory for a site, use the following Visual Basic code:

 Dim VirtualDirectory As IADs Dim ServerName As String Dim Index As Long Dim NewVirtualDirPath As String Dim NewVirtualDirUser As String Dim NewVirtualDirPassword As String ServerName = "IIS_Server_Name" Index = Site_Index_Value NewVirtualDirPath = "New_Path_for_Site" NewVirtualDirUser = "UNC_Credentials_Used_To_Establish_Connection" NewVirtualDirPassword = "UNC_Credentials_Used_To_Establish_Connection" Set VirtualDirectory = GetObject("IIS://" & ServerName & "/W3SVC/" & Index & "/ROOT") VirtualDirectory.Path = NewVirtualDirPath VirtualDirectory.UNCUsername = NewVirtualDirUser VirtualDirectory.UNCPassword = NewVirtualDirPassword VirtualDirectory.SetInfo

Access Permissions and Content Control for Local and Remote Home Directories

For both the local and remote home directory site configurations, you can assign permissions, enable/disable logging, enable/disable directory browsing, allow indexing of the directory, and enable/disable FrontPage user access.

You can perform these actions by binding to the Root virtual directory and setting the appropriate Boolean value for each of the following properties:

Property	Behavior
`AccessRead`	Enables or disables the ability to read files in the directory.
`AccessWrite`	Enables or disables the ability to write files in the directory.
`DontLog`	Enables ordisables logging of the bound directory.
`EnableDirBrowsing`	Enables or disables the ability to browse the virtual directory from the client.
`ContentIndexed`	Enables or disables indexing of the bound virtual directory.
`FrontPageWeb`	Enables the FrontPage manager to create the required FrontPage files. If set to disabled, the FrontPage Web support files are deleted.

Managing Access Permissions and Content Control Properties Using Visual Basic

The following Visual Basic code shows the manipulation of all Access Permissions and Content Control properties for IIS 4.0:

 Dim VirtualDirectory As IADs Dim ServerName As String Dim Index As Long ServerName = "IIS_Server_Name" Index = Site_Index_Value Set VirtualDirectory = GetObject("IIS://" & ServerName & "/W3SVC/" & Index & "/ROOT") Debug.Print "Read:" & vbTab & vbTab & vbTab & VirtualDirectory.AccessRead Debug.Print "Write:" & vbTab & vbTab & vbTab & VirtualDirectory.AccessWrite Debug.Print "Logging Disabled: " & vbTab & VirtualDirectory.DontLog Debug.Print "Dir Browsing: " & vbTab & vbTab & VirtualDirectory.EnableDirBrowsing Debug.Print "Index Content: " & vbTab & VirtualDirectory.ContentIndexed Set VirtualDirectory = GetObject("IIS://" & ServerName & "/W3SVC/" & Index) Debug.Print "FrontPage Web:" & vbTab & vbTab & VirtualDirectory.FrontPageWeb

Warning

Notice that the FrontPageWeb property is defined only at the site level. An automation error will occur if you attempt to reference this property from any other location in the Metabase hierarchy .

Web Application Configuration

To associate a global.asa file with a specific set of scripts, you can configure a virtual directory as a Web application. In addition to the ability to use global functions and variables across all scripts within the application boundaries, you can also force scripts to run in a separate memory space from the IIS service.

This can be especially useful if application developers write "misbehaving" code and you do not want to reboot the server on a regular basis. Many administrators who complain that IIS is unstable find solace by simply running custom-developed applications out-of-process from the IIS service. Although this may incur a small performance detriment, it is a worthwhile sacrifice to maintain the stability of the entire server.

After binding to a virtual directory, you can set the application name, process isolation configuration, permissions for the application, session state parameters, server-side buffering, the language used for all ASP scripts, and the timeout value for ASP scripts. On development servers, you can enable both client- and server-side ASP debugging, as well as determine the verbosity of script error messages.

Basic Application Administration

Most of the common application configuration properties can be defined using the AppFriendlyName , AppRoot , AppIsolated , AccessExecute , and AccessRead properties.

Querying Application Configuration Using Visual Basic

To query an existing application configuration programmatically, you can use the following Visual Basic code to display the application's attributes:

 Dim Application as IADs Dim ServerName As String Dim Index As Long ServerName = "IIS_Server_Name" Index = Site_Index_Value Set Application = GetObject("IIS://" & ServerName & "/W3SVC/" & Index & "/ROOT") Debug.Print "Friendly Name:" & vbTab & vbTab & vbTab & Application.AppFriendlyName Debug.Print "Application Root:" & vbTab & vbTab & Application.AppRoot Debug.Print "Isolated Process:" & vbTab & vbTab & Application.AppIsolated Debug.Print "Read:" & vbTab & vbTab & vbTab & vbTab & Application.AccessRead Debug.Print "Execute:" & vbTab & vbTab & vbTab & vbTab & Application.AccessExecute

Setting Application Configuration Using Visual Basic

To define a new application, you can do so by configuring the appropriate properties in the following Visual Basic code:

 Dim Application As IADs Dim ServerName As String Dim Index As Long Dim ApplicationName As String Dim Isolated As Boolean Dim Read As Boolean Dim Execute As Boolean ServerName = "IIS_Server_Name" Index = Site_Index_Value ApplicationName = "Application_Name" Isolated = True Read = True Execute = True Set Application = GetObject("IIS://" & ServerName & "/W3SVC/" & Index & "/ROOT") Application.AppRoot = Replace(Application.ADsPath, "IIS://" & ServerName, "/LM") Application.AppFriendlyName = ApplicationName Application.AppIsolated = Isolated Application.AccessRead = Read Application.AccessExecute = Execute Application.SetInfo

Advanced Application Administration

In addition to basic application administration, you can also configure the default behavior of the application server. As shown in Figure 9.7, you can configure session timeout values, buffering, parent paths, the default language used for ASP scripts and the timeout value for ASP script execution.

Figure 9.7. Application Configuration dialog box ”App Options tab.

graphics/09fig07.gif

Configuring Application Options Using Visual Basic

Consider the following Visual Basic code to demonstrate the configuration of each of these properties:

 Dim Application as IADs Dim ServerName As String Dim Index As Long ServerName = "IIS_Server_Name" Index = Site_Index_Value Set Application = GetObject("IIS://" & ServerName & "/W3SVC/" & Index & "/ROOT") Debug.Print "Session Timeout:" & vbTab & Application.AspSessionTimeout Debug.Print "Buffering:" & vbTab & vbTab & Application.AspBufferingOn Debug.Print "Parent Paths:" & vbTab & vbTab & Application.AspEnableParentPaths Debug.Print "Script Language:" & vbTab & Application.AspScriptLanguage Debug.Print "Script Timeout:" & vbTab & Application.AspScriptTimeout

Process Options Manipulation

Using ADSI, you can also configure the behavior of IIS service event logging, error handling, ASP caching, and CGI timeout values, as shown in Figure 9.8.

Figure 9.8. Application Configuration dialog box ”Process Options tab.

graphics/09fig08.gif

The following Visual Basic code shows each of the properties used to manipulate the Process Options tab in the IIS 4.0 MMC ISM snap-in:

 Dim Application as IADs Dim ServerName As String Dim Index As Long ServerName = "IIS_Server_Name" Index = Site_Index_Value Set Application = GetObject("IIS://" & ServerName & "/W3SVC/" & Index & "/ROOT") Debug.Print "NT Event Logging:" & vbTab & vbTab & vbTab & vbTab & vbTab & Application.AspLogErrorRequests Debug.Print "Debug Exceptions:" & vbTab & vbTab & vbTab & vbTab & vbTab &  Application.AspExceptionCatchEnable Debug.Print "Script Engines Cached:" & vbTab & vbTab & vbTab & vbTab &  Application.AspScriptEngineCacheMax Debug.Print "Script File Cache:" & vbTab & vbTab & vbTab & vbTab & vbTab &  Application.AspScriptFileCacheSize Set Application = GetObject("IIS://" & ServerName & "/W3SVC/" & Index) Debug.Print "CGI Script Timeout:" & vbTab & vbTab & vbTab & vbTab & vbTab &  Application.CGITimeout

Use Table 9.3 to toggle the Script File Cache option button.

Table 9.3. Script File Cache Option Button Toggling Information

Integer	Description
	Do not cache ASP files
`-1`	Cache all requested ASP files
`n`	Max ASP files cached

ASP Debugging Options Manipulation

In a development environment, it may be helpful to enable ASP debugging for ASP scripts to help track down issues as they arise. As shown in Figure 9.9, IIS allows you to configure both client- and server-side ASP script debugging as well as determine the nature of error messages displayed at the client.

Figure 9.9. Application Configuration dialog boxApp Debugging tab.

graphics/09fig09.gif

Manipulating ASP Debugging Option Using Visual Basic

Consider the following Visual Basic code as an example of application debug behavior manipulation:

 Dim Application As IADs Dim ServerName As String Dim Index As Long ServerName = "IIS_Server_Name" Index = Site_Index_Value Set Application = GetObject("IIS://" & ServerName & "/W3SVC/" & Index & "/ROOT") Debug.Print "ASP Server-Side Debugging:" & vbTab & vbTab & vbTab &  Application.AppAllowDebugging Debug.Print "ASP Client-Side Debugging:" & vbTab & vbTab & vbTab &  Application.AppAllowClientDebug Debug.Print "Detailed Client Error Messages:" & vbTab & vbTab &  Application.AspScriptErrorSentToBrowser If Application.AspScriptErrorSentToBrowser = False then  Debug.Print "Error Message Text:" & vbTab & vbTab & vbTab & vbTab & vbTab &  Application.AspScriptErrorMessage End If

HTTP URL Redirection

As shown in Figure 9.10, IIS has the ability to redirect users to a new site. This can be handy in cases where the content has been moved to an alternate location or the server is in the process of being decommissioned.

Figure 9.10. Default Web Site Properties Configuration dialog boxHome Directory tab (URL redirection).

graphics/09fig10.gif

Using the URL redirection option, you can redirect all requests to an alternate URL. To take advantage of this option programmatically, you assign the HttpRedirect property to the desired URL and desired behavior flags.

Quite often, you want to redirect the user to a new site by concatenating some part of the original URL to a new site while retaining all original parameters. You can perform this by using redirect variables. Variables you can use are listed in Table 9.4.

Table 9.4. Redirect Variables and Descriptions

Variable	Description
`$P`	Passes the original parameters to the new URL. To redirect `www.site1.com?search=exact` to `www.site2.com?search=exact` you could specify `www.site2.com$P` as the redirect URL.
`$Q`	Passes the original parameters to the new URL. In this option, you can pass all parameters (including the question mark) to the new URL. To redirect `www.site1.com?search=exact` to `www.site2.com?search=exact` you could specify `www.site2.com$Q` as the redirect URL.
`$S`	Passes a matched suffix to the new URL. To redirect requests for `/BetaSearch/Find.EXE` to `/Search/Find.Exe` , you could specify the following redirect URL: `/Search$S` .
`$V`	Passes the requested URL without the server name. To redirect all requests from `http://www.isp.net/employment/hot_jobs.asp` to `http://www.consulting.com/employment/hot_jobs.asp` you can use the following redirect URL: `http://www.consulting.com$V` .
`!`	Do not redirect. This can be used to prevent redirecting a directory or file.

Tip

URL redirection also supports the use of wildcards. Check the IIS product documentation for more information on the use of redirection wildcards .

Three options exist to configure the behavior of the URL redirection:

The Exact URL Entered Above. This sends an HTTP redirect header to the specified URL. All variables and wildcards can be used with this option.
A Directory Below This One. This allows you to re-map a parent directory to a child node.
Permanent Redirection for This Resource. This changes the HTTP header from a 301 Temporary Redirect to a 302 Permanent Redirect. In some cases, this can be used to update the URL associated with a bookmark.

Armed with this background information, you can now begin programmatic manipulation of the URL redirect functionality of a home directory.

To perform this redirect functionality, call upon the HttpRedirect administrative property. This property is a single string that expects to receive data in one of two formats:

Destination , Flag, (for example http://www.microsoft.com, EXACT_DESTINATION,)
Destination , Flag1, Flag2, (for example http://www.microsoft.com, EXACT_DESTINATION, PERMANENT,)

With the second format, you can supply multiple flags for the same destination.

Valid flags for this property are as follows :

EXACT_DESTINATION
CHILD_ONLY
PERMANENT

These flags directly correlate to the three URL redirection behavior options described previously.

Querying Current Running Redirection Status Using Visual Basic

To determine where a site has been redirected to, use the following Visual Basic code:

 Dim Resource As IADs Dim ServerName As String Dim Index As Long ServerName = "IIS_Server_Name" Index = Site_Index_Value Set Resource = GetObject("IIS://" & ServerName & "/W3SVC/" & Index & "/ROOT") Debug.Print Resource.HttpRedirect

Setting New Resource Redirection Using Visual Basic

To establish a new resource redirection, use the following Visual Basic code:

 Dim Resource As IADs Dim ServerName As String Dim SiteIndex As Long Dim HttpRedirectString As String ServerName = "IIS_Server_Name" SiteIndex = Site_Index_Value HttpRedirectString = "http://www.sitename.com,FLAG," Set Resource = GetObject("IIS://" & ServerName & "/W3SVC/" & SiteIndex & "/ROOT") Resource.HttpRedirect = HttpRedirectString Resource.SetInfo

Top