Deploying ASP.NET Web Applications in the Windows SharePoint Services 3.0 _layouts Folder

Summary:  Learn to use Microsoft Visual Studio 2005 to create a simple ASP.NET 2.0 Web site that you can deploy to the SharePoint layouts folder.

Applies to:  2007 Microsoft Office System, Microsoft Windows SharePoint Services 3.0, ASP.Net 2.0, Microsoft Visual Studio 2005

Joel Krist, iSoftStone

February 2008

Windows SharePoint Services 3.0 uses the following folder to deliver SharePoint administration pages to each site in the site collection:

%ProgramFiles%\Common Files\Microsoft Shared\Web server extensions\12\Template\Layouts

The layouts folder is a special directory that gets "virtualized" for each SharePoint site. That is, each SharePoint site will have a /_layouts path from the root of the Web. For example http://servername/sites/sitename/_layouts. You can make an ASP.NET 2.0 Web application available under each SharePoint site by deploying the application to the layouts folder. This How To illustrates deploying ASP.NET Web applications in the Windows SharePoint Services 3.0 _layouts folder.

The following sections use Visual Studio 2005 to create a simple ASP.NET 2.0 Web site that you can deploy to the SharePoint _layouts folder. The process includes four major steps:

  • Creating a Web site project in Visual Studio 2005.

  • Adding a reference to the SharePoint Services assembly to the Visual Studio project.

  • Modifying the Web site to use the SharePoint master page.

  • Copying the Web site to the SharePoint _layouts folder.

To create a Web site project in Visual Studio 2005

  1. Start Visual Studio.

  2. On the File menu, click New, and then click Web site. The New Web site dialog box appears.

  3. In the Visual Studio installed templates pane, select ASP.NET Web site.

  4. Select File System for the Location and specify a path and name for the project.

    Note
    You can select the SharePoint _layouts folder as the parent folder for the folder containing the new Web site. Doing this removes the need to copy the Web site to the _layouts folder. For the purposes of illustration, this How To takes the approach of creating the new Web site in a separate folder and then copying it to the _layouts folder.
  5. Select Visual C# or Visual Basic for the Language and click OK. Visual Studio generates an ASP.NET Web Site project and opens the default.aspx page in the editor.

    Figure 1. Create New Web site


The sample code shown below uses the SharePoint SPWeb and SPContext classes to illustrate that the Web site is running in the SharePoint context. You can use these classes by adding a reference to the SharePoint Services assembly to the project.

If Visual Studio is running on a computer that has SharePoint Services installed, do the following:

To add a reference to the SharePoint Services Assembly

  1. From the Context menu, right-click the default.aspx file in the code editor and click Add Reference. The Add Reference dialog box is displayed.

  2. In the Add Reference dialog box, click the .NET tab, then locate and select the following component:

    Windows SharePoint Services component (Microsoft.SharePoint.dll)

  3. Click OK to add the reference.

    If Visual Studio is running on a computer that does not have Windows SharePoint Services or Office SharePoint Server installed on it then the SharePoint Services assembly is not available. In this case, you can copy the assembly from a computer with SharePoint Services installed to a local project folder on the development computer. The assembly file you need to create the sample Web site is Microsoft.SharePoint.dll. By default this assembly is located in the following folder on a computer that has SharePoint Services installed:

    C:\Program Files\Common Files\Microsoft Shared\Web server extensions\12\ISAPI

    After you make a local copy of the assembly, you can add the necessary reference to the Web site project by browsing for the local file.

  4. In Visual Studio Solution Explorer, right-click the Web site project name and click Add Reference. The Add Reference dialog box is displayed.

  5. Click the Browse tab then navigate to the local folder containing the copy of the SharePoint assembly.

  6. Select the Microsoft.SharePoint.dll file.

  7. Click OK to add the reference to the project.

Master pages are a feature of ASP.NET 2.0; they work the same way in Windows SharePoint Services 3.0 and Office SharePoint Server 2007 as they do in ASP.NET 2.0. Using master pages, you can create a single page template and then use it as the basis for multiple pages, instead of having to build each new page from scratch. SharePoint uses master pages to provide a consistent look and feel for the site. You need to modify the default.aspx page to make the sample Web site fit seamlessly into the SharePoint site by using the SharePoint master page.

The first step is to add the following MasterPage attribute to the page directive at the top of the default.aspx file:

MasterPageFile="~/_layouts/application.master"

This specifies that the default.aspx page uses the SharePoint application.master page for a master page. The application.master page is provided with SharePoint and provides the master page functionality for the administrative related pages that are located in the _layouts folder.

Master pages make use of content placeholder controls. These placeholder controls define regions where replaceable content will appear. In turn, the replaceable content is defined in content pages. Modify the default.aspx page to make it work with two of the content placeholder controls provided with the SharePoint master page by doing the following:

