Intro to SharePoint Development: How to Build and Deploy a Web Part

Posted Wednesday, October 22, 2008 7:50 AM by CoreyRoth

UPDATE: Building Web Parts in SharePoint 2010

I've recently helped out a number of developers new to SharePoint and I found that I have been often asked the same types of questions.  Most of those involve getting started and deployment, so today, I am beginning my series on getting started with SharePoint.  Most new developers find starting out pretty overwhelming, but once you get used to it, it does all make sense.  Hopefully this post will help the community and keep new SharePoint developers from getting scared off.  There have been a lot of posts on this topic I admit.  Since there are so many ways to do things, I wanted to write this post as a reference to new developers so they can see how I usually do things.  What I find is that most developers have no trouble getting a web part built, but when it comes time to deploy it, they are lost.  There are multiple ways to do this and not all of them are necessarily the right way.

Environment

Let's start by talking about your development environment.  In an ideal situation, you probably have your own virtual machine with Windows Server 2008 (or 2003), MOSS 2007, and Visual Studio 2008 installed.  However, maybe you don't have your own dedicated machine and you are going to be developing on a Windows XP machine, but deploying to a remote SharePoint server.  This is fine, but you are going to have to do some things a little differently.  First, you won't be able to install the Visual Studio Extensions for SharePoint.  You can live without this though because most people I have ran into say they don't use them.  Secondly, when it comes to deployment (which we'll talk about down below), you are going to have to copy your source files (either manually or via solution package) to the server.  You are also going to have to remote debug but fret not my post on it makes it easy.

If you are developing on a desktop, another thing you will need to do is copy the SharePoint assemblies to your computer.  We can easily get these from a deployed SharePoint server.  However, this is a great time to take an aside and talk about some of the SharePoint directory structure.

C:\Program Files\Common Files\microsoft shared\Web Server Extensions\12

All SharePoint developers have that file path permanently burned into their memory.  It is often referred to as the 12 hive.  A lot of things happen within this folder.  Subfolders here contain the SharePoint binaries, Master Pages, Application Pages, User Controls, Configuration Files, and Features.   Although SharePoint will let you customize any file in here, in general you don't want to make changes to any of these builtin files as it puts you in an unsupported scenario.  If you want to customize a master page or a style, it is typically best that you make a copy of what you want to customize and go from there.  Here is a quick list of some of the key folders and what they are used for.

Folder Description
CONFIG Contains partial trust configuration files
ISAPI Binaries and SharePoint Web Services
LOGS Error Logs (look here first when you get a strange error)
TEMPLATE\CONTROLTEMPLATES User Controls
TEMPLATE\FEATURES SharePoint Features (turns functionality on and off)
TEMPLATE\IMAGES MainImages Folder
TEMPLATE\LAYOUTS Pages and Styles
TEMPLATE\SiteTemplates Definitions avaiable for deploying new sites
TEMPLATE\THEMES Used to create custom themes in SharePoint
TEMPLATE\XML Contains XSDs for any XML used with SharePoint

Enough on that tangent, back to the assemblies that we need to copy.  Go to the above path and then go into the ISAPI folder.  Copy all of the DLLs from this folder onto your desktop machine in the corresponding folder name.  If you don't have that folder, create it.  You may also copy them to the Global Assembly Cache as well.  Once you are this point, you are ready to being building a web part.

Coding the Web Part

Start by creating a new class library project in Visual Studio.  There are packages and tools out there to automate some of these steps, but its best that you learn how to do it first by hand, so you know how to troubleshoot it should something go wrong.  Next, you will want to add (at a minimum) a reference to Microsoft.SharePoint.dll.  You can either grab it out of the GAC (will be listed under Windows SharePoint Services) or use the copy that you put in your ISAPI folder.  After you add it, make sure Copy Local is set to false on your reference.  You will also want to add System.Web since more than likely your web part will use an ASP.NET control in it.  You are now ready to create your web part.  To do this, create a new class and add a using statement for Microsoft.SharePoint.  In the past, you would derive your class from Microsoft.SharePoint.WebPart (and you still can), but now the more accepted way of doing things is to derive from the new System.Web.UI.WebParts.WebPart class.  The latter comes from ASP.NET 2.0 and can actually be deployed outside of SharePoint.  Here is what our class is going to look like.

public class TestWebPart : System.Web.UI.WebControls.WebParts.WebPart

{

    protected override void CreateChildControls()

    {

        base.CreateChildControls();

        Controls.Add(new Label(){Text = "My Test Web Part (Hello World)!"});

    }

}

The content of the class is simple.  We use the overridden CreateChildControls method to add ASP.NET controls to the page to do the rendering.  I simply call Control.Add and add a Label control with the text above.  Compile it and this web part is good to go, but there is the small matter of deploying it.  Compiling it yield you a DLL that has be deployed to SharePoint somehow.  SharePoint also needs to know where the web part is and how to reference it.  This is where the .webpart file comes in.

Describing the WebPart

The .webpart file is an XML file that tells SharePoint what to call your DLL and what assembly it is located in.  The easiest way to get started creating this file is to copy another one in SharePoint.  You can find plenty of examples by going to your web part gallery (Site Root -> Site Settings -> Web Parts).  this file simply describes the class and assembly of your web part as well as some default properties (i.e.: it sets a title and description).  You can also add your own properties by specifying a series of attributes on a property in your class.

<webParts>

  <webPart xmlns="http://schemas.microsoft.com/WebPart/v3">

    <metaData>

      <type name="MyWebPart.TestWebPart, MyWebPart, Version=1.0.0.0, Culture=neutral" />

      <importErrorMessage>Cannot import this Web Part.</importErrorMessage>

    </metaData>

    <data>

      <properties>

        <property name="Title" type="string">My Web Part</property>

        <property name="Description" type="string">A test web part.</property>

      </properties>

    </data>

  </webPart>

Note: There is also a .dwp file, which comes from version 2, that can describe your webpart as well.  It still works but it is consider deprecated.

Ghetto Deploying

So far, we have built a web part and created a .webpart file so now it is time to deploy it.  We'll start by doing it the wrong way.  The first thing to know is that you can't just copy your DLL into the bin folder of your web application unless you change to full trust (not recommended) or specify Code Access Security.  Specifying CAS when first starting out will make even the most seasoned developers run for the hills.  So we are going to start by deploying to the GAC.  In almost all situations, I recommend against this, but for the sake of getting you started, it is ok.  You can then follow the Code Access Security post later on how to set up everything properly.

Start by copying your compiled DLL into the Global Assembly Cache of your SharePoint server.  Keep in mind anytime you update this DLL, you will need to either reset IIS or recycle the application pool (otherwise the old version stays in memory).  The next thing you need to do is upload the .webpart file to the web part gallery of your site collection (again Site Root -> Site Settings -> Web Parts).  At this point, SharePoint will be able to recognize your web part and it can be added to a page.  If you click on the name of the web part in the gallery (in this case MyWebPart.webpart), it will display a preview of what it will look like on a page.  If everything is working correctly, you will see your web part, otherwise you will get an error.  At this point, you will have the following error.

A web part on this web part page cannot be displayed or imported because it is not registered on this site as safe.

This is because there is one more step to do.  Every web part or user control in SharePoint must be registered as safe to execute in the web.config.  To do this, find the SafeControls element near the top and add the following line (changing it with your fully qualified assembly path).

<SafeControls>

  <SafeControl Assembly="MyWebPart, Version=1.0.0.0, Culture=neutral" Namespace="MyWebPart" TypeName="*" Safe="True" />

</SafeControls>

Now when you go back to the web part gallery, it should give you a preview of your web part.  If it doesn't check your assembly paths and make sure the file is deployed.  If you still have issues, check out this post on troubleshooting a web part.  Assuming you were able to get the web part to preview, you can also go add it to a page by going to any page, clicking Edit Page and then Add Web Part.  Scroll through the list until you find your web part and select it.  You should then see your web part on the page.

Features

So we talked about deploying a web part the wrong way.  Ok, it's not necessarily wrong, but it really adds a lot of extra work  This can be automated quite a bit by using features and solution packages.  Creating a feature, allows you to turn on and off customizations to SharePoint at the click of a button.  They can be used to deploy web parts, site definitions, workflows, document libraries, and plenty of other things.  In this case, we are building a feature to automate the deployment of our .webpart file.  You can also specify a class (Feature Receiver) that is executed when the feature is installed, activated, deactivated, or uninstalled.  A feature typically consists of two XML files.  The first file Feature.xml (must be named that), describes the feature and where its feature receiver is (if any). 

<Feature

    xmlns="http://schemas.microsoft.com/sharepoint/"

    Id="{BDD425C3-CA50-4aee-9170-73954044D764}"

    Scope="Site"

    Hidden="False"

    Title="My Web Part"

    Description="My Test Web Part"

    >

  <ElementManifests>

    <ElementManifest Location="Elements.xml" />

  </ElementManifests>

</Feature>

The Id element contains a GUID.  Every feature needs a different one.  The Scope attribute specifies where to deploy the feature.  Possible values are Site, Web, WebApplication, and Farm.  I would go into the difference in scopes, because this post is already getting long enough.  You will most likely use Site or Web for most things you do (note on terms in API).  The ElementManifest element makes calls to additional XML files.  Typically the other file is called Elements.xml (although it can be called anything).

The Elements.xml file can be used to deploy files, create document libraries, and many other functions.  I won't go into the whole detail of this file (it's in the SDK), but basically we are specifying that the MyWebPart.webpart file should be copied into the web part gallery.  I will tell you what a few things are though.  In this case the Module element says that we are going to deploy something into a list that is located at _catalogs/wp (this is the URL of the web part gallery).  How did I figure this out?  I looked at another example.  The File element deploys our MyWebPart.webpart file into the web part gallery.  I wont go into why you set the Type to GhostableInLibrary right now.  Just know this is the value you will pretty much always use.

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">

  <Module Name="WebPartPopulation" List="113" Url="_catalogs/wp" RootWebOnly="TRUE">

    <File Url="MyWebPart.webpart" Type="GhostableInLibrary" />

  </Module>

