ASP.NET Web Site Paths

When working with resources in a Web site, 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 application might use a physical file path to a server-based file to read or write the file. ASP.NET provides facilities for referring to resources and for determining 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 (not the application root). Site-root relative paths are useful if you keep cross-application resources, such as images or client script files, in a folder that is located under the Web site root.

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

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

  If 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 the location of the page that hosts the user control.

Note
In master pages, paths to resources are resolved based on the path of the content page. For more information, see ASP.NET Master Pages Overview.

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.

Note

For mobile pages only, if your application relies on cookieless sessions or might receive requests from mobile devices that require cookieless sessions, using a tilde ("~") in a path can result in inadvertently creating a new session and potentially losing session data. To set a property on a mobile control with a path that includes a tilde (such as "~/path"), resolve the path using the ResolveUrl method before assigning it to the property.

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 application 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. However, ASP.NET provides you with ways to get any physical file path within your application 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.

Note
Physical file paths should not be sent to the client because they could be used by a malicious user to gain information about your application.

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.

Using the MapPath Method

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("~");

Note
The path passed to the MapPath method must be an application-relative path rather than an absolute path.

See Also

Concepts

ASP.NET Web Site Layout
Page and Application Context in ASP.NET Web Applications