DotNet Development, SharePoint Customizing, Silverlight, MS Infrastructure and other tips and tricks

different appendages for a custom aspx page to SharePoint

Posted by PANVEGA on February 7, 2008

In this post I am going to show how to add a custom aspx page to SharePoint. Maybe you already have developed an ASP .Net Web Application with many web forms, user controls, business layer, and data access layer and want to add this aspx page to SharePoint. In this post I´m going to explain some different ways how to integrate an aspy page.

The goal is to integrate the files within this web application into the SharePoint site and totally get rid of the web application. This has couple of advantages:

  1. Business users and end users need not go to a separate web application (URL). Users can see all those pages within SharePoint site.
  2. Once the integration is done, we have the SharePoint site’s security and access rules i.e. Authentication and Authorization is in place without any additional work.
  3. Simple development experience as compared to developing with web parts.

In a nutshell this option allows us to build an ASP.Net application outside of SharePoint, build it, test it & then add it to SharePoint. Now, the problem is what are the ways to deploy the ASP .Net application pages into SharePoint and which one is should we go with. Some solutions are listed below:

<!–[if gte mso 9]> Normal 0 21 false false false DE-AT X-NONE X-NONE MicrosoftInternetExplorer4 <![endif]–><!–[if gte mso 9]> <![endif]–>



  1. The SharePoint designer approach: This approach can be used if there are few aspx pages with little functionality.
  2. Using web parts. This can be used in conjunction with SharePoint designer. But once again, developing many web parts is not feasible and also raises performance issues.
  3. _Layouts folder approach: This is the simplest of all. Just deploy the web application pages under the _layouts folder of SharePoint and the pages can be accessed from any SharePoint site. Cons: The pages don’t inherit the security and access rules from SharePoint. The pages can be accessed from any site existing on that server farm. Master Page integration is not possible. MSDN Article explains with a sample.
  4. Similar to solution 3. However we add our dll to Sharepoint bin folder and edit the WSS or MOSS web.config for a new trust level. The detail steps you find above.
  5. User controls using Smart Part: In this approach, the developer can develop web parts using the third party Smart Part control. In this way the developer can have the drag – drop functionality as he/she can develop it as a user control and drop it in the smart part. This method is similar to web parts but the developer has the privilege of drag-drop functionality but it still carries the negatives mentioned for the web parts approach.

Pros and Cons for Solution 2: Custom built Web Parts

With this option you build all your UI using the Web Part framework. Logic etc… can be off in other .Net assemblies or a web service etc… just as you would with any other .Net Application.


  • Built using ASP.Net Web Part framework
  • Deployed via Web Part install package or the new Feature/Solution Deployment mechanism
  • SharePoint application provides hosting framework for “putting” these Web Parts on Web Part pages
  • Communications framework for talking with other Web Parts
  • Designed to be highly re-usable across many sites with little effort


  • No drag and drop UI for laying out your UI i.e. no design time surface
  • A framework that developers must learn to work within

Summary: A good use of web parts would be where you want to build a widget/mini-application that you can put on many web part pages across many sites.

Pros and Cons for Solution 3: layouts application

An _layouts application is when you develop an ASP.Net Web Application and deploy it to the c:\program files\common files\microsoft shared\web server extensions\12\template\layouts  directory. This is a special directory that gets “virtualized” in each sharepoint site i.e. in each sharepoint site you will have an /_layouts path from the root of the web. E.g. http://servername/sites/sitename/_layouts.

This means you can make your application available under each SharePoint site e.g. http://servername/sites/sitename/_layouts/MyApp/SomePage.aspx

In fact this is how all the SharePoint administration pages are delivered in each site.


  • Great way to make your functionality available in every site
  • Easy to develop. It is just like developing a regular ASP.Net web site
  • Context sensitive access to the SharePoint object model. Great for doing work on the site that the user happens to be working in at the time.


  • Cant use the ASP.Net master page of the site context as the _layouts application is a separate ASP.Net application

Summary: It is best to use an _layouts based application when you want to extend every site with some functionality such as additional administration pages.

Detail steps for solution 4:

Create a new Web Application Project from Visual Studio 2005. You need to download web application project extension for this. Open Visual Studio 2005 and select Web Application Project.  You can design this page as you need to handle. Once you are done with designing run the application once to make sure that there is no error.

Add reference to Microsoft.Sharepoint. Leave only Microsoft.SharePoint, System, and System.Web. In the Solution Explorer create folder “~masterurl” and add masterpage “default.master” insid. Then replace code behind for the masterpage with:

