SharePoint supports several types of web part, and it is not immediately clear from the documentation and out of box examples which combination to use.

XML Definition Files

First there is the .webpart or .dwp file. The out of the box web parts use both formats which makes it less clear which is the right one to use.

.dwp files are the older format so should be avoided. The document element for a dwp file is

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

and within this element properties are specified as  

 <Title>Business Data Actions</Title>

.webpart files are the newer format, which can be used for both SharePoint-specific and generic asp.net webparts. The v3 format uses a webParts element as the document element, and the webpart element uses a different namespace:

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

Properties are specified as

  <property name="Title" type="string">Choice Filter</property>

It is the property differences that are most likely to cause problems if you get the formats mixed up.

WebPart Code

To write code for a webpart, you have a choice of two webparts to inherit from.

System.Web.UI.WebControls.WebParts.Webpart

Microsoft.SharePoint.WebpartPages.Webpart

Some parts of the documentation seem to suggest that the SharePoint one is there for backwards compatibility and the System.Web version should be used. However, the SharePoint version is a subclass of the System.Web version and adds a fair bit of SharePoint-specific code. In real world development you won't often need to host a webpart developed for SharePoint outside of SharePoint, so in the interest of picking a standard, I go with the SharePoint version.

Within the code most things remain the same whichever webpart variation you are working with, but properties are significantly different though.

The v2 format is based on serailising the web part class, so an XmlRoot attribute is needed on the class and the attributes needed for properties are serialisation based:

[XmlElement("ContentLink", IsNullable=false), Resources("ContentLinkLiteral", "Advanced", "ContentLink"), WebPartStorage(Storage.Shared)]

Additional SharePoint-specific attributes such as Browsable are used to define how the attribute will appear in the toll pane.

The v3 format is based on retrieving values from the standard property structure. XmlRoot is not required, and the attributes for properties come from System.Web.UI and System.ComponentModel:

[Personalizable(PersonalizationScope.Shared)]

        [WebBrowsable(true)]

        [System.ComponentModel.Category("My Property Group")]

        [WebDisplayName("MyProperty")]

        [WebDescription("Meaningless Property")]

While either format will work, it is important that the version used in the code matches the one used for the xml. Mixing the two formats will cause unexpected markup errors. If you create a web part without properties first, the errors will not show up the first time you deploy or even when you add properties and redeploy - the error will appear only when you try to add a new web part to a page or view it in the web part gallery.