Skip to content

Products -->-->
Discontinued

PageXchanger Documentation

PageXchanger is an ISAPI filter that provides a powerful form of content negotiation for IIS Web servers. Requests to a Web site can be examined and responses custom suited to the capabilities and preferences of the requester/client. This content negotiation also allows the hiding of file extensions in URLs and throughout the Web site source code.


Installation

Installing PageXchanger is very simple. Once you have downloaded the installer executable from the Port80 Web site, double click on the file to begin the PageXchanger setup program.

The PageXchanger setup program will guide you through the steps necessary to complete the installation. You will be asked to accept the license agreement and to choose an installation destination. The default installation location is C:\Program Files\Port80\PageXchanger.

Files Installed by PageXchanger

PageXchanger installs the following files in the following default locations:

In C:\%SystemRoot%\System32\inetsrv\

px_isapi.dll PageXchanger ISAPI filter DLL

In C:\Program Files\Port80\PageXchanger\

PageXchanger.exe Settings Manager
w3svcupd.exe Installer utility for updating metabase
documentation Documentation/Help for PageXchanger
ReleaseHistory.htm Release history for PageXchanger
TechSupport.htm Information about obtaining technical on PageXchanger
Activation.txt Activation Help
Install.log Installation log file
Uninstall.exe Uninstaller for PageXchanger

In C: \Program Files\Port80\PageXchanger\files\

Supporting files used for the Documentation

back to top

Using the Settings Manager

The Settings Manager can be launched from the Port80/PageXchanger program group in the Start menu, or directly by running PageXchanger.exe. The Settings Manager controls the operation of PageXchanger for any Web site (virtual server) provisioned on the computer. On the left side of the Settings Manager is a list of all the Web Sites (virtual servers) that are available on the computer. Use this list to select the Web site whose settings you want to change.

Screenshot of PageXchanger Settings Manager
  • To configure PageXchanger settings for a particular Web site: Select the site from the Web Sites list. The controls on the Settings Manager will reflect the current settings for that Web site. Any changes you make will take effect only for the site that is selected.
  • To configure PageXchanger's default settings for new Web sites: Select Default Settings from the Web Sites list. The controls on the Settings Manager will reflect the current default settings. Any changes you make will take effect for any new Web sites that are added in IIS.
  • To configure PageXchanger settings for two or more Web sites: Select the sites from the Web Sites list (optionally including Default Settings) using the Shift key (for two or more contiguous Web sites) or the Control key (for two or more discontinuous Web sites). In this case, the controls on the Settings Manager will reflect the current settings for the first Web site selected -- which will also be the one pointed to by the arrow indicator. Any changes you make will take effect for all the sites that are selected.

After making any changes on the PageXchanger Settings Manager, you must press either the "Apply" or the "OK" button in order for the changes to take effect. OK dismisses the Settings Manager dialog, Apply does not. Click "Cancel" (or use the File/Exit menu option) to abandon any changes and exit the Settings Manager.

back to top

Static File Negotiation

With Static File Negotiation enabled, PageXchanger will select the most appropriate version of a resource based on the list of suitable, or most preferred, MIME types from the client's Accept: header. Suppose you have two images, abc.gif and abc.png. If the client makes a request for a file named abc with the following request:

GET /abc HTTP/1.1
...
Accept: image/gif;q=0.3, image/jpeg;q=0.4, image/png;q=0.5

PageXchanger will examine the quality ratings (q ratings) of the Accept: header value and, in this case, serve a png file to the user.

Screenshot of PageXchanger Settings Manager

The "PageXchanger Negotiated Types" list on the left shows the MIME Types and associated file extensions that PageXchanger is configured to negotiate.

The "Available Types for Negotiation" list on the right shows the MIME Types and associated file extensions that are configured on the Windows Server (from the system metabase). Use the "Mime Type Filter" in the top right corner of the tab to change what MIME Types are displayed in the two lists.

If you would like to enable a MIME Type/file extension pair to be negotiated by PageXchanger, you may either select it from the "Available Types for Negotiation" list on the right side and click the left arrow button, or you may click the "Add..." button and enter the information manually.

