Corey Roth [MVP] : Deployment

Making changes to SharePoint the quick and dirty way (Ghetto Deployment)

CoreyRoth — Wed, 05 Aug 2009 16:04:06 GMT

So you become a pro SharePoint developer, you’re great at making solution packages, but now you’re feeling lazy and want to cut out a few steps when you’re just making some changes during development. This post is for you. In reality, the best way to deploy your web parts and other custom code is using a solution package with a feature. Deploying solution packages can take quite a bit of time. If you’re just changing one line of code, do you really need to go through the hassle of deploying a solution package every time? The answer is in fact no as long as you are careful and are willing to deal with the consequences should anything go wrong. Most of the scenarios we are talking about today assume you have a solution package built and you have deployed it at least once. We’re just talking about how you can make development faster on subsequent code changes.

One thing I will point out before we start is that if you are in a farm environment, your changes must be deployed to all front end servers.

Web Parts

Updating a web part is pretty simple. All you need to do is copy the assembly to wherever you deployed it to (GAC or bin folder). Your .webpart file does not need to be updated unless you have made changes to it.

Web Parts Deployed to the GAC

Although, I try to put as little in the GAC as possible, some things just have to go there. If you have made a change to your web part’s code, you can easily just copy the assembly out of your project and put it straight in the GAC via the C:\Windows\Assembly folder. Don’t forget that SharePoint caches assemblies in the Global Assembly Cache, so you need to recycle your application pool of any web application that is using your web part on each front end server. You can just do an iisreset, but an application pool reset is a bit faster.

Web Parts Deployed to the bin folder

If you are deploying to the bin folder, ghetto deployment is even easier. Just copy out the DLL to the bin folder of your web application and you are good to go. No application pool reset is necessary. If you do make significant changes and your code requires different permissions, then you will need to deploy with your solution package so that you can specify an updated CAS policy.

Pages and User Controls

If your code behind changes, then the rules above for web parts apply. Just copy out the binary to the deployment location. If you made changes to a .aspx or .ascx file, these files can simply be copied out to the 12 hive (LAYOUTS folder for pages and CONTROLTEMPLATES folder for controls).

Event Receivers

The binaries for your event receivers can also be copied out directly to the GAC. Just like with web parts, remember to reset your application pool to avoid caching issues.

Workflow

Workflow can also be deployed directly to the GAC. If you have any changes to what forms are registered or anything else you will need to deploy it regularly though.

Some of this may have seemed obvious, but I have had a few developers ask me questions like this when starting out. Of course if anyone goes wrong, just start open, retract your solution and redeploy it the correct way. Hopefully, though you can use some of these tips to speed up development when you are making lots of changes. No one likes to sit there and wait for a solution to deploy. Have any other tips? Leave a comment.

How to: Deploy a Page using a Feature

CoreyRoth — Tue, 02 Jun 2009 20:58:23 GMT

I am about to do start giving some training again, so I thought I would work on some more content for the blog that I could refer to people to when they are trying things out. Today, I want to start out with the basic task of deploying a page to SharePoint. There are actually lots of ways to get pages into SharePoint. You can use the whole page publishing model in MOSS, but sometimes you just need a simple page with a simple web part deployed and a feature makes this task pretty easy.

For today’s example, I want to deploy a simple page with a web part or two on it. To start, you will need to create a new folder for your feature. You can name this whatever you want. For the purpose of this example, we’ll call it PageTest. Before we begin though we need a .aspx page which will host these web parts. You can create one on your own, but I find it’s easiest to just “borrow” one from SharePoint that already exists. A good one to borrow I have found is in the STS site template (12\TEMPLATE\SiteTemplate\STS) called default.aspx. This .aspx page has two WebPartZones named Left and Right. Put a copy of this file into your new feature folder. You can customize this file however you desire, such as changing the layout or adding or subtracting WebPartZones.

By now, I am sure you probably know how to make a basic Feature.xml file, but here is one just in case. In this case, we have a feature with a scope of Web so we’ll be deploying to an individual site.

