This is the third part of my Web Part Properties series and this post will focus on the .webpart file. Every SharePoint developer have seen it and perhaps edited it, but what is the purpose of the file and when and why should I edit it.

Background

The .webpart file is an XML file containing metadata about the Web Part. In previous versions of SharePoint this file had an extension of .dwp. Although these files may look similar it’s a crucial difference between those files. The .webpart file uses the http://schemas.microsoft.com/WebPart/v3 schema and the .dws file uses http://schemas.microsoft.com/WebPart/v2. The v2 schema is intended for Web Parts derived from the Microsoft.SharePoint.WebPartPages.WebPart class, which is the base class used for developing Web Parts for previous SharePoint versions. When developing Web Parts using the .NET 2.0 WebPart class (System.Web.UI.WebControls.WebParts.WebPart) the v3 schema must be used, see previous article on why you should use the latter.

Structure

The .webpart file uses the following structure, with some elements left out for later posts.

  • webParts
    • webPart
      • metaData
        • type
        • importErrorMessage
      • data
        • properties
          • property

The metadata element contains information about the Web Part; the type element must contain a name attribute which must be the full name of the Web Part class, and the importErrorMessage element contains an error message that is displayed if the import of the Web Part fails.

The data section contains information about the default values of the Web Part properties, each default value is set using the property element. Each property element has a name attribute_,_ a _type_ attribute and a value; the name property must match an exposed Web Part property and the type must be the Type of the property. The type can be expressed as a fully qualified type name or one of the built-in shortcuts (string, int, bool, double, single etc). The value of the type property is the default value.

For full reference of the schema head on over to MSDN.

Sample

Here is a sample of a .webpart file, taken from the TweetPart in the previous Web Part Properties posts.

  1: <?xml version="1.0" encoding="utf-8"?>
  2: <webParts>
  3:   <webPart xmlns="http://schemas.microsoft.com/WebPart/v3">
  4:     <metaData>
  5:       <type name="TweetPart.TwitterWebPart, TweetPart, Version=1.0.0.0, Culture=neutral, PublicKeyToken=cfa2cd081d8900d7" />
  6:       <importErrorMessage>Error importing Web Part</importErrorMessage>
  7:     </metaData>
  8:     <data>
  9:       <properties>
 10:         <property name="Title" type="string">TweetPart</property>
 11:         <property name="Description" type="string">Sample Web Part by Wictor Wilén</property>
 12:         <property name="ChromeState" type="chromestate">Normal</property>
 13:         <property name="AllowZoneChange" type="bool">True</property>
 14:         <property name="AllowHide" type="bool">True</property>
 15:         <property name="ExportMode" type="exportmode">NonSensitiveData</property>
 16:         <property name="TitleIconImageUrl" type="string">/_layouts/images/TweetPart/TweetPart_16.png</property>
 17:         <property name="CatalogIconImageUrl" type="string">/_layouts/images/TweetPart/TweetPart_16.png</property>
 18:         <property name="Username" type="string">wictor</property>
 19:         <property name="Mode" type="TweetPart.TwitterTimeLineMode">User</property>
 20:         <property name="TweetCount" type="int">10</property>
 21:       </properties>
 22:     </data>
 23:   </webPart>
 24: </webParts>

As you can see the metaData is defined in row 4-7 and the default values in rows 8-23. The Web Part class we use is defined on row 5 and expressed using the full assembly name.

If we look at the properties we notice that there are several property elements (row 10-15) that contains information on the behavior of the Web Part, these properties are almost always defined and most Web Part code generation tools, like STSDev, adds them automatically. For this part I added three custom properties, row 18-20. The second one of those uses a custom type defined in my assembly.

Tip: Row 16 and 17 contains two system defined properties that you can use to make your Web Part look a little bit cooler by using icons. The TitleIconImageUrl points to an image that is used in the heading of your Web Part and the CatalogIconImageUrl is displayed in the Web Part Catalog.

Note: it is not necessary to add all of your Web Part properties to the .webpart file, unless a default value is needed.

Install and customize

Every Web Part needs one of these .webpart files to work. To get your Web Part to work you have to register the class in the correct way and the add the .webpart file to the Web Part Gallery. This is normally done when you deploy your Web Part feature.

If the Web Part has a lot of custom properties you can help your users by editing the .webpart file and customize the default values. Just go to the Web Part Gallery and choose to Export the Web Part. Then you just edit the file with your favorite XML editor and upload it once again to the Web Part Gallery.

Export a Web Part

Tip: If you don’t want to manually edit the file you can always add the Web Part to a page and then edit the properties and then use the Export menu option on the Web Part.

Summary

I think it’s worth the time to go through your .webpart files; if you are a developer make sure that you add a good set of default values for your Web Part and as a SharePoint administrator you should help your users by setting good default values that fit your installation(s).