To modify the Website to use the SharePoint Master Page

  1. Add the following directives to the top of the default.aspx file, just below the Page directive modified previously:

    <%@ Assembly Name="Microsoft.SharePoint.ApplicationPages, 
    Version=12.0.0.0, Culture=neutral,
    PublicKeyToken=71e9bce111e9429c" %>
    <%@ Register Tagprefix="SharePoint" 
    Namespace="Microsoft.SharePoint.WebControls" 
    Assembly="Microsoft.SharePoint, Version=12.0.0.0, 
    Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
    <%@ Register Tagprefix="Utilities" 
    Namespace="Microsoft.SharePoint.Utilities" Assembly="Microsoft.SharePoint, Version=12.0.0.0, 
    Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
  2. Replace the default.aspx HTML markup generated by Visual Studio with the following:

    <asp:Content ID="Content1" ContentPlaceHolderId="PlaceHolderMain" >
        <div>
        Title of this site: <asp:Label ID="LabelTitle"  Text="Label">
        </asp:Label>
        </div>
    </asp:Content>
    <asp:Content ID="Content2" 
    ContentPlaceHolderId="PlaceHolderPageTitleInTitleArea" >
    Test ASP.NET 2.0 Application
    </asp:Content>

    This new code uses two of the master page content placeholders, PlaceHolderMain and PlaceHolderPageTitleInTitleArea, to display its content. PlaceHolderMain displays the main content of the page and PlaceHolderPageTitleInTitleArea displays a title for the application. After you make the changes described above, the dafault.aspx should look like the following:

    Figure 2. Modified Default.aspx


    Visual Studio tags the content placeholder IDs and MasterPage directive as invalid because it cannot locate the master page. You can ignore these warnings since you will locate the master page when the Web site is copied to the _layouts folder.

To set the text of the Label control used in the PlaceHolderMain content placeholder, modify the code file for the page by doing the following:

To set the text of the Label control

  1. From the Context menu, right-click the default.aspx file in the code editor and click View Code. Visual Studio displays the default.aspx.cs or default.aspx.vb code file, depending on the language selected when the Web site project was created.

  2. Add the following Imports or using statement to the top of the code file. For the C# case, add the using statement after the using statements generated by Visual Studio.

  3. Modify the contents of the page load event handler method and add code to set the text of the Label control to display the title of the current Web site. For the Visual Basic case, add the page load event handler by selecting Page Events from the Class Name dropdown list and then selecting Load from the Method Name dropdown list.

    Figure 3. Adding Page_Load Event Handler


  4. Add the following code to the body of the Page_Load method:

    The default.aspx page currently uses the application.master page as the master page. This master page makes the page look and feel like the other SharePoint pages that are located in the _layouts folder. To make the default.aspx page use a different SharePoint master page, add the following override of the OnPreInit method:

The preceding code modifies the page at runtime to use the default.master master page that is located in the SharePoint Master Page Gallery. You can use the same technique to select other master pages from the gallery.

To deploy the Web site to the SharePoint _layouts folder, do the following:

To deploy the Web site to the SharePoint layouts folder

  1. Modify the contents of theWeb.config file of ASP.NET Web site and comment out the <authentication> section. For example:

    <!-- <authentication mode="Windows"/> -->
  2. Save the modified Web.config file.

  3. Copy the folder containing the ASP.NET 2.0 Web site to the following folder on the server running SharePoint:

    %ProgramFiles%\Common Files\Microsoft Shared\Web server extensions\12\TEMPLATE\LAYOUTS

    For example, if the folder containing the Web site files is named MyWebSite, the full path to the folder after you copy it to the SharePoint server would be:

    %ProgramFiles%\Common Files\Microsoft Shared\Web server extensions\12\TEMPLATE\LAYOUTS\MyWebSite

    The Web site is now available and running within the SharePoint context. Navigating to it displays the default.aspx page that shows the title of the site and uses the SharePoint default.master master page.

    Figure 4. ASP.NET Site in SharePoint


Creating a SharePoint application by deploying to the SharePoint _layouts folder has the following benefits:

  • It is an easy way to make functionality available in every site.

  • It is just like developing a regular ASP.NET Web site using the familiar Visual Studio environment.

  • It allows for context sensitive access to the SharePoint object model.

This approach does have some drawbacks, specifically that the deployment of the site is not managed via the SharePoint solution deployment mechanism.

It is best to use a _layouts based application when the goal is to extend every site with some functionality such as additional administration pages.

This article explores how to use Visual Studio 2005 to create a simple ASP.NET 2.0 Web site that you can deploy to the SharePoint _layouts folder. The following steps were performed:

  • Creating a Web site project in Visual Studio 2005.

  • Adding a reference to the SharePoint Services assembly to the Visual Studio project.

  • Modifying the Website to use the SharePoint master page.

  • Copying the Web site to the SharePoint _layouts folder.

Watch the Video

Video Length: 00:6:22

File Size: 5.1 MB WMV