</Elements>

When the feature is activated, it will put the file in the web part gallery.  However, it won't remove the item from the web part gallery on deactivation.  It's pretty easy to do with code and I still plan to write a post on it.  For now, if you want the .webpart file gone you will have to delete it manually.  During the development cycle though, the only time it really is necessary to remove a .webpart file is if you have changed the namespace, class name, or public key token.  Here is what an elements file typically looks like for deploying a web part.

So where do all these files go?  Let's talk about where you put them in your Visual Studio project first.  Typically, what you will do is create a folder structure in your project that matches the 12 hive.  So in this case, we will create a TEMPLATE\FEATURES folder.  We will then create a folder for our web part.  I am just calling it MyWebPart for now.  Here is what your solution will look like.  This folder is where you will put Feature.xml, Elements.xml, and MyWebPart.webpart.

image

To deploy the feature, copy it to the TEMPLATE\FEATURES folder in your 12 hive.  You then need to use stsadm command to install it.  The stsadm executable is located in the bin folder of the 12 hive.  You tend to use it a lot, so you might want to put it in your path environment variable.  Once you have located it, issue the following command.

stsadm -o installfeature -name MyWebPart

This makes the feature available to be activated.   To activate it, go to Site Collection Features (Site Root -> Site Settings -> Site Collection Features).  Find the feature in the list and click the Activate button.  This deploys the web part to the gallery and it can be added to pages as before.  If you ever want to remove the feature, use the uninstallfeature operation.  You will want to deactivate the feature first, otherwise you will have to use the -force parameter when using stsadm.

