number of features of Microsoft® Internet Explorer are geared toward the corporate intranet. One of these is the ability to specify one or more proxy servers for Internet Explorer to use when connecting to servers outside the company. The basic proxy configuration information for Internet Explorer 5.0 can be found in the Tools | Internet Options menu, on the Connections tab (see Figure 1).

Figure 1: Proxy Configuration Settings

    Larger companies with big networks frequently need to specify more than one proxy server and allow users to choose between them based on transient conditions. Proxy Auto-Configuration (PAC) files, indicated with a .pac extension, accomplish this by allowing a server administrator to author a single script file that determines which of numerous proxies to use for all client computers throughout the enterprise.

    Some examples of how a PAC file can be used are:

• Choosing a proxy at random from a list for load balancing.
• Rotating proxies by time of day or day of the week to accommodate a server maintenance schedule.
• Specifying a backup proxy server to use in case of failure of the primary proxy.
• Specifying the nearest proxy for roaming users based on the local subnet.

    I'll discuss the structure and content of PAC files and address some of the problems and questions I receive in Microsoft Developer Support regarding these auto-proxy files.

What's in a PAC?

    A PAC file is a plain text file that, in its most basic form, consists of a single JScript® function called FindProxyForURL. Internet Explorer calls this function with two parameters: the full URL to which the user is navigating and the hostname portion of that URL. The FindProxyForURL function must return one of three possible strings: "DIRECT" tells Internet Explorer it should bypass the proxy server, "PROXY" followed by a proxy server name and port specifies a proxy, and "SOCKS" followed by a SOCKS server name and port specifies that Internet Explorer should use that SOCKS server. The auto-proxy file can also indicate some combination of these choices, delimited by semicolons.

    The following PAC file will check whether the user is navigating to a page at www.harvest-books.org.

   function FindProxyForURL(url,host)
   {
     if (host == "www.harvest-books.org")
         return "DIRECT";
 
         return "PROXY myproxy.harvest-books.org:80;
                 PROXY myotherproxy.harvest-
                 books.org:8080; 
                 DIRECT" ;  
   }

Getting Fancy

    My first example demonstrates the general sort of logic contained in an auto-proxy file. At its bare minimum, it is nothing more than a series of if. . .then statements used to determine a proxy setting based on certain conditions. Your network situation may demand more complex logic. For example, you might want to implement round-robin load balancing on the client side by creating a function that picks a proxy based on the time of day, a random number, or some other factor. The following PAC file excerpt demonstrates how to use a helper function to randomly choose from among five proxy servers:

 function FindProxyForURL(url,host)
 {
      return randomProxy();
 }
 
 function randomProxy()
 {
     switch( Math.floor( Math.random() * 5 ) )
     {
         case 0:
             return "PROXY proxy1.harvest-books.org:80";
             break;
         case 1:
             return "PROXY proxy2.harvest-books.org:80"; 
             break;
         case 2:
             return "PROXY proxy3.harvest-books.org:80";
             break;
         case 3:
             return "PROXY proxy4.harvest-books.org:80";
             break;
         case 4:
             return "PROXY proxy5.harvest-books.org:80";
             break;
     }    
 }

    With the exception of dnsResolve, dnsDomainLevels, and myIPAddress, these functions all return a boolean value based on a simple condition. It may be easiest to think of these return values as pieces of information your function will use to help make a decision about which proxy Internet Explorer should use.

    Consider the following logical decisions and their equivalents in code. Am I navigating to a machine on the local intranet (http://myservername/)? If so, I'll bypass the proxy.

 if ( isPlainHostName( host ) ) return "DIRECT";

 if ( isInNet( host, myIPAddress( ), "255.255.0.0" ) ) 
     return "PROXY proxy1.harvest-books.org:80";

 if ( shExpMatch( url, "https*" )  )
 {
     if( shExpMatch( host, "*.harvest-fin.org" ) )
     {
         return "PROXY secure-prxy1.harvest-books.org:443";
     }
     return "PROXY secure-prxy2.harvest-books.org:443";
 }

PAC Files and the Document Object Model

    Those familiar with JScript are probably used to thinking of the Internet Explorer object model as part of the language. However, objects such as window, document, and navigator are pieces of the Internet Explorer Document Object Model (DOM), which is only available from within a Web page. Methods, properties, and functions of the DOM are not available within an auto-proxy file. If you try to reference members of the window object, the document object, or other Web page elements, the PAC file will fail silently (without presenting an error message). Only intrinsic elements of the JScript language are valid within the PAC file.

    One exception is the alert statement, which is normally used as a method of the DOM window object. Microsoft has made a hotfix available for Internet Explorer 4.01, which allows an alert message to be displayed to the user from within a PAC file. My experiments show that this method works in Internet Explorer 5.0 (now available from the Microsoft Web site) and in preview builds of Service Pack 2 for Internet Explorer 4.01 (which should also be available soon after press time). The hotfix is discussed in the Microsoft Knowledge Base article Q181856 at http://support.microsoft.com/support/kb/articles/q181/8/56.asp.

Setup and Deployment

Deploying an auto-proxy file is not difficult, but there are several requirements that must be satisfied. First, the file must be referenced using an HTTP-based URL. This means that the file cannot live on the local file system; it must be on a Web server. Second, the server should return the appropriate content type for the file. Internet Explorer will excuse this lapse, but if you plan to use the file with a mix of browsers, your server should map the .pac file extension to the MIME type application/x-ns-proxy-autoconfig. If you are using Internet Explorer exclusively, you can use either the .pac or the .js extensions for the file, and you needn't worry about returning a particular content type for the file.

    The final step is to tell Internet Explorer where to look for proxy information. There are two ways to specify a PAC file for Internet Explorer to use for proxy auto-configuration. You can specify the file directly in Internet Options. In Internet Explorer 4.x, the settings can be found at View | Internet Options | Connections | Automatic Configuration. Select the Configure button and enter the URL. In Internet Explorer 5.0, these settings are available by selecting Tools | Internet Options | Connections | LAN Settings | Use automatic configuration script.

    Your second option is to specify an .ins auto-configuration file (developed using the IEAK) in the previous location, and specify the PAC file as the AutoConfigJSURL value in the [URL] section of the .ins file. (The .ins format is similar to the .ini format.) In the IEAK Profile Manager, you specify the PAC file under Automatic Browser Configuration in the Auto-Proxy URL box. Remember that with either option the auto-configuration file must be specified using an HTTP URL.

Debugging your PAC File

    In general, proxy auto-configuration files are simple, but for larger, more complicated files with many logical twists, you may reach a point where it isn't sufficient to troubleshoot files by inspection or by throwing alerts. In this case, Microsoft Visual InterDev™ 6.0 can come to the rescue. Visual InterDev can attach to any process that hosts the Active Scripting Engine for JScript. This will allow you to set breakpoints, step through code, and examine variables at runtime, just as you can with a debugger for any of the compiled languages.

    To debug your auto-proxy file using Visual InterDev, put it on your server and have Internet Explorer point to it as described previously. From the Debug menu in Visual InterDev, choose Processes. In the process selection box, choose Iexplore.exe (Internet Explorer must be running). Click the Attach button and then close the process dialog. At this point, you can go to the View menu and choose Debug windows | Running documents. This will give you a list of debuggable scripts running in Internet Explorer. Your PAC file will be listed as "JScript - script block." Clicking on this entry in the running documents pane will open the file and allow you to debug that source as it is running.

See the sidebar "Known Issues".

Do you have questions for FAQ? Send mail to faq@microsoft.com.

From the May 1999 issue of Microsoft Internet Developer.