Upgrading is among the most important  aspects of  the software development process, because we need to remake the product with new features and enhancements, provide additional flexibility, and generally develop an even more useful product than the original. Upgrading a Web Part can mean changing the number of properties of the Web Part, or reorganizing the structure of the Web Part properties; the final step in the upgrade of a Web Part is to ensure that our Web Part works correctly.

Each of the Web Part properties has a Name and Type.  If there is only a change to the Name in the new version, it’s easy to upgrade the Web Part, but with changes to the Type, we must reorganize the structure of the Web Part properties.

Challenge:

How do I upg​​​rade Web Part properties in SharePoint 2010?

Solution:

In SharePoint, there are two methods to perform an upgrade on Web Part properties: the override AfterDeserialize method, and implementing the interface IversioningPersonalizable. In this article, I will assume that our project is named MyWebpart, and has a property named ListSource. ListSource stores the source name that the Web Part will connect to in order to get the data, and its value is a string (such as SharePoint if you are connecting to a SharePoint List, and SQL if you are connecting to SQL Server: 

Now I need to upgrade to version 2.0, and I need to replace the old properties with a new property named DataSource.​

1. Implementing AfterDeserialize:

I implement an override using the AfterDeserialize method, which will go through and access each of property of the Web Part in version 1.0. Thus, in this method, I have a loop statement to get the value for each of the elements, then assign them to the new property in version 2.0. In the case of the image belowk, I will get the value of ListSource and assign to DataSource property. 

Note: Each XmlElement element in the UnknownXmlElements properties is a Web Part property.

After assigning the new property, I need to remove the old property from UnknowXmlElement so that next time, this property will not upgrade again. This prevents duplicate data, or setting the wrong value whenever the method executes.

2. Implementing IVersioningPersonalizable:

In this solution, I need to inherit the interface named IVersioningPersonalizable, which is supported SharePoint, and declare a variable named oldProperties to store all properties of the old version of the Web Part. To get the old properties of the previous version of the Web Part, implement the code in the Load method of this interface as shown below:

The Method Load of IVersioningPersonalize is executed first, so I need to upgrade the properties in OnInit of the Web Part. I implement a loop statement to go through all properties as with the above solution. To avoid the duplicate or updating the wrong value whenever OnInit is executed, after upgrading the properties, I set the oldProperties variable to be null, indicating that we have already upgraded. 

Notes:

Be aware that, when upgrading Web Parts for Publishing sites, you will likely get an error at this.SaveProperties = true. If you see this error, it means you’ll need to check out your publishing site before upgrading the Web Part.

See Also:

• Upgrading Web Parts [MSDN]
• ​Upgrading a Web Part Assembly for Microsoft SharePoint Products and Technologies [MSDN]
• Handling unknown properties during a Web Part upgrade [SharePoint Thoughts]