Deploying Via Solution Package

Features are nice, but we can take this one step further.  A solution package (.wsp file) allows you to package your entire solution into one .wsp file for deployment.  A .wsp file is simply a cab file with a manifest.xml file that tells SharePoint how to install the contents.  It will even deploy and install your feature for you, allowing you to skip the installation steps above.  Two files are required to build the .wsp file: cab.ddf and manifest.xml.  These files typically go into a folder called Solution in your Visual Studio project.  Cab.ddf tells the utility, makecab.exe, how to construct the .wsp file.   Below is an example DDF file.  You will need to set the CabinetNameTemplate to the filename you want for your wsp file.  You then specify a source and destination for each file you want copied.  In the example below, note that I am copying the DLL, Elements.xml, Feature.xml, and MyWebPart.webpart file. 

; ** MyWebPart.wsp **

.OPTION EXPLICIT    ; Generate errors

.Set CabinetNameTemplate=MyWebPart.wsp

.set DiskDirectoryTemplate=CDROM ; All cabinets go in a single directory

.Set CompressionType=MSZIP;** All files are compressed in cabinet files

.Set UniqueFiles="ON"

.Set Cabinet=on

.Set DiskDirectory1=Package

 

Solution\manifest.xml manifest.xml

 

; binary

bin\debug\MyWebPart.dll MyWebPart.dll

 

