Best Practices for Developing SharePoint Custom Web Parts

In essence, a web part is a small web application that integrates into a broader web application. In SharePoint, web parts usually coexist with other web parts on a web part page. It's your responsibility to ensure that you design your web part so that it will:

• Provide an intuitive user interface even when failing
• Work with other web parts running in the same environment
• Integrate smoothly with the SharePoint architecture
• Be upgradable
• Be safe and secure
• Provide optimal performance

If you investigate, you'll find considerable information available from various sources that discuss how best to develop web parts that meet these objectives. This article is intended to serve as a one-stop resource, both to highlight the major issues and best practices, and to provide links to further resources on any given topic.

General Web Application Programming Practices

It should go without saying that you should not stop implementing normal programming practices when programming web parts. To this end you should still…

It is quite likely that any exception generated by your web part will cause the entire web part page to stop responding and display your error. You should avoid such problems at all costs by wrapping all code likely to generate an exception in a Try/Catch/Finally block (for more information see these two links VB developers and C# developers.

SharePoint will direct any unhandled exceptions to a generic error page and render a message. To control the error message displayed, you need to implement the WebPartPageUserException class.

Any information submitted via a web application is subject to both accidental misuse and deliberate attack. Therefore, you must validate all information submitted by the user, making sure it's in an appropriate form and contains acceptable values.

To help prevent a malicious user from attacking your application using cross-site scripting or other script-based attacks you should always encode input to safe HTML. This changes all extended and special characters into escape characters. To do this in SharePoint, use the SPEncode class's HTMLEncode method (you will need to import the Microsoft.SharePoint.Utilities namespace to use this class).

Upgradable Web Parts

Ask anyone who was involved in upgrading SharePoint Portal Server 2003 to either MOSS 2007 or WSS 3.0 if it was a pleasant experience, and you'll probably have to ward off a torrent of negativity. Fortunately, Microsoft solved many of these problems in MOSS 2007 and WSS 3.0 by adding support for a highly upgradable deployment methodology. The combination of WSP packages and the feature framework give you two upgrade points for your solutions. But you need to use them to benefit from this power.

Your SharePoint Administrator (if you have one) should tell you that nothing should be installed on a SharePoint farm unless it's provided as a SharePoint Solution Package (.wsp file). However, third-party vendors still sell web parts and other SharePoint solutions packaged as executables.

To make sure your web parts get installed correctly and can be upgraded smoothly, put them in a Site Collection scoped feature, and wrap the feature in a WSP.

Linked Resources

In addition, if your web parts use external resources such as images, CSS files, or scripts, you will need to reference these from within your code. If you want to maintain the upgradability of your web part, use linked resources to ensure that the external files are not bound to your assembly. This will also help with performance if you share these scripts with multiple web parts, because they will be cached at browser level. For more information on managing resources, see this link.

Connections

If your web part uses the Web Part Connections Framework, then it is probably in your best interest to implement the standardized connection interfaces provided by ASP.NET. Obviously, this is not always possible—it depends upon the web parts and the type of data being shared. However if you are using simple types then you should probably use the ASP.NET implementations to ensure that out-of-the-box SharePoint web parts can interact with yours and vice versa.