<Feature
    xmlns="http://schemas.microsoft.com/sharepoint/"
    Id="{8B486B2B-4D71-423f-BD6C-9C792299F432}"
    Scope="Web"
    Hidden="False"
    Title="PageTest"
    Description="Deploys a custom page with some web parts."
    >
  <ElementManifests>
    <ElementManifest Location="elements.xml" />
  </ElementManifests>
</Feature>

The Elements.xml file deploys files using the Module and File elements. The Module element tells SharePoint to deploy files from a physical folder, specified in the Path attribute, to a virtual folder inside SharePoint, specified in the Url attribute. The Path attribute is relative to the feature folder while the Url attribute is relative to the site it was deployed on. No paths are specified in our case.

<Module Name="Pages" Path="" Url="">

The Module element can contain one or more File elements to deploy pages. You need one File element for each page you want to deploy inside of SharePoint. Note: that it is possible to use the same default.aspx page in your feature folder and deploy it multiple times with different web parts (i.e.: page1.aspx, page2.aspx, etc.).

<File Name="TestPage.aspx" Url="default.aspx" IgnoreIfAlreadyExists="FALSE" NavBarHome="True">

The Name attribute specifies the name the file will be called inside SharePoint. The Url specifies the name of the file in your feature folder. In our case, default.aspx. The confusing part her of course being that Url in the Module element refers to the path inside SharePoint and on the File element it refers to the name of the file in your feature folder.

For each page that you can deploy, you can use CAML to automatically add web parts to the page. To do this, you use the AllUsersWebPart element. Remember in the page we had WebPartZones named Left and Right? We use those same Ids here, to specify which zone to add the web part too. The WebPartZoneOrder element specifies the order in which the web parts are added to a given zone (you can have multiple web parts in a zone and they will stack). The definition of the web part goes inside a CDATA element inside the AllUsersWebPart element. If you built the web part yourself, you can just paste in the XML from your .webpart file. If you are using an out-of-the-box SharePoint web part, you can add it to an existing page and export it or go to the web part gallery and export it. Here is what a completed file looks like with multiple web parts.

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Module Name="Pages" Path="" Url="">
    <File Name="TestPage.aspx" Url="default.aspx" IgnoreIfAlreadyExists="FALSE" NavBarHome="True">
      <AllUsersWebPart WebPartZoneID="Left" WebPartOrder="1">
        <![CDATA[
          <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>
          </webParts>
        ]]>
      </AllUsersWebPart>
      <AllUsersWebPart WebPartZoneID="Left" WebPartOrder="2">
        <![CDATA[
        <WebPart xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://schemas.microsoft.com/WebPart/v2">
          <Title>Search Box</Title>
          <Description>Used to search document and items.</Description>
          <MissingAssembly>Cannot import this Web Part.</MissingAssembly>
          <Assembly>Microsoft.SharePoint.Portal, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c</Assembly>
          <TypeName>Microsoft.SharePoint.Portal.WebControls.SearchBoxEx</TypeName>
          <GoImageUrl xmlns="urn:schemas-microsoft-com:SearchBoxEx">/_layouts/images/gosearch.gif</GoImageUrl>
          <GoImageUrlRTL xmlns="urn:schemas-microsoft-com:SearchBoxEx">/_layouts/images/goRTL.gif</GoImageUrlRTL>
          <GoImageActiveUrl xmlns="urn:schemas-microsoft-com:SearchBoxEx">/_layouts/images/gosearch.gif</GoImageActiveUrl>
          <GoImageActiveUrlRTL xmlns="urn:schemas-microsoft-com:SearchBoxEx">/_layouts/images/goRTL.gif</GoImageActiveUrlRTL>
          <DropDownModeEx xmlns="urn:schemas-microsoft-com:SearchBoxEx">ShowDD</DropDownModeEx>
          <ScopeDisplayGroupName xmlns="urn:schemas-microsoft-com:SearchBoxEx">Search Dropdown</ScopeDisplayGroupName>
          <RegisterStyles xmlns="urn:schemas-microsoft-com:SearchBoxEx">true</RegisterStyles>
          <ShouldTakeFocusIfEmpty xmlns="urn:schemas-microsoft-com:SearchBoxEx">false</ShouldTakeFocusIfEmpty>
        </WebPart>
        ]]>
      </AllUsersWebPart>
      <AllUsersWebPart WebPartZoneID="Right" WebPartOrder="1">
        <![CDATA[
                   <WebPart xmlns="http://schemas.microsoft.com/WebPart/v2" xmlns:iwp="http://schemas.microsoft.com/WebPart/v2/Image">
                        <Assembly>Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c</Assembly>
                        <TypeName>Microsoft.SharePoint.WebPartPages.ImageWebPart</TypeName>
                        <FrameType>None</FrameType>
                        <Title>$Resources:wp_SiteImage;</Title>
                        <iwp:ImageLink>/_layouts/images/homepage.gif</iwp:ImageLink>
                        <iwp:AlternativeText>$Resources:core,sitelogo_wss;</iwp:AlternativeText>
                   </WebPart>
                   ]]>
      </AllUsersWebPart>
    </File>
  </Module>
