Including Files

Server-side include directives give you a way to insert the content of another file into a file before the Web server processes it. ASP implements only the #include directive of this mechanism. To insert a file into an .asp file, use the following syntax:

<!-- #include virtual | file ="filename" --> 

The virtual and file keywords indicate the type of path you are using to include the file, and filename is the path and file name of the file you want to include.

Included files do not require a special file name extension; however, it is considered good programming practice to give included files an .inc extension to distinguish them from other types of files.

Using the Virtual Keyword

Use the virtual keyword to indicate a path beginning with a virtual directory. For example, if a file named Footer.inc resides in a virtual directory named /Myapp, the following line would insert the contents of Footer.inc into the file containing the line:

<!-- #include virtual ="/myapp/footer.inc" -->

Using the File Keyword

Use the file keyword to indicate a relative path. A relative path begins with the directory that contains the including file. For example, if you have a file in the directory Myapp, and the file Header1.inc is in Myapp\Headers, the following line would insert Header1.inc in your file:

<!-- #include file ="headers\header1.inc" -->

Note that the path to the included file, Headers\header1.inc, is relative to the including file; if the script containing this #include statement is not in the directory /Myapp, the statement would not work.

You can also use the file keyword with the syntax (..\) to include a file from a parent, or higher-level, directory if the Enable Parent Paths option is selected in the Internet Information Services snap-in.

Location of Included Files

ASP detects changes to an included file regardless of its location and inserts the files content the next time a browser requests an .asp file which includes this file. However, in general, it is easier to secure include files if they reside within the same application or Web site. For better security, it is advisable to place include files in a separate directory within your application, such as \Includes, and apply only appropriate Execute (Web server) permissions.

Important   By default, Web server Read permissions are applied to all files. However, to prevent users from viewing the contents of your include files, disable Read permissions for the Include directory.

Including Files: Tips and Cautions

An included file can, in turn, include other files. An .asp file can also include the same file more than once, provided that the #include directives do not cause a loop. For example, if the file First.asp includes the file Second.inc, Second.inc must not in turn include First.asp. Nor can a file include itself. ASP detects such loop or nesting errors, generates an error message, and stops processing the requested .asp file.

ASP includes files before executing script commands. Therefore, you cannot use a script command to build the name of an included file. For example, the following script would not open the file Header1.inc because ASP attempts to execute the #include directive before it assigns a file name to the variable name.

<!--  This script will fail -->
<% name=(header1 & ".inc") %> 
<!-- #include file="<%= name %>" -->

Scripts commands and procedures must be entirely contained within the script delimiters <% and %>, the HTML tags <SCRIPT> and </SCRIPT>, or the HTML tags <OBJECT> and </OBJECT>. That is, you cannot open a script delimiter in an including .asp file, then close the delimiter in an included file; the script or script command must be a complete unit. For example, the following script would not work:

<!-- This script will fail -->
<%
  For i = 1 To n
    statements in main file
    <!--  #include file="header1.inc" -->
  Next
%>

The following script, however, would work:

<% 
  For i = 1 to n
    statements in main file
%> 
<!--  #include file="header1.inc"   -->
<% Next %>

Note   If the file that your ASP script includes contains a large number of functions and variables that are unused by the including script, the extra resources occupied by these unused structures can adversely affect performance, and ultimately decrease the scalability of your Web application. Therefore, it is generally advisable to break your include files into multiple smaller files, and include only those files required by your server-side script, rather than include one or two larger include files that may contain superfluous information.

Occasionally, it may be desirable to include a server-side file by using the HTML <SCRIPT></SCRIPT> tags. For example, the following script includes a file (by means of a relative path) that can be executed by the server:

<SCRIPT LANGUAGE="VBScript" RUNAT=SERVER SRC="Utils\datasrt.inc"></SCRIPT>

The following table shows the correct syntax for including files with the SRC attribute by means of either virtual or relative paths:

Note   You should not put any programmatic logic between the <SCRIPT> tags when including by this method; use another set of <SCRIPT> tags to add such logic.