When a request is made to your Web site, the MIME type preferences expressed in the client's Accept: header are compared against the "PageXchanger Negotiated Types" list. If the MIME type with the highest q rating in the Accept: header is present in this list, PageXchanger will first try to locate the resource of that type. If it is not available, it will try the MIME type second highest ranked in the Accept: header, and so on until an appropriate match is found.

In the event that the client's MIME type preferences are unknown, PageXchanger will use the ordering of the "PageXchanger Negotiated Types" to the same effect as the q ratings in the Accept: header.

back to top

Dynamic File Negotiation

Dynamic File Negotiation is similar to Static File Negotiation, but uses file extensions rather than MIME types to negotiate dynamic resources, which allows dynamic files to be requested with or without a file extension. This will keep the URL clean and also make the scripting language transparent to the user.

Screenshot of PageXchanger Settings Manager

When Dynamic File Negotiation is enabled, if a request is made for a resource on your Web site without a file extension, PageXchanger will complete the request using an extension from the "File Extensions" list on the Dynamic Negotiation tab. These extensions should be mapped to applications on the server (most commonly these are the interpreters for the scripting environment in which the site runs, i.e. ASP, ColdFusion, PHP).

The order of the "File Extensions" list on the Dynamic Negotiation tab is significant in that PageXchanger will start at the top of this list when mapping and will traverse this list from the top until it finds a resource that is available on the Web site.

So for example, if Dynamic File Negotiation is enabled and the "File Extensions" list includes "asp" at the top of the list, a user making a request to your site for the file

www.website.com/products/index

will be served the file

www.website.com/products/index.asp
back to top

Language Negotiation

When Language Negotiation is enabled, PageXchanger will examine the language-range values of the client's Accept-Language: header and serve the resource in the appropriate language, provided that the file exists.

Screenshot of PageXchanger Settings Manager

The file naming convention used for language negotiation in PageXchanger is very simple. For your default language, leave the file name as it is, for example index.asp. For each additional language you would like to support for that file, create another file and append a dash and the language-range characters to the name. For example, the German file would be named index-de.asp and the French file would be index-fr.asp. Second, make sure each language for which you created a file is in the language list on the Language Negotiation tab in the Settings Manager.

If a client makes a request and none of the languages specified in their Accept-Language: header are configured to be supported by PageXchanger, then the default language will be assumed.

Now, if you have set up PageXchanger to support English (as the default), German and French, the files would be named index.asp, index-de.asp, index-fr.asp. If the client makes the following request for index (or index.asp):

GET /index HTTP/1.1
...
Accept-Language: es, fr;0.8, en;0.5

PageXchanger will first look for the file index-es.asp since the absence of a q rating defaults to the highest legal value (1.0). In this example, PageXchanger was not configured to support Spanish (es), so it will move on. The next language requested is French (fr) and PageXchanger finds index-fr.asp exists, so it serves the content of that file.

Note: The mechanism used in PageXchanger is such that the URL displayed in the client's address bar will remain as index even though the content of index-fr.asp is being displayed. This keeps the URL of a resource clean and consistent, despite differences in the page that is served.

Language Override Cookie
To override the client's language preferences in the Accept-Language: header, a special cookie, named P80LO, can be used. This is useful if you want to allow users to change their language preferences when using your site without changing them in the browser. To use this feature, set the value of the cookie P80LO to be the language-range characters. For example, to override the client's languages preferences to be German, set P80LO=de.

back to top

Advanced Settings

Screenshot of PageXchanger Settings Manager
For Requests with File Extensions

These features determine the behavior of PageXchanger when requests are made for files with file extensions.

Do not redirect
When this feature is checked, PageXchanger does not negotiate static or dynamic content because the file extension exists in the request. However, PageXchanger will continue to negotiate language.

Redirect to file without extension
When this feature is checked, PageXchanger will redirect the client to the same resource, but without the file extension. For example, a request for:

www.website.com/products/index.asp

would be redirected to

www.website.com/products/index

Redirect to a relative path
When this feature is checked, PageXchanger will redirect the client to the path specified by the edit box. Be careful not to include a file extension in the redirect path; this would cause an infinite loop of redirection.