</Elements>

When SharePoint is deploying the page, it combines your .aspx page with what is in the elements.xml file to output the completed page. At this point you are ready to install and activate your feature. You can put this in a solution package at this point to ease deployment. When you activate the feature, you should get something that looks like this.

Of course, deactivating the feature won’t remove this page or its web parts. However, you can always easily implement a feature receiver to cleanup the files you deployed. This is how you deploy simple pages using CAML. This is effectively the same way that Site Templates deploy pages as well (except the web parts and views are defined in onet.xml instead).

Speaking at SharePoint Saturday Tulsa this weekend

CoreyRoth — Mon, 23 Mar 2009 18:01:19 GMT

I am excited to see that SharePoint Saturday is coming to Tulsa this Saturday 3/28. We look to have a lot of good local speakers plus several from out of town as well. I am giving my talk on deployment that I gave at SharePoint Saturday Kansas City. I recommend this talk for anyone starting out with SharePoint since deployment is one of the most difficult concepts to grasp.

For those of you that were at Tech Fest last year, you might have heard about the epic Beer and Code event brought to you by DotNetMafia. Well the godfather himself has declared that the DotNetMafia is doing it again for SharePoint Saturday. Beer and Code will be at Dirty’s Tavern (just like last time) located at 325 E 2nd St (2nd and Elgin – Downtown Tulsa). There is even a pizza place next door now, so if I can pick up a sponsor by the end of the week, I’ll get us some to bring over to Dirty’s. We’ll see you all there.

Slides from my talk at SharePoint Saturday in Kansas City

CoreyRoth — Mon, 09 Feb 2009 15:48:00 GMT

On Saturday, I had the opportunity to speak at SharePoint Saturday in Kansas City. It was a fun event with a pretty good turnout and I had the opportunity to meet lots of new people. I gave a new talk on Deploying Code in SharePoint. The talk focused on walking you through building a solution package from scratch. Slides and sample code are attached at the bottom of this post. I was able to catch sessions from Matt Bremer, Dennis Bottjer / David McCullough, and Becky Bertram. All in all it was very informative. The facilities at Centriq are pretty good, although the one major thing lacking is a large room to handle the welcome / prize giveaways. I also ran into David Walker, who told me that School of Dev / SharePoint Saturday Tulsa would be on 3/28 (I think).

Here is a brief list of posts that I have written about various topics relating to deployment.

Thanks again to Becky Isserman for allowing me to speak as well as heading up the whole SharePoint Saturday event.

Introduction to SharePoint Development: Deploy a User Control in SharePoint

CoreyRoth — Tue, 18 Nov 2008 20:07:58 GMT

A common question I get with new SharePoint developers is "How do I deploy my user control in SharePoint?". Many times they know of the SmartPart or even how to make their own, but its the matter of deploying things that may not be clear. Before starting this, you need to read how to build and deploy a web part. Many of the concepts in that article are used here and explained in more detail.

To build a user control, you start in very much the same way as you do with regular ASP.NET. My recommendation is to start by creating a web application project. You can also use a regular class library, but its easier if you use a web application project since it has the file types you need as well as references. If you already have a class library, you can easily convert it to a web application project using a hack.

