ASP.NET Web Project Paths

When working with resources in a Web project, you must often specify a path for the resource. For example, you might use a URL path to reference an image file in a page or the URL of a page elsewhere in the Web site. Similarly, code in your Web project might use a physical file path to a server-based file to read or write the file. ASP.NET provides ways for you to refer to resources and to determine the paths of pages or other resources in the application.

Specifying Paths for Resources

In many cases, elements or controls on your page must refer to an external resource such as a file. ASP.NET supports various methods for referencing external resources. The reference method you choose depends on whether you are working with a client-side element or a Web server control.

Client Elements

Elements that are not Web server controls on a page—client elements—are passed through as-is to the browser. Therefore, when referring to a resource from a client element, you construct paths according to standard rules for URLs in HTML. You can use a fully qualified (which is also known as absolute) URL path or various types of relative paths. For example, if your page contains an img element, you can set its src attribute using one of the following paths:

• An absolute URL path. An absolute URL path is useful if you are referencing resources in another location, such as an external Web site.

  <img src="https://www.contoso.com/MyApplication/Images/SampleImage.jpg" />
  

• A site-root relative path, which is resolved against the site root. Site-root relative paths are useful if you keep resources that are used throughout the site, such as images or client script files, in a folder that is located under the Web site root.

  The following example path assumes that an Images folder is located under the Web site root.

  <img src="/Images/SampleImage.jpg" />
  

  If the URL of your Web site is https://www.contoso.com, the path would resolve to the following:

  https://www.contoso.com/Images/SampleImage.jpg
  

• A relative path that is resolved against the current page path.

  <img src="Images/SampleImage.jpg" />
  

• A relative path that is resolved as a peer of the current page path.

  <img src="../Images/SampleImage.jpg" />
  

  Note

  By default, browsers resolve relative paths by using the current page URL as the base. However, you can include an HTML base element in a page to specify an alternate base path.

Server Controls

In ASP.NET server controls that reference resources, you can use absolute or relative paths as you do for client elements. If you use relative paths, they are resolved relative to the path of the page, user control, or theme in which the control is contained. For example, imagine that you have a user control in a Controls folder. The user control contains an Image Web server control whose ImageUrl property is set to the following path: Images/SampleImage.jpg.

When the user control runs, the path will resolve to the following: /Controls/Images/SampleImage.jpg. This is true no matter what the location is of the page that hosts the user control.

Absolute and relative path references in a server control have the following disadvantages:

• Absolute paths are not portable between applications. If you move the application that the absolute path points to, the links will break.

• Relative paths in the style of client elements can be difficult to maintain if you move resources or pages to different folders.

To overcome these disadvantages, ASP.NET includes the Web application root operator (~), which you can use when specifying a path in server controls. ASP.NET resolves the ~ operator to the root of the current application. You can use the ~ operator in conjunction with folders to specify a path that is based on the current root.

The following example shows the ~ operator used to specify a root-relative path for an image when using the Image server control In this example, the image file is read from the Images folder that is located directly under the root of the Web application, regardless of where in the Web site the page is located.

<asp:image runat="server" id="Image1"
  ImageUrl="~/Images/SampleImage.jpg" />

You can use the ~ operator in any path-related property in server controls. The ~ operator is recognized only for server controls and in server code. You cannot use the ~ operator for client elements.

Determining Physical File Paths for the Current Web Site

In your application, you might need to determine the path of a file or other resource on the server. For example, if your Web project reads or writes a text file programmatically, you must supply the file's complete physical path to the methods used for reading and writing.

It is not a good practice to hard-code physical file paths (such as C:\Website\MyApplication) into your application because the paths can change if you move or deploy your application. In addition, you might not know what the physical path will be if you deploy your site to a hosting provider. However, ASP.NET provides you with ways to get any physical file path within your Web project programmatically. You can then use the base file path to create a full path to the resource you need. The two most commonly used ASP.NET features for determining a file path are properties of the HttpRequest object that return path information, and the MapPath method.

Determining the Path from Request Properties

The following table lists properties of the HttpRequest object that help you determine the paths of resources in your application.

The examples listed in the table are based on the following assumptions:

• A browser request was made using the following URL: https://www.contoso.com/MyApplication/MyPages/Default.aspx.

• The term "virtual path" refers to the portion of the request URL that follows the server identifier; in this case, the virtual path is the following: /MyApplication/MyPages/Default.aspx.

• The physical path for the root of the Web site is the following: C:\inetpub\wwwroot\MyApplication\.

• The physical path contains a folder named MyPages.

Converting a Virtual Path into a Physical Path

The MapPath method returns the complete physical path for a virtual path that you pass to the method. For example, the following code returns the file path for the root of your Web site:

Dim rootPath As String = Server.MapPath("~")

String rootPath = Server.MapPath("~");

See Also

Concepts

ASP.NET Web Project Folder Structure

Page and Application Context in ASP.NET Web Applications

Other Resources

ASP.NET Web Projects