This feature is helpful if you are trying to migrate your site to clean URLs without file extensions. Perhaps a user has an old bookmark to /products/info.asp. You can redirect them to a catch all page by setting the relative path similar to /mycatchall/, etc.

Do not redirect POST requests
To preserve data sent with POST requests, redirections should be disabled for POST requests until file extensions are removed from Web site source code. Checking this check box will prevent Posts from redirecting. It can be unchecked after extensions have been removed from Web site source code.

Advanced Mime Type Settings

Enable XHTML Mime Type Fix
When this feature enabled, if a client makes a request for a resource which includes application/xhtml+xml in the Accept: request header, and a XHTML DOCTYPE appears within the first 255 characters of the file, PageXchanger will correct the Content-Type: response header to be application/xhtml+xml.

Cookies and Exclusions

Use Cookies to Preserve Settings
Cookies can be used to preserve the request header values that are necessary for content negotiation and that are sometimes only sent during the initial request of a session. This can allow the content negotiation to maintain the highest level of specificity throughout an entire session.

Adding session cookies that are set on your Web site to the Cookie List will enable PageXchanger to preserve their values during HTTP redirects. This is necessary when either the "Redirect to file without extension" or the "Redirect to the following path" option is enabled in PageXchanger.

Exclusions
This feature allows you to exclude PageXchanger from acting on certain files or file extensions.

back to top

Understanding Content Negotiation

Because of the growing variety of Internet users, a resource on a Web site must oftentimes be available in a variety of representations; for example, pages must be written in different languages or images must be available in different MIME types for browsers with different display capabilities.

How It Works
When a user's browser sends a request to a server, it includes information in its HTTP headers about the types of resources that it is capable of displaying or that it prefers being served. For instance, the browser's Accept header includes a list of MIME types that the browser is able to display. Typically these will include image MIME types such as,

Accept: image/gif, image/jpeg, image/png

If the values are sent in this order, the browser will most likely be served a gif image. For content negotiation purposes, each of these values could also be assigned a quality rating (or q rating). If, for example, the same image MIME types are sent with the following q ratings,

Accept: image/gif;q=0.3, image/jpeg;q=0.4, image/png;q=0.5

it means that the browser is expressing a preference for a graphic in a png format, since image/png has the highest q rating value.

When content negotiation is enabled, a server can transparently select and serve a requested resource based on an evaluation of the browser's capabilities or preferences. When a server using PageXchanger receives the Accept headers with the q ratings above, the server first looks for the resource in a png format. If that is not available, it searches for the resource in a jpeg format, then if necessary, in a gif format.

PageXchanger allows content to be negotiated based on language (Language Negotiation) and MIME type. When these types of content negotiation are used in combination with other features of PageXchanger, like Application Mapping, it allows a site's file extensions to be hidden from a request, providing cleaner URLs and obscuring the scripting environment in which the site is running.

back to top

System Requirements

PageXchanger is compatible with the following:

  • IIS 6.0 (Windows Server 2003)
  • IIS 5.0 (Windows 2000 Server)
  • IIS 4.0 (NT 4.0 Server)
  • IIS 5.1 (Windows XP)*
* Since Windows XP lacks a true "server" configuration, Port80 Software neither recommends nor supports the use of its software on Windows XP (and the associated version of IIS) in production environments. The Windows XP environment is supported exclusively as an evaluation platform.
back to top

Known Issues

PageXchanger 2.0 has the following known issues:

  • If a request uses a POST method and the URL of the target page has a file extension, the redirect method that PageXchanger uses can result in the loss of posted data. This could occur when "Remove extension/Redirect file" with the "Redirect without extension" option is selected (which is the default setting) and the file extension has not been removed from the POST request. This issue is corrected by ensuring that with these settings enabled, the file extension is removed from the POST request or the "Do not redirect POST requests" setting is enabled.
back to top
Port80 Software stands behind our products 100%. Given the nature of Web server utilities, various environments and third party applications may cause new and unforeseen conflicts. Therefore, Port80 pledges to work with you to ensure our products run in all testing and production environments - if you work with us, we will work with you to make your IIS Web server safer, faster and friendlier.