Microsoft KB Archive/299982

From BetaArchive Wiki

Article ID: 299982

Article Last Modified on 10/15/2005


APPLIES TO

  • Microsoft Active Server Pages 4.0
  • Microsoft Internet Information Services 5.0


This article was previously published under Q299982


SUMMARY

This step-by-step procedure demonstrates how to use server-side include (SSI) files in Active Server Pages (ASP) Web applications. SSIs are a widely used technique to package and reuse Web application code. For example, you may have a common database access routine that is used on many pages, or you may have a common header that you want to display at the top of each page in your site. Rather than rewriting the entire code for these tasks on each page, you can write it once in an SSI file and then reference that SSI file on each page that requires the code. Not only are SSIs a great way to avoid a lot of duplicate coding, they also make your site easier to maintain. For example, if your SSI file contains a commonly used header for every page in your site, when you want to change the appearance or content of the header, you only have to change it in one place (the SSI file), and all the other pages that reference it are updated automatically.

Prerequisites

  • Microsoft Windows 2000 Professional, Windows 2000 Server, or Windows 2000 Advanced Server
  • Internet Information Server (IIS) 5.0

Note The features that are described in this article also work on Windows NT with IIS 4.0 or earlier installed and configured, but this sample assumes that you are using Windows 2000.

Prepare the Web site

  1. In Windows Explorer, create a folder named SSITest under your Web server's root folder, which is typically located at C:\Inetpub\Wwwroot\.
  2. Right-click the newly created folder, and then click Properties.
  3. On the Security tab, add the Everyone group, and allow both Read and Write permissions for the Everyone group to the folder. Click OK to accept the changes.
  4. Repeat steps 1 through 3 to create another folder named SSIScripts.
  5. On the Start menu, point to Programs, point to Administrative Tools, and then click Internet Services Manager.
  6. Under Internet Information Services, double-click to expand the entry for the local server.
  7. Right-click the Default Web Site, point to New, and then click Virtual Directory. In the wizard, follow these steps:
    1. When prompted, type SSITest in the Virtual Directory Alias box, and then click Next.
    2. When you are prompted to type the Web Site Content Directory, click Browse, select the newly created SSITest directory, and then click Next.
    3. When you are prompted to select Access Permissions, select Read and Run scripts (such as ASP). No other Access Permissions are necessary for this example. Click Next to complete the wizard.
  8. Right-click the new virtual directory, and then click Properties.
  9. On the Directory tab, verify that the Web name (as entered in step 7b) is listed in the Application Name box under Application Settings. If it is not, click Create to create the application.
  10. Close the Properties dialog box and Internet Information Server.

Create the pages for the SSI demonstration

  1. On the Start menu, point to Programs, point to Accessories, and then click Notepad.

  2. Highlight the following code, right-click the code, and then click Copy. In Notepad, click Paste on the Edit menu to add the following code to the file.

    <%@ Language=VBScript %>
<HTML>
<HEAD>
</HEAD>
<BODY>
<!-- #include file="myHeader.inc" -->
<BR>
<BR>
This is the body of Page 1.<BR><BR>
<A HREF="Page2.asp">Go to Page 2.</A>
</BODY>
</HTML>
  3. On the File menu, click Save.
  4. In the Save in list, browse to the SSITest folder that you created earlier. In the File name box, type Page1.asp, and then click All Files in the Save as Type list. Finally, click Save to save the file.
  5. On the File menu, click New to create a new text document.

  6. Highlight the following code, right-click the code, and then click Copy. In Notepad, click Paste on the Edit menu to add the following code to the file.

    <%@ Language=VBScript %>
<HTML>
<HEAD>
</HEAD>
<BODY>
<!-- #include file="myHeader.inc" -->
<BR>
<BR>
This is the body of Page 2.<BR><BR>
<A HREF="Page1.asp">Go to Page 1.</A>
</BODY>
</HTML>
  7. On the File menu, click Save.
  8. In the Save in list, browse to the SSITest folder that you created earlier. In the File name box, type Page2.asp, and then click All Files in the Save as Type list. Finally, click Save to save the file.
  9. On the File menu, click New to create a new text document.

  10. Highlight the following code, right-click the code, and then click Copy. In Notepad, click Paste on the Edit menu to add the following code to the file.

    <TABLE WIDTH=100% BGCOLOR=Black BORDER=0 CELLSPACING=1 CELLPADDING=1>
  <TR>
   <TD><FONT color=white><B>My Company Header</B></font></TD>
   <TD></TD>
   <TD align=right><FONT color=white>Today's Date: <%=Now()%></font></TD>
  </TR>