Once you have a web application project, create your user control as normal. Build the project and then its time to deploy. We'll first talk about where the files go on the server and then we'll look at how we can get the files there with a solution package. Let's assume, I have a control called MyControl.ascx. This file has to be deployed to the SharePoint server along with its binary. If you are using a SmartPart, the ascx file to go is in a folder called UserControls located in the root of your web sites folder (by default c:\inetpub\wwwroot\wss\VirtualDirectories\80). However with true SharePoint development you have to break the my controls go in X folder on my site way of thinking. In SharePoint, everything is designed to be modular no matter how many web applications your server hosts.

I recommend creating your own web part to host your user control that will work with any folder. SharePoint itself puts all user controls in the CONTROLTEMPLATES folder in the 12 hive (C:\Program Files\Common Files\microsoft shared\Web Server Extensions\12). You can place your controls here as well, but I recommend creating a subfolder here to keep your controls separate. In this case, I will create a folder called MyControls and copy MyControl.ascx into it. At this point you are probably wondering what is the path to my control if its in the 12 hive? On any SharePoint web application, there is a virtual directory called _controltemplates. This happens to map to the folder we need. Therefore, the path you would reference in your web part (or any web page) would be ~/_controltemplates/MyControls/MyControl.ascx.

Now, it is just a matter of deploying the binary. In traditional ASP.NET, you could just copy the DLL of your web application project to the bin folder of the web application. However, with SharePoint we can't do that without specifying Code Access Security which is a pretty big undertaking when you are starting out. For any file that is in the bin folder, SharePoint requires a security policy be set specifying exactly what permissions your DLL has. I recommend deploying to the bin folder, but if you are just starting out, you don't want to go there yet. To get around this for now, there are two options: 1) Change the TrustLevel in the web.config to Full or 2) Deploy the DLL to the Global Assembly Cache. I strongly recommend against #1, so for the sake of starting out, just copy your DLL to the GAC. You will need to strongly name your assembly. Any time you copy the DLL to the GAC, you will need to either recycle the application pool that your web application is using or reset IIS. I know that can be a pain, but once you implement CAS, you don't have to do that any more.

Just like with a web part, you have to add your user control as a safe control. Just specify the assembly name and allowed namespaces.

</SafeControls>

At this point you are ready to try your new user control out. To add it to a page like a web part, I recommend you follow the steps in this post to make your own SmartPart. If you don't know how to deploy a web part, follow my post on how to deploy a web part. Once you have your smart part added, specify the path I mentioned above (~/_controltemplates/MyControls/MyControl.ascx). You can also add user controls to your master pages, just like you would in ASP.NET. Just create the reference and add it to the .master.

This may sound like a lot at this point but it's really not bad. If there is enough interest in the article, I will try and get some code together in one package so people can use it as a starting point. That is how you manually deploy a user control, we'll move onto how we do it with a solution package.

Deploying via Solution Package

For deployment, we will pretty much follow what we did in the deployment of the web part. For more details on building solution packages, please see that post. In this case a feature is not necessary unless you want to automate the deployment of the user controls onto an existing page. The cab.ddf file only contains lines to copy the binary and .ascx file.

; ** MyControls.wsp  **
.OPTION EXPLICIT     ; Generate errors 
.Set CabinetNameTemplate=MyControls.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

;binaries
bin\MyControls.dll MyControls.dll

;feature files

;template files
MyControl.ascx CONTROLTEMPLATES\MyControls\MyControl.ascx

The Manfiest.xml file will contain entries to copy your ascx file out as well as copy your binary to the GAC. It will also add the Safe Control entry that you need. Here is what the file would look like. The TemplateFile element is used to specify every .ascx file that you want copied to the server. More details on what you can do with the manifest file are here.

