Cleaning up your WebPart Gallery

Deploying webparts in SharePoint can be difficult (when you are learning) because of the many ways to do it. You can manually add webparts to the WebPart gallery, you can add WebParts through features and you can even manually add them to certain file system folders.

If you have developed extensively in SharePoint, you probably choose the feature way to deploy WebParts. I am not going to go into this conversation right now, but it is well known that the best practice for building webparts is to deploy them with features. However, one thing that nobody really talks about is removing the WebPart from the WebPart Gallery. If a WebPart is placed in the WebPart gallery when the feature is activated, shouldn’t it be removed from the WebPart gallery when the feature is de-activated? In this article we are going to go over the basics of how WebParts are added to the WebPart gallery during activation of the feature and then we are going to show how you can clean up your gallery when the feature is deactivated.

Overview of WebParts and Features

The premise of WebParts is simple – you are adding an xml file to a special list in SharePoint. This special list is called the Web Part Gallery and the xml file you add is called a .webpart file or a .dwp file. The .webpart or .dwp file “describes” the properties of the WebPart and points to a code file where the .net code runs that builds the WebPart controls. If you want to visit this special WebPart Gallery you can go to your SharePoint site and put “/_catalogs/wp” after your url (i.e.: http://server:port/_catalogs/wp). If I have already confused you at this point, you probably want to start looking into some beginner guides to WebParts in SharePoint. I will do a small overview of WebParts in this article (that might be helpful for beginners), but the point of this article is to show some advanced techniques to how to clean up your WebPart Gallery.

When deploying webparts in SharePoint I always use a Feature to deploy the WebPart to the WebPart gallery. Then I always wrap these features up in a WSP solution in order to deploy a single solution to my SharePoint farm. This is best practice and is really easy once you have done it a couple of times. Personally, I choose to use WSPBuilder to build my WSP solutions (but the process is the same if you use Visual Studio Extensions or if you build your WSPs manually).

If you are using WSPBuilder you can just click Add – New Item – WSPBuilder – WebPart Feature. This will create a .webpart file, feature.xml, element.xml  and code file for you. And, I choose “Site” scope so that the WebPart is added to my Site Collection WebPart Gallery. If you don’t use WSPBuilder, the process is the same, you still have to build the .webpart file, feature.xml, element file and code file (WSPBuilder just does it for you).

So, let’s talk about what these files do:

1.       Feature.xml – this file defines “how” the feature will get deployed and the general settings for the feature. Technically, this is the only file required for a feature to work.

 

The important part of this file is the “Scope”. The scope defines where the feature will be deployed (Site, Web, Web Application, Farm). For webparts, we usually choose “Site” in order for the WebPart to be added to the WebPart Gallery. The other important part of this file is the “ElementManifest”. This tells the feature where the element file is located. The element file is the actually actionable file in a feature.

<?xml version=“1.0“ encoding=“utf-8“?>

<Feature  Id=“7801227a-326a-4a65-8769-6e56ade76b66“

          Title=“Custom Webpart“

          Description=“This is my custom webpart Webpart“

          Version=“12.0.0.0“

          Hidden=“FALSE“

          Scope=“Site“

          DefaultResourceFile=“core“

          xmlns=“http://schemas.microsoft.com/sharepoint/“ >

  <ElementManifests>

    <ElementManifest Location=“elements.xml“/>  

  </ElementManifests>

</Feature>

 

2.       Elements file – usually we call this file elements.xml, but you can call it whatever you want. You just need to make sure it is an xml file and you need to make sure that the name you call it is the same as the reference in the feature.xml.

 

This file tells SharePoint “what” to do with the feature. There are a lot of different things you can do with SharePoint Features. So, you have to do your research to understand the different xml combinations. In the case of the WebPart, we are using a “Module” action. Module actions move files to different galleries (or lists) in SharePoint. With webparts, we want to move the .webpart gallery to the WebPart gallery list. We do this by setting the “url” property to the “_catalogs/wp” path. That is the path for the WebPart gallery list. The other thing to notice in this file is the “Group” and “QuickAddGroups”. These define the grouping when you click “Add New Webpart” on your SharePoint site.

<?xml version=“1.0“ encoding=“utf-8“ ?>

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

  <Module Name=“WebPartPopulation“ Url=“_catalogs/wp“ RootWebOnly=“TRUE“>  

         <File Url=“CustomWebpart.webpart“ Type=“GhostableInLibrary“>

                <Property Name=“Group“ Value=“RDA“></Property>

                <Property Name=“QuickAddGroups“ Value=“RDA“ />

         </File>    

  </Module>

</Elements>

 

3.        .webpart file – this is the file that “describes” the properties of the WebPart. This could also be a .dwp file (it all depends on the version of the WebPart you are using). SharePoint supports .net webparts and SharePoint webparts. That is why you can have .dwp and .webpart files. So, any property you can set in your WebPart, can be set in this file. I am not going to show an example here because the set of properties is different for every WebPart.

 

This file also contains the assembly path to the code file. This is important, because if you ever change information about the Code file (name, version, etc…), then you need to change the path in your .webpart file.

 

4.       Code file – this is the file that actually runs the webpart code. These files inherit from one of two classes depending on the version of WebPart you are building (.net webpart or SharePoint webpart). For example, a .net framework webpart will inherit from Microsoft.SharePoint.WebPartPages.WebPart. Once again, I am not going to show an example of this, because it is different for every customization. The basis of this class is that you build out your html controls programmatically and add them to the Control collection.

 

Side Note: On a side note that is not really part of this article, don’t think the SharePoint webpart (i.e.: dwp) is better to use than the .net webpart (i.e.: .webpart) just because one is labeled a SharePoint webpart. If you don’t plan on using SharePoint webpart connections or part caching, I actually recommend using a .net webpart in SharePoint. Also, you might hear .dwp webparts referred to as Version 2 webparts and .webparts referred to as Version 3 webparts. This is because .dwp webparts were originally built just for SharePoint 2.0 and are backwards compatible. But, in SharePoint 3.0 we got the ability to use the asp.net webparts.

 

Cleaning up your WebPart Gallery

Ok, so you know how to deploy a WebPart to the WebPart Gallery. But, you notice that when you de-activate your Feature the WebPart is still hanging around in the Gallery. Some developers don’t really care about this. But, other than the obvious problem of keeping a clean Gallery for maintaince, there is another big issue. Let’s say you are using versioning for your assembly for the WebPart code. The reference for the assembly is located in the .webpart file. Thus, if you don’t remove the WebPart from the gallery before you make version changes, then your new assembly version will never make it to the gallery.

So, the easiest way to do this is to just go to the WebPart Gallery and remove it before you install and activate your updated feature. However, as most SharePoint developers know, you want to stay away from manual processes as much as possible. That makes your customizations almost impossible to maintain as your code base grows.

But, the answer to this problem is easy. Create a feature receiver to remove the webpart from the WebPart Gallery when the feature deactivates. I saw this done for the first time when I was reviewing the code for the Forms Based Authentication project in the Community Toolkit for SharePoint:  http://www.codeplex.com/CKS. I modified the code a little to meet my needs, but it is basically the same. Here is how you do it.

Create a Generic Class

This class is a generic class that will work for any WebPart feature receiver. The idea behind this class is to implement the Feature Deactivating event and remove the WebPart. Here is the code for this class:

     class GenericWebPartFeatureReceiver : SPFeatureReceiver

    {

 

        /// <summary>

        /// Remove the webpart from the webpart gallery. This is to fix a shortcoming of SharePoint

       ///       that it doesn’t remove

        /// the webpart when the feature gets deactivated (even though it adds it when the feature

       ///       gets activated).

        /// </summary>

        /// <param name=”properties”></param>

        public override void FeatureDeactivating(SPFeatureReceiverProperties properties)

        {

            SPSite site = null;

            try

            {

                site = properties.Feature.Parent as SPSite;

                using (SPWeb web = site.RootWeb)

                {

                    SPList list = web.Lists["Web Part Gallery"];

 

                    // go through the items in reverse

                    for (int i = list.ItemCount – 1; i >= 0; i–)

                    {

                        // format name to look like a feature name

                        string webpartName = list.Items[i].Name;

                        webpartName = webpartName.Substring(0, webpartName.IndexOf(‘.’));

 

                        // delete web parts that have been added

                        if (properties.Feature.Definition.DisplayName == webpartName)

                        {

                            list.Items[i].Delete();

                            break;

                        }

                    }

                }

            }         

            finally

            {

                if (site != null)

                    site.Dispose();

            }

        }

 

        public override void FeatureActivated(SPFeatureReceiverProperties properties){ }

 

        public override void FeatureInstalled(SPFeatureReceiverProperties properties){ }

 

        public override void FeatureUninstalling(SPFeatureReceiverProperties properties) { }

    }

 

Call Feature Receiver

After your Generic Feature Receiver is built, then you just need to call it from the feature.xml file for all your WebParts. Here is some sample code. It is the same as the feature.xml file I showed above, except for the fact that I placed a reference to a RecieverAssembly and a ReceiverClass.

<?xml version=“1.0“ encoding=“utf-8“?>

<Feature  Id=“7801227a-326a-4a65-8769-6e56ade76b66“

          Title=“Custom Webpart“

          Description=“This is my custom webpart Webpart“

          Version=“12.0.0.0“

          Hidden=“FALSE“

          Scope=“Site“

          DefaultResourceFile=“core“

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

   ReceiverAssembly=“MySolution, Version=1.0.0.0, Culture=neutral, PublicKeyToken=3cbe19ecf7353dae“

   ReceiverClass=“MySolution.GenericWebPartFeatureReceiver“>

  <ElementManifests>

    <ElementManifest Location=“elements.xml“/>  

  </ElementManifests>

</Feature>

Note: You cannot just copy the xml above. The reference to the features ReceiverAssembly and ReceiverClass is specific to my implementation. When you deploy the assembly that contains the “GenericWebPartFeatureReceiver” to your BIN or GAC, then you need to get the information necessary to build out these two lines. Make sure the name of the Assembly and Namespaces match your implementation. And, make sure that the PublicKeyToken matches your public key for your assembly.

 

That’s it; you now have a Generic WebPart Feature Receiver that will remove the WebPart from the WebPart Gallery whenever your WebPart Feature is deactivated. This should help you keep your gallery clean and will help eliminate possible issues with assembly versioning.

Re-attaching objects – My Foray into Linq to Sql and the Entity Framework (part 2 of 2)

This is the second part of a two part series on Linq to Sql and the Entity Framework. In the first part we talked about the two different frameworks. Specifically we talked about detached objects. This part of the series will discuss the options to re-attach objects. We will be discussing this in terms of Linq to Sql. However, the “ideas” will work for the Entity Framework also.

How do I Re-attach my objects?

During my research I found 3 different techniques for re-attaching objects. Each of these techniques has pros and cons, so I will attempt to explain each one. I will be explaining these techniques in terms of Linq to Sql. However, the architectural decisions are the same with Linq to Sql or the Entity Framework.

Technique 1: Re-Query

The re-query technique is basically re-querying the database in your save routine. The reason to use this is to get the “original” values back before you save. However, there are some serious downsides to this technique.

Here is an example of this technique in action. Let’s say we have already done our retrieve and then hit the save button on our asp.net application. A postback ran and we filled in an “Employee” object. Now we have to attach that employee object to our context to save. However, if we just attach it, then the framework will always thing the object is “New”. So, we will re-query to get the original values so the framework knows we are doing an update.

//Instantiate a context to do our save

MyDataContext saveContext = new MyDataContext();

 

//Run a query to get the “original” objects

MyDataContext origContext = new MyDataContext();

Employee origEmp = origContext.Employees.Single(e => e.EmployeeID == 1);

 

//Attach the new employee object to the save context and pass in the original context

//so it can do concurrency checking

saveContext.Employees.Attach(newEmp, origEmp);

saveContext.SubmitChanges();

 

The above technique will seem like it works. However it has two issues:

1.       Performance – there is no need to run that extra retrieve when saving

2.       Concurrency – this is not really checking concurrency, it is doing a fake check

Let me explain a little more why this is doing a fake check. Let’s take an example of two users in a system. This system has a status field and the users really need to know the current status when they are changing data because another user might have already made the changes that they wanted to make for this particular status.

1.       User 1 retrieves the data

2.       User 2 retrieves the data

3.       User 2 updates the data

4.       User 1 updates the data

That is a concurrency issue on step 4. When User 1 updates the data, they should know that someone else slipped in an updated the data before them and they never saw that updated data. Well, in the above approach where you query the data in the save logic, just to get the original values, you are not really solving the underlying problem. Because User 1 just retrieved User 2’s data when they were saving and never saw the changed data. Concurrency checks will all pass and User 1 will never know there was an issue.

So, I don’t ever recommend this technique if concurrency is something you need in your system.

 

Technique 2: Session

Using session to store your objects across PostBacks is a valid technique to keep original data around. The basic steps are to retrieve the data in load, set that data to session, run the save PostBack, get the data out of session and reset the fields with the data from your user controls.

This sounds easy, but there are many considerations when using this technique.

Consideration 1

Session can hurt performance of a server and eat up resources. You have to be very careful when using Session on an asp.net application. If your objects are too large, then you don’t want to store them in session. Also, if you have many users accessing the system at the same time, session can become an issue. So, weigh in the normal architectural decisions of using Session when validating this approach.

Consideration 2

You have now disconnected the original object and want to re-attach it to the context. Don’t you lose all “state” information (i.e.: new, modified, deleted, etc…)? Well, yes, you do. But, this is where that Code Plex project I mentioned earlier comes in to play http://www.codeplex.com/LINQ2SQLEB. This keeps the state and original values in the base class for the objects, instead of just keeping them in the context. And, it reattaches the objects to a new context and sets all this information. Thus, I can serialize my objects, reattach them to my data context and still have my original values and state around for optimistic concurrency checks.

Consideration 3

Linq to Sql objects are not marked as Serializable. Thus, they can’t just be set into session easily. However, the Entity Framework objects are marked that way, so this is only an issue with Linq to Sql.  Luckily, there is a trick to this. Linq to Sql does support DataContracts. Thus, you can use the DataContactSerializer to store Linq to Sql objects in session http://www.squaredroot.com/post/2008/01/30/Storing-LINQ-Objects-in-SQL-Based-Session-State.aspx

 

This technique was the approach I picked for my last project. We had other architectural decisions in which we were storing objects in session anyways, so it seemed like a perfect fit. And, because of this technique, and the base class I found (LINQ2SQLEB) is the only reason I picked Linq to Sql over the Entity Framework. If there was something available like this for the Entity Framework, I would use it in a second. Hum, maybe I will create something like that.

Note on Technique 2

Be careful with this technique and the concurrency checking mechanism of Linq to Sql. When you re-attach your object, to do an update, here is what the update statement will look like:

@originalValue1 = 02/11/2009 12:33:31 PM

@originalValue2=”testing”

@newValue1 = 02/13/2009 12:33:31 PM

@newValue2=”test”

UPDATE [MyTable]

SET [lastUpdatedTime] = @newValue1, [field1] = @newValue2

WHERE ([lastUpdatedTime] = @originalValue) AND ([field1] = @originalValue2)

 

This is fine and the update statement will do optimistic concurrency perfectly. However, there is a performance consideration here. The update statement builds a check on every field in the “Where” clause. This can make a bloated sql statement when you are updating lots of fields. If you want to clean up these sql statements, here is my suggestion. Add a field to your table in the database that always changes, I recommend a timestamp field in sql server. Then, go to your Linq to Sql designer and turn the concurrency check from “Always” to “Never” on all your fields except this timestamp field. This way, the timestamp field is the only field that will be checked in the “Where” clause. You will still have the same optimistic concurrency and a much quicker update statement.

 

Technique 3 – Manually attaching with timestamp

The last technique I want to explain is how to manually attach an object with a timestamp field. In this technique we retrieve our data in the load, set a timestamp field to ViewState, run the save on PostBack and use that timestamp field to set the original values.

The technique is actually quite simple when seen in code. Below I am showing the save code. Assume we have already loaded the data and set the timestamp field to a ViewState attribute marked _timestamp.

 //Instantiate a context to do our save

MyDataContext saveContext = new MyDataContext();

 

//Create a new employee object to fill in

Employee emp = new Employee();

 

//reset the timestamp viewstate field “before” I attach to set the original value

emp.timeStamp = _timeStamp;

 

//Attach the object after setting the timestamp.

//This creates an object in state “New”

saveContext.Employees.Attach(emp);

 

//set the values from our user controls

Emp.FirstName = txtFirstName.Text;

Emp.MiddleName = txtMiddleName.Text;

Emp.LastName = txtLastName.Text;

 

saveContext.SubmitChanges();

 

Keys to making this work:

1.       Set the original value, from ViewState, before you attach the object.

2.       Set the new values, from your user controls, after you attach the object.

3.       Turn the “Update Check” to “Never” on all the fields except for the timestamp field in the Linq to Sql designer.

 

How this works:

Basically, you create a new Employee object. At this point, all the fields (timestamp, FirstName, MiddleName, LastName) are set to null and the state is “New”. Then you set the timestamp field from ViewState. This sets that value to the “original” value we got when we loaded. The state is still “New” at this point. Then we attach to the context. Once the object is attached to the context, any change we make turns the state from “New” to “Modified”. So, when we set the FirstName, MiddleName and LastName we are telling the context that we modified data. This will build an update statement like this:

 

@originalTimeStamp = “3289t5u23940uewu903285”;

@originalFirstName=null;

@originalMiddleName=null;

@originalLastName=null;

@newTimeStamp = “3289t5u23940uewu903285”;

@newFirstName=”Greg”

@newMiddleName=”Brian”;

@newLastName=”Galipeau”;

UPDATE [MyTable]

SET [TimeStamp] = @newTimeStamp, [fName] = @newFirstName, [lname] = @newLastName, [mName] = @newMiddleName

WHERE ([TimeStamp] = @originalTimeStamp)

 

The issue with this approach is that it will always think that it needs to update the fields in the database. Because the original value for the First, Middle and Last names always are null, it always thinks we changed them. This is not necessarily a bad thing. You will have to decide that for your architecture. If it is a bad thing, and you really want to use this approach, then you have to set those values in ViewState when you load also. That way you can set the original values, before you attach, and the tool can do a real check against the value to see if you actually made any changes. This process of setting everything into ViewState could become quite cumbersome on larger forms.

The following example assumes I stored the original first, middle and last names in ViewState on the page load.

//Instantiate a context to do our save

MyDataContext saveContext = new MyDataContext();

 

//Create a new employee object to fill in

Employee emp = new Employee();

 

//reset the viewstate fields “before” I attach to set the original value

emp.timeStamp = _timeStamp;

emp. FirstName = _firstName;

emp. MiddleName = _middleName;

emp. LastName = _lastStamp;

 

 

//Attach the object after setting the timestamp.

//This creates an object in state “New”

saveContext.Employees.Attach(emp);

 

//set the values from our user controls

Emp.FirstName = txtFirstName.Text;

Emp.MiddleName = txtMiddleName.Text;

Emp.LastName = txtLastName.Text;

 

saveContext.SubmitChanges();

 

  

Conclusion

So far these 3 techniques are the best ones I have found for re-attaching disconnected objects using Linq to Sql or the Entity Framework. If you have any other suggestions please leave a comment. And, let’s just “hope” Microsoft one day realizes this scenario and gives us better options, such as the option to have a mini-datacontext that we can store in Session. That would be nice!