using System;
using Microsoft.SharePoint;

namespace CustomNamespace._masterurl

public partial class _default : System.Web.UI.MasterPage

protected void Page_Load(object sender, EventArgs e)



In the SP designer, rename ContentPlaceHolder’s ID to “PlaceHolderMain”and delete Default.aspx, and add new page – SamplePage.aspx. Replace source content with the following:

<%@ Page Language=”C#” MasterPageFile=”~masterurl/default.master” CodeBehind=”SamplePage.aspx.cs” Inherits=”ItDoesWork.SamplePage” Title=”Untitled Page” meta:webpartpageexpansion=”full” meta:progid=”SharePoint.WebPartPage.Document” %>

<asp:Content ID=”Content5″ ContentPlaceHolderID=”PlaceHolderMain” runat=”server”>

Testing Page…

<asp:Label ID=”Label1″ runat=”server” Text=”Label”></asp:Label>


Replace the code behind:

using System;
using Microsoft.SharePoint;

namespace CustomNamespace

public partial class SamplePage : System.Web.UI.Page

protected void Page_Load(object sender, EventArgs e)

Label1.Text = SPContext.Current.Site.Url;


Visual Studio automatically creates a dll in the projects bin filder when starting or debugging the code.  Now go to the file path where you have created the Web Application. You have to copy the dll file to share point site’s bin folder. You usualy find the Shareoint application folder under i.e. C:\Inetpub\wwwroot\wss\VirtualDirectories\moss.litwareinc.com80\bin IIS folder and sreach for your sharepoint application or go to IIS and select your share point site. Right click on the site name and click on Open.

In the next step copy your dll into the Sharepoint bin folder. Now create a new folder with an appropriate name at same level where your SharePoint site’s BIN directory resides and copy your new created aspx page to this folder.Open Web.Config file of Share Point site and copy safe control tag shown below to Web.Config file.

<SafeControl Assembly=”CustomProject” Namespace=”CustomNamespace” TypeName=”*” />

If you have chosen different namespace and assembly names than you have to use your name instead of this.

The last thing is, you have to add <trustLevel> tag in share point sites’s web.Config file. You need to  set trust level to “WSS_Medium”

<trustLevel name=”WSS_Medium” policyFile=”C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\config\wss_mediumtrust.config” />

Thats all you have to do.

Open your share point site in browser and check for newly added page. In our case the link will be http://ServerName:PortNumber/Your Folder/CustomePage.aspx

One of the great things about this option is that you could build your application outside of SharePoint with any old MasterPage, then deploy to SharePoint and swap out the masterpage string for the correct one.  Thus being able to develop and debug outside of SharePoint and then deploy and test inside SharePoint.

A note on debugging:  If you want to debug your code once it is running inside SharePoint then all you need to do is attach the Visual Studio debugger to the correct w3wp.exe process (Debug -> Attach to process), set your break points and then hit your page in a browser.


  • Simple development experience. Develop outside SharePoint first if desired.
  • You get a design surface to build you UI
  • Deployment reasonably straight forward


  • Deployment not managed via Solution deployment mechanism Out of the Box. ( but this might be possible i have not tried it yet)
  • Slightly different deployment of User Control files and assemblies (but nothing a .bat file can’t fix) during development.

Pros and Cons for Solution 5: User Controls and the Son of SmartPart

The last option is to build your applications UI in ASP.Net User Controls as you would with any other ASP.Net Web Application and then use the Son of SmartPart to deliver those User Controls via a web part.

The Son of SmartPart is a Web Part that is able to “host” an ASP.Net 2.0 User Control. For more info on this see:


  • Simple development experience.
  • You get a design surface to build you UI
  • Deployment reasonably straight forward
  • Can use Web Part connection framework if desired

Might be possible to develop these outside of SharePoint first (depending on if they have dependencies to SharePoint).


  • Deployment not managed via Solution deployment mechanism Out of the Box (you could build a solution to deploy the Son of Smart Part)

Slightly different deployment of User Control files and assemblies (but nothing a .bat file can’t fix) during development.

Summary: I think this is a great option when you want to build a rich browser based UI that you only want to use in one (or a couple) of sites. I don’t think this is a good option if you want to build a mini-application that you want to include on many sites. A better option in that case might be a Web Part.

Decision matrix

Single Site Some Sites Many Sites
Per site functionality Smart Part Smart Part or Web Part Web Part
Single instance application Smart Part or add ASPX pages to site N/A N/A
Site extension functionality Web Part Web Part _Layouts application

More Information:

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


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: