12/20/2010 ASP.

NET Web Project Paths

ASP.NET Web Project Paths

.NET Framework 4

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="http://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 http://www.contoso.com, the path would resolve to the
following:

http://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
msdn.microsoft.com/…/ms178116.aspx 1/4
12/20/2010 ASP.NET Web Project Paths
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.

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.

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

msdn.microsoft.com/…/ms178116.aspx 2/4
12/20/2010 ASP.NET Web Project Paths
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.

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:

http://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.

Property Description

ApplicationPath Gets the root path of the current application, regardless of where in
the application you request it. For the example, the property returns
the following: /

CurrentExecutionFilePath Gets the virtual path of the current request. Differs from the FilePath
property in that CurrentExecutionFilePath is correct if the request has
been redirected in server code. For the example, the property returns
the following: /MyApplication/MyPages/Default.aspx

If you get the property in code that is running as a result of a call to

Transfer or Execute, the path reflects the location of the code.

FilePath Gets the virtual path of the current request. For the example, the
property returns the following: /MyApplication/MyPages/Default.aspx

Unlike the CurrentExecutionFilePath property, FilePath does not reflect

server-side transfers.

Path Gets the virtual path of the current request. For the example, the
msdn.microsoft.com/…/ms178116.aspx 3/4
12/20/2010 ASP.NET Web Project Paths
property returns the following: /MyApplication/MyPages/default.aspx

PhysicalApplicationPath Gets the physical file system path of the currently executing
application's root directory. For the example, the property returns the
following: C:\inetpub\wwwroot\

PhysicalPath Gets the physical file-system path that corresponds to the requested
URL. For the example, the property returns the following:
C:\inetpub\wwwroot\MyApplication\MyPages\default.aspx

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:

VB

Dim rootPath As String = 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 Project Folder Structure

Page and Application Context in ASP.NET Web Applications

Other Resources

ASP.NET Web Projects

Community Content

msdn.microsoft.com/…/ms178116.aspx 4/4