<Solution SolutionId="{FA34A0BE-FEAA-4750-9E82-B313F62C5CF9}"  xmlns="http://schemas.microsoft.com/sharepoint/" ResetWebServer="true">
  <TemplateFiles>
    <TemplateFile Location="CONTROLTEMPLATES\MyControls\MyControl.ascx" />

  </TemplateFiles>
  <Assemblies>
    <Assembly DeploymentTarget="GlobalAssemblyCache" Location="MyControls.dll">
      <SafeControls>
        <SafeControl Assembly="MyControls, Version=1.0.0.0, Culture=neutral, PublicKeyToken=03afd371f1d50a3a" Namespace="MyControls" TypeName="*" Safe="True" />
      </SafeControls>
    </Assembly>
  </Assemblies>

</Solution>

At this point, you build and deploy the .wsp file as described in my web part post. Again, I strongly recommend reading that post if you are not familiar with any of the deployment steps yet. The nice thing about having your user control in a solution package is that it is now completely portable. It can be deployed to your other SharePoint servers very easily. Once you have mastered the process, I recommend you start deploying your binaries to the bin folder with Code Access Security. Once you have the solution package built, adding CAS is pretty easy and it saves you from having to kill your app pool every time you do a deployment.

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

CoreyRoth — Wed, 22 Oct 2008 12:50:00 GMT

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.

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.

Troubleshooting: Cannot import Web Part Error

CoreyRoth — Mon, 06 Oct 2008 22:20:54 GMT

Let's face it, any new SharePoint developer is going to run into an error such as the one below when starting out.

[WebPartPageUserException: Cannot import MyWebPart Web Part.]

at Microsoft.SharePoint.WebPartPages.WebPartImporter.CreateWebPart(Boolean clearConnections)

at Microsoft.SharePoint.WebPartPages.WebPartImporter.Import(SPWebPartManager manager, XmlReader reader, Boolean clearConnections, Uri webPartPageUri, SPWeb spWeb)

at Microsoft.SharePoint.WebPartPages.SPWebPartManager.CompressWebPartNoSave(Boolean isClosed)

I've found myself doing a LOT of troubleshooting of this for developers, so I decided it was time to post the steps in helping me resolve this issue. This issue can be a number of things, but the first place I always check is the web part gallery. If you can't view your web part in the gallery, chances are it's not going to work. The first thing you need to do is verify that your web part is in fact in the list. If it's not, you need to go install it (either manually or via solution package / feature). If it is there, click on the link to the web part (i.e. MyWebPart.webpart), not the icon. If you get an error like the one above, you definitely know something is wrong with the way the web part is installed on your server.

The next thing you do is click the Edit icon (the one next to the webpart link). From this page, you can make use of the View XML link to look at the .webpart file that is installed. More than likely at this point, the assembly path is wrong to your DLL or the DLL is not installed on your system. Confirm that the assembly path is correct given your DLL. For example, if your DLL is strongly signed, make sure the public key token is listed on the assembly path. If the DLL is not in the GAC, I recommend leaving off the PublicKeyToken becuase it will try and find that DLL in the global assembly cache which will give you an error saying that it cannot find the DLL. Other issues I have ran into here is the version number. Sometimes specify the version number as 1.0.* (for example). This usually works but I have seen issues where it would not work unless you specified 1.0.0.0. I am sure there is a reason for that, but I have no idea what it is. Also remember, if you change your assembly path ever (i.e.: you change the PublicKeyToken or namespace) and redeploy, you need to delete the .webpart file out of the gallery. You can do this manually or write code to do it with a feature receiver.

If you have verified that your .webpart is correct, make sure that the DLL for you web part actually exists. I know this sounds obvious, but lots of things can cause a solution package to install silently which means your DLL may not be present in the bin folder or the GAC when you think it should be. Also remember that you probably need to reset IIS (or at least the application pool), if you have deployed a DLL to the GAC for SharePoint to pick it up.

Of course, make sure you have a SafeControls entry in the web.config file for your assembly. Although, this would probably result in a Cannot register this type as safe error. This error can often times be quite frustrating because it will seem as if you have done all the steps to make sure it works and it just doesn't. Don't forget to check the logs (C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\logs) too. This error will show up in there and there may be extra information in there to help you find your error. Just keep at it and double check everything and usually you can find something.

More on Manfiest.xml

CoreyRoth — Thu, 04 Sep 2008 15:19:32 GMT