; feature files

TEMPLATE\FEATURES\MyWebPart\Elements.xml MyWebPart\Elements.xml

TEMPLATE\FEATURES\MyWebPart\Feature.xml MyWebPart\Feature.xml

 

; web part files

TEMPLATE\FEATURES\MyWebPart\MyWebPart.webpart FEATURES\MyWebPart\MyWebPart.webpart

I won't go into manifest.xml again because I have already covered it once in this post.  It's this file that tells SharePoint how to deploy features, copy files, setup code access security, and add SafeControl entries to your web.config.  Once you create your solution files, build your project and then go to the command line.  The utility makecab.exe (should already be on your system) will actually create the wsp file.  In the command prompt, go to the root folder of your project and execute the following command.  It has to be executed from that folder because all of the paths are relative.

makecab.exe /f solution\cab.ddf

You can automate this step when you build, by creating a build action.

If you are working on a remote server, you will need to copy the .wsp file onto the server. Add and deploy the solution with the following commands.

stsadm -o addsolution -filename package\MyAssembly.wsp
stsadm -o deploysolution -name MyAssembly.wsp -immediate -allContentUrls -allowGacDeployment
stsadm -o execadmsvcjobs

At this point if all goes well, your solution will be installed and deployed.  This eliminates all the steps of manually copying files into SharePoint.  You can then activate your feature like before (remember it installs the feature for you) and add your web part to a page.  If you make an update to your web part, deploying is easy, just use the upgradesolution stsadm command and it will update all the files in your solution.  Should you decide, you don't need the solution any more, use the retractsolution command.  After you issue either of those commands, you will need to follow it up with a execadmsvcjobs command as shown above.

This may sound like a lot, but it really isn't bad.  It makes deployment really easy (especially to other servers).  Once you have your solution deployed and you want to make an update, you can also just directly copy out the binary to your server.  Not really a best practice, but it does speed things up quite a bit, since stsadm commands take a few seconds to run.

Once you get the hang of it and are familiar with the deployment process, you really need to consider deploying your solution to the bin folder by deploying your solution under partial trust.  Remember right now, you are deploying to the GAC which is not ideal.  My post on Code Access Security walks you through the whole process and provides more details on how solution packages are built.

User Controls

By now, you may be thinking, I went through all of that and I still have to render stuff to the screen using straight code?  I hear you.  It's not any fun at all and can be a controversy among some SharePoint developers.  You do have a couple of alternatives, use the SmartPart or write your own.  I typically go with the latter.  This simple web part uses Page.LoadControl to load the .ascx file you specify.

This is quickly becoming the longest post I have ever written.  I've attached the code I used in this post.  You can use it to verify that you put your own web part together correctly or you can use it as a starting point.  I hope this provides enough information for a new SharePoint developer to get started.  I certainly wish I had this much info condensed in one place when I was starting out.  You may also want to check out one of the many solution generating tools out there such as stsdev.  Please leave a comment if this helps or if you have any questions.  If I am missing anything or you think I need to add anything, also please let me know.

Comments

# Links (10/23/2008) &laquo; Steve Pietrek - Everything SharePoint

Thursday, October 23, 2008 7:41 PM by Links (10/23/2008) « Steve Pietrek - Everything SharePoint

Pingback from  Links (10/23/2008) &laquo; Steve Pietrek - Everything SharePoint

# Remote Development, Deployment, and Remote Debugging your first SharePoint 2007 Program &laquo; Stuff I geek with

Pingback from  Remote Development, Deployment, and Remote Debugging your first SharePoint 2007 Program &laquo; Stuff I geek with

# Learning SharePoint – Part I

