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.jpgA 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.
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 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: 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.
Property |
Description |
|---|---|
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: / |
|
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. |
|
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. |
|
Gets the virtual path of the current request. For the example, the property returns the following: /MyApplication/MyPages/default.aspx |
|
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\ |
|
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:
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 Project Folder Structure
Page and Application Context in ASP.NET Web Applications