There are a ton of tools out there to create SharePoint solution packages (.wsp files) for you, but it is still a good idea to know what those tools are creating for you exactly. Sometimes, things don't always work right, and you may need to customize or tweak your manifest file. If you are new to SharePoint development, the Manifest.xml file is used during the deployment of a .wsp solution package. It tells SharePoint what files to copy, what features to install, where to put your binaries, adds SafeControl entries, as well as set code access security. The file seems pretty straight forward but there are a lot of ways to mess it up. As I pointed out in the past, do not put any comments in this file. It will cause all kinds of FAIL.

I'll start by go over the key elements of this file and point out some things you need to know about each one. If you create any of these main elements, note, that they will always require some kind of child element, otherwise the file won't validate. The first element we will talk about is FeatureManifests. This name as it sounds is used to deploy features. Your solution will install features but not activate them for you. You can list multiple features to install here using the FeatureManifest element. It's Location attribute specifies the path to the feature (inside the DDF file). What that means is the path specified to your feature.xml file will match whatever you have listed as the destination in your DDF file. We can talk about DDF files again another day if necessary.

<FeatureManifests>
    <FeatureManifest Location="MyFeature\feature.xml" />
</FeatureManifests>

The TemplateFiles element is used to copy out any additional files to the SharePoint server. These could be .webpart files, user controls, other XML files, application pages, master pages, etc. SharePoint will not copy any file that is not listed here (except for binaries and feature.xml and related files). Again, you can specify multiple TemplateFile child elements to copy multiple files. Part of what makes this file tricky is the paths. Some are relative, some require you to specify something inside the 12 hive. It takes some getting used to. In this case, if you are copying additional files into a feature folder for a web part, you would specify something like FEATURES\MyFeature\mywebpart.webpart.

<TemplateFiles>
  <TemplateFile Location="FEATURES\MyFeature\MyWebpart.webpart" />
</TemplateFiles>

The Assemblies element specifies which binaries will be deployed to SharePoint and where. You can copy multiple assemblies out at a time with a feature by specifying more than one Assembly element. The Assembly element has a Location attribute which typically just contains the DLL name (again dependent on where the DLL is copied in your DDF file). It also contains a DepoymentTarget attribute which specifies wether to copy it to the GAC (GlobalAssemblyCache) or the bin folder (WebApplication). It also contains a SafeControls element with the same syntax of what is used in the web.config.

<Assemblies>
  <Assembly DeploymentTarget="WebApplication" Location="MySolution.dll">
    <SafeControls>
      <SafeControl Assembly="MySolution, Version=1.0.0.0, Culture=neutral" Namespace="MySolution.WebParts" TypeName="*" Safe="True" />
    </SafeControls>
  </Assembly>
</Assemblies>

One thing to note here is that if you do not specify at least one assembly with a SafeControl element, SharePoint will decide that your solution does not contain a Web Application Resource and therefore will not deploy it when you specify a URL with stsadm. So, I typically include this line even if I don't have any controls or web parts in my solution. You will get an error like the one below.

This solution contains no resources scoped for a Web application and cannot be deployed to a particular Web application.

The last element, I am will talk about is CodeAccessSecurity. This of course is the most complex one. I have posted on this topic in the past and don't forget, I will be speaking about it next month. The post I have on it covers it in more detail that I will cover today. The one thing, I will remind you of is that it is ok to specify multiple assemblies.

I haven't talked about the root element yet. It's pretty simple. Just remember the SolutionId needs to be unique. The ResetWebServer attribute can be set to false if you don't want it to reset IIS on deployment.

<Solution SolutionId="{B3270C0DF-EACA-4320-9B2A-C293435C5DF1}"  xmlns="http://schemas.microsoft.com/sharepoint/" ResetWebServer="true">

Anyhow, hopefully this will help someone out the next time they are looking at a manfiest.xml file.

Avoid Comments in a SharePoint Deployment Manifest

C-Dog's .NET Tip of the Day — Thu, 05 Jul 2007 17:42:35 GMT

In order to properly install a web part with Code Access Security, it is necessary to create a deployment solution. My next post will cover these and the proper way to specify code access security for a web part. In the meantime though, I wanted to post...(read more)