Tuesday, January 20, 2009 5:42 PM by Colby Africa

I am on a special project that requires I do a deep dive into SharePoint and fast.&#160; I told my director

# re: Intro to SharePoint Development: How to Build and Deploy a Web Part

Friday, January 15, 2010 4:37 AM by Sanjay

Thanks Corey. This really helped me. Keep the good work going :)

# re: Intro to SharePoint Development: How to Build and Deploy a Web Part

Sunday, January 24, 2010 7:30 AM by SPMurugesa Pandian

Corey ,Wonderful piece !.It boost my learning spirit.!

# re: Intro to SharePoint Development: How to Build and Deploy a Web Part

Tuesday, February 16, 2010 10:20 PM by Preet

Absolutely amazing...!! Marvelous.... No words to describe it...You have down superb job. People like you are required not only in SharePoint Community but required in world. Thanks for sharing such valuable knowledge.

# re: Intro to SharePoint Development: How to Build and Deploy a Web Part

Wednesday, February 17, 2010 9:32 AM by CoreyRoth

Thanks for the great comments.  I'm glad people are finding it useful.

# re: Intro to SharePoint Development: How to Build and Deploy a Web Part

Friday, February 19, 2010 7:17 AM by Jeannie

I'm trying to deploy to a remote server from my build server utilizing the command line, which will placed in CCNet file.  When I attempt stsadm -o addsolution -filename package\MyAssembly.wsp, I am receiving the ominous "Object not set to the instance of an object.  Solution was not added" msg.  Any ideas?

# re: Intro to SharePoint Development: How to Build and Deploy a Web Part

Friday, February 19, 2010 9:49 AM by CoreyRoth

Hmmm, it sounds like there is something inside your solution package SharePoint doesn't like.  Unfortunately, you may have to sift through the logs in 12\LOGS to find out what the actual error is.

# Sharepoint : Various way to develop WebPart in Sharepoint &laquo; Nair&#039;s Blog

Pingback from  Sharepoint : Various way to develop WebPart in Sharepoint &laquo;  Nair&#039;s Blog

# re: Intro to SharePoint Development: How to Build and Deploy a Web Part

Monday, May 10, 2010 12:06 PM by Nandakumar

Rock on

# re: Intro to SharePoint Development: How to Build and Deploy a Web Part

Thursday, May 13, 2010 1:49 PM by StephanieDeHart

As a complete SharePoint newbie, I needed more detail for your instruction to "start by copying your compiled DLL into the Global Assembly Cache of your SharePoint server".

In order to install my assembly into the GAC, I had to sign it.  In Project Properties, on the Signing tab, check the option for Sign the assembly, and enter a filename ending with the .snk file extension.  I didn't use the option to enter a password.

Awesome instructions!  VS 2008 really did make deployment easier.  This is probably the only time I'll deploy the "ghetto" (i.e. manual) way, but I am glad I've done it to help with troubleshooting.

Thanks!

# re: Intro to SharePoint Development: How to Build and Deploy a Web Part

Thursday, May 13, 2010 1:58 PM by CoreyRoth

@StephanieDeHart  Thanks for the feedback!

You're right, I guess I did make the assumption that the developer has some prior experience doing .NET applications.  Thanks for the good comments.  I'll probably include that point when I update the post.

# Twitter Trackbacks for http://www.dotnetmafia.com/blogs/dotnettipoftheday/archive/2008/10/22/intro-to-sharepoint-development-how-to-build-and-deploy-a-web-part.aspx?CommentPosted=true [dotnetmafia.com] on Topsy.com

Pingback from  Twitter Trackbacks for                 www.dotnetmafia.com/.../intro-to-sharepoint-development-how-to-build-and-deploy-a-web-part.aspx         [dotnetmafia.com]        on Topsy.com

# re: Intro to SharePoint Development: How to Build and Deploy a Web Part

Friday, June 18, 2010 5:33 PM by Sri

Thanks Corey, it helped in preparing for my interview.

# Build and Deploy A User Control In Sharepoint &laquo; Sladescross&#039;s Blog

Pingback from  Build and Deploy A User Control In Sharepoint &laquo; Sladescross&#039;s Blog

# re: Intro to SharePoint Development: How to Build and Deploy a Web Part