</TABLE>
<HR size=1 >
  11. On the File menu, click Save.
  12. In the Save in list, browse to the SSITest folder that you created earlier. In the File name box, type myHeader.inc, and then click All Files in the Save as Type list. Finally, click Save to save the file.

Working with the SSI sample

Browse to the first ASP page

On the Web server or on another computer that has network access to the server, open a Web browser, type the following address in the Address bar, and then press ENTER:

http://<Your Server Name>/SSITest/page1.asp


Notice the header that appears at the top of Page1.asp. Click the link to Page2.asp, and notice that it displays the same header.

Working with file includes

To see how includes work, use Notepad to reopen Page1.asp on the Web server. Approximately six lines into the code, notice that the following include code appears: 

<!-- #include file="myHeader.inc" -->

This one line of code is all that is required to reference the SSI file. If you had 50 pages that needed the same header, you can simply add this one line of code to all of those pages. However, be aware of file path issues in your include syntax. In this case, myHeader.inc is in the same directory as the ASP page that references it; thus, the "file=" attribute in the include tag can just name the file. You can also provide relative paths to the "file=" attribute so that, for example, you can gather all the scripts for your virtual directory into one subordinate folder and reference them as follows: 

<!-- #include file="./myScripts/myHeader.inc" -->

Working with virtual includes

The preceding type of file include works fine when you can place all your scripts within the same virtual directory as your Web application. However, what if you have some reusable script code that you want to make available to multiple Web applications and virtual directories on your server? For example, imagine a company Web server that has multiple virtual directories that serve multiple Web applications, and you want all Web applications to be able to use a common SSI file for a header on their pages. If you use a file type include, every Web application must have its own copy of myHeader.inc.

Fortunately, you can use another type of include, a virtual include, which enables you to store include files in a separate virtual directory and access them from other virtual directories. The syntax for a virtual include appears as follows, where the virtual path to the include file is in the "Website1" virtual directory: 

<!-- #include virtual="../Website1/myHeader.inc" -->

Different types of SSIs

You can use SSIs for purposes other than including files. For instance, it is common to use an SSI called "#exec" that runs an executable program that may access a database or perform other tasks and insert the results into the ASP page. Other SSI keywords enable you to dynamically insert variables, file attributes, and other entities into your ASP pages at run time. For a detailed description of SSIs, see the "References" section.

Troubleshooting

  • SSIs can affect performance. If you have one or more includes on your ASP page, and if those files become large, it slows down your Web application.
  • SSIs can make problems hard to troubleshoot. If you have multiple SSIs in your page, and the page is producing errors, it can be difficult to determine exactly in which SSI the error occurred and where it happened.
  • SSIs can potentially permit malicious users to bypass the security on your Web server. However, this problem has been corrected in Windows 2000 and IIS 5.0.
  • Do not nest SSIs. It is common for developers to develop complex, nested schemes where one SSI includes another, and they are layered in multiple folders throughout a virtual directory. This is generally not a good idea because nested includes are known to perform erratically. It is better to simplify your include structure, perhaps keep one folder with all your includes and another virtual folder for includes that are used by several applications.
  • Be careful with tags. Although you must be on an ASP page for includes to work, do not enclose the include syntax (see the preceding samples) that references an SSI file in any ASP or <SCRIPT> tags. Only add your include reference at the point in the page where you need it, as if it was another HTML tag. The contents of the include itself can be normal HTML or even ASP script, but in the latter case, you must surround the code in the include file with the ASP delimiter tags ("<%" and "%>").


REFERENCES

For more information about how to write reusable script, visit the following Microsoft Web sites:

http://msdn.microsoft.com/library/devprods/vs6/vinterdev/vidref/vihowwritingreusablescript.htm

http://www.microsoft.com/windows2000/en/server/iis/htm/core/iisiref.htm


For more information, click the following article numbers to view the articles in the Microsoft Knowledge Base:

192144 How to dynamically include files in Active Server Pages


187506 Required NTFS permissions and user rights for IIS 4.0


297943 Getting started with Active Server Pages


Keywords: kbhowto kbhowtomaster KB299982



Send feedback to Microsoft

© Microsoft Corporation. All rights reserved.


Retrieved from ‘https://www.betaarchive.com/wiki/index.php?title=Microsoft_KB_Archive/299982&oldid=329339’
the Creative Commons 3.0 ShareAlike (except the Microsoft KB Archive).
Powered by MediaWiki