Wednesday, December 22, 2010 3:44 PM by Sam

Absolutely great article. One of the best on the internet for Webpart building and deployment. Thanks a ton!

# Buzz Lightyear is here &raquo; Blog Archive &raquo; links for 2011-01-06

Pingback from  Buzz Lightyear is here  &raquo; Blog Archive   &raquo; links for 2011-01-06

# Creating a Solution Package in Windows SharePoint Services 3.0 &laquo; Dot Net Solutions

Pingback from  Creating a Solution Package in Windows SharePoint Services 3.0 &laquo; Dot Net Solutions

# Creating a Solution Package in Windows SharePoint Services 3.0 &laquo; Dot Net Solutions

Pingback from  Creating a Solution Package in Windows SharePoint Services 3.0 &laquo; Dot Net Solutions

# re: Intro to SharePoint Development: How to Build and Deploy a Web Part

Sunday, February 13, 2011 9:59 PM by Dave

Thank you so much for sharing. But my environment is VS2005 and SP2007, is it working in this way?

# re: Intro to SharePoint Development: How to Build and Deploy a Web Part

Monday, February 14, 2011 8:41 AM by CoreyRoth

@Dave Yes, VS2005 will work pretty much the same way.  However, I would point out that there is absolutely no excuse to be still running VS2005.  The product is now 6 years old.

www.dotnetmafia.com/.../people-it-s-time-to-upgrade-to-visual-studio-2008.aspx

# re: Intro to SharePoint Development: How to Build and Deploy a Web Part

Monday, April 4, 2011 3:47 AM by Jiten

Thanks Corey. Although I have previously developed webparts, your blog comes in handy when I have to brush up the steps once in a while. A well composed quick guide.

# re: Intro to SharePoint Development: How to Build and Deploy a Web Part

Tuesday, April 5, 2011 11:31 PM by Amit

Nice article for beginners!! Thanks for the good work.. keep posting such nice articles...

# re: Intro to SharePoint Development: How to Build and Deploy a Web Part

Friday, June 3, 2011 2:30 AM by Syahri

SIr...you just save a greenhorn like me from getting kicked out his job...wonderful article...thanks :)

# re: Intro to SharePoint Development: How to Build and Deploy a Web Part

Friday, July 15, 2011 4:25 AM by andy b

awesome article .thanks

# re: Intro to SharePoint Development: How to Build and Deploy a Web Part

Saturday, July 23, 2011 12:42 AM by Kishan

No Words... i am searching this type of post from a long time...

Absolutely amazing...!! Marvelous...I am very thankful you shared such a important knowledge...

Thanks Again...

Kishan

# WebParts by sithram - Pearltrees

Sunday, January 8, 2012 6:11 AM by WebParts by sithram - Pearltrees

Pingback from  WebParts by sithram - Pearltrees

# re: Intro to SharePoint Development: How to Build and Deploy a Web Part

Thursday, April 5, 2012 1:54 PM by Sachin

Very nice article Corey, It was very Helpful..

# re: Intro to SharePoint Development: How to Build and Deploy a Web Part

Monday, April 16, 2012 1:40 AM by aamy

awesome......

# re: Intro to SharePoint Development: How to Build and Deploy a Web Part

Monday, July 23, 2012 11:17 PM by Suresh

Thanks Corey for nice article. Its very helpful for me.

# Hows to deploy .dwp file as a feature in sharepoint | Zener Answers

Pingback from  Hows to deploy .dwp file as a feature in sharepoint | Zener Answers

# How to generate wsp for master page what i created in designer and how it deploy into sharepoint site? | Zeliff Answers

Pingback from  How to generate wsp for master page what i created in designer and how it deploy into sharepoint site? | Zeliff Answers

# How To Build And Deploy Web Part Sharepoint 2007 | Adsense

Pingback from  How To Build And Deploy Web Part Sharepoint 2007 | Adsense

# Learning SharePoint &ndash; Part I | Colby Africa

Tuesday, March 1, 2016 10:59 PM by Learning SharePoint – Part I | Colby Africa

Pingback from  Learning SharePoint &ndash; Part I | Colby Africa

Leave a Comment

(required) 
(required) 
(optional)
(required)