Web Parts Control Description Files
Web Parts control description files contain property values, state data, and assembly or source file details exported from a WebPart control (or other ASP.NET server or user control used in a Web Parts application) to an XML file with a .WebPart extension. A description file is used by the Web Parts import feature to import the control it describes into a Web Parts page, and to configure the imported control with the saved data. This topic describes the basic structure and XML elements included in a description file.
<webParts>
<webPart>
<metaData>
<type …/>
<importErrorMessage …/>
</metadata>
<data>
<properties>
<ipersonalizable>
<property …/>
</ipersonalizable>
<property …/>
</properties>
<genericWebPartProperties>
<ipersonalizable>
<property …/>
</ipersonalizable>
<property …/>
</genericWebPartProperties>
</data>
</webPart>
</webParts>
Remarks
The following table lists each element that can be included in a Web Parts description file (with the element's immediate child elements indented beneath it), lists any attributes that exist on that element, and summarizes what the element is used for. Note that, if a control implements the IPersonalizable interface, the appropriate <ipersonalizable> child element appears and contains the implemented properties as <property> elements; otherwise, the <ipersonalizable> element does not appear in the file.
Element |
Attributes |
Summary |
|---|---|---|
webParts webPart |
None. |
The parent element in the file; it can occur once per file. The logic of the XML is that this element could contain multiple <webPart> elements per file, but as currently implemented there is one <webPart> in a description file. |
webPart metaData data |
xmlns="https://schemas.microsoft.com/WebPart/v3" Note This is a namespace attribute with a fixed value. |
Represents the control whose state and property data are contained in the file. Currently, there can only be one <webPart> element per file. |
metaData type importErrorMessage |
None. |
Contains information about the type of the <webPart> element and a message to display to users if there are errors during the import process. One instance per <webPart> element. |
type |
The type element must have either a name or a src attribute specified, and can have both. If both are specified, name takes precedence. The value of the name attribute consists of a string with type and (optional) assembly information about the <webPart> element. The src attribute provides a path to the source file of a user control. |
Lists type information for an assembly that contains a <webPart> element, or the path of a source file if <webPart> represents a user control. One instance per <webPart> element. |
importErrorMessage |
None. |
Contains the text of a message displayed to users if an error occurs during the import process. One instance per <webPart> element. |
data properties genericWebPartProperties |
None. |
Contains the state and property values data for the <webPart> element. One instance per <webPart> element. |
properties ipersonalizable property |
None. |
Contains <property> elements, a single <ipersonalizable> element (which contains child <property> elements), or both. The <properties> element is always present, but will only have child <property> elements if <webPart> has personalizable properties. One instance per <webPart> element. |
genericWebPartProperties ipersonalizable property |
None. |
Contains <property> elements, a single <ipersonalizable> element (which contains child <property> elements), or both. This element is only present if the control that corresponds to <webPart> does not inherit from the WebPart class. One instance per <webPart> element. |
ipersonalizable property |
None. |
A child of both the <properties> element and the <genericWebPartProperties> element. This element appears only if the control that corresponds to the <webPart> element implements the IPersonalizable interface. It contains one or more <property> elements. One instance per <webPart> element. |
property |
The property element has three attributes: name, type, and null. The name and type attributes are required; null is used only if the property has a null value. The name attribute is the name of a particular property on the control that corresponds to the <webPart> element. The null attribute can take a value of true or false; it is used only when a property actually has a null value, to distinguish that value from an empty string ("") value. The type attribute identifies the Type of the property referenced in the name attribute. The actual value of type can be a string with a fully qualified type name, or it can be a string that uses one of the abbreviated type names listed below. * string * int * bool * double * single * datetime * color * unit * fontsize * object * direction (represents ContentDirection) * helpmode (represents WebPartHelpMode) * chromestate (represents PartChromeState) * chrometype (represents PartChromeType) * exportmode (represents WebPartExportMode) |
A child of the <properties>, <genericWebPartProperties>, and <ipersonalizable> elements. This element contains name/value pairs for each property value or state data item within the <webPart> element. The actual data for a property is contained between the <property> element tags, and the name and type of the property item are specified by attributes. There can be zero to many <property> elements within the three types of parent elements that contain them. |
Example
The following code examples demonstrate two .WebPart description files that were exported from instances of controls in a Web Parts application. The first example shows a file for a control that inherits from the base WebPart class. Note that its property data is all contained within the <properties> section. The second example shows a file for an ASP.NET server control that does not inherit from the WebPart class. Note that its property data is all contained within the <genericWebPartProperties> section.
<!-- File exported from a System.Web.UI.WebControls.WebParts.WebPart
control. -->
<?xml version="1.0" encoding="utf-8"?>
<webParts>
<webPart xmlns="https://schemas.microsoft.com/WebPart/v3">
<metaData>
<type name="Samples.AspNet.CS.Controls.TextDisplayWebPart,
App_Code.zq0cecf5, Version=0.0.0.0, Culture=neutral,
PublicKeyToken=null" />
<importErrorMessage>
Cannot import this Web Parts control.
</importErrorMessage>
</metaData>
<data>
<properties>
<property name="AllowClose" type="bool">True</property>
<property name="Width" type="unit" />
<property name="AllowMinimize" type="bool">True</property>
<property name="ContentText" type="string" null="true" />
<property name="AllowConnect" type="bool">True</property>
<property name="ChromeType" type="chrometype">
Default
</property>
<property name="TitleIconImageUrl" type="string" />
<property name="Description" type="string" />
<property name="Hidden" type="bool">False</property>
<property name="TitleUrl" type="string" />
<property name="AllowEdit" type="bool">True</property>
<property name="Height" type="unit" />
<property name="HelpUrl" type="string" />
<property name="Title" type="string" />
<property name="CatalogIconImageUrl" type="string" />
<property name="Direction" type="direction">
NotSet
</property>
<property name="ChromeState" type="chromestate">
Normal
</property>
<property name="AllowZoneChange" type="bool">True</property>
<property name="AllowHide" type="bool">True</property>
<property name="HelpMode" type="helpmode">Navigate</property>
<property name="ExportMode" type="exportmode">All</property>
</properties>
</data>
</webPart>
</webParts>
<!-- File exported from a System.Web.UI.WebControls.BulletedList
control placed in a Web Parts zone. -->
<?xml version="1.0" encoding="utf-8"?>
<webParts>
<webPart xmlns="https://schemas.microsoft.com/WebPart/v3">
<metaData>
<type name="System.Web.UI.WebControls.BulletedList,
System.Web, Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a" />
<importErrorMessage>
Cannot import this Web Parts control.
</importErrorMessage>
</metaData>
<data>
<properties />
<genericWebPartProperties>
<property name="AllowClose" type="bool">True</property>
<property name="Width" type="unit" />
<property name="AllowMinimize" type="bool">True</property>
<property name="AllowConnect" type="bool">True</property>
<property name="ChromeType" type="chrometype">
Default
</property>
<property name="TitleIconImageUrl" type="string" />
<property name="Description" type="string" />
<property name="Hidden" type="bool">False</property>
<property name="TitleUrl" type="string" />
<property name="AllowEdit" type="bool">True</property>
<property name="Height" type="unit" />
<property name="HelpUrl" type="string" />
<property name="Title" type="string">
Favorite Links
</property>
<property name="CatalogIconImageUrl" type="string" />
<property name="Direction" type="direction">
NotSet
</property>
<property name="ChromeState" type="chromestate">
Normal
</property>
<property name="AllowZoneChange" type="bool">
True
</property>
<property name="AllowHide" type="bool">True</property>
<property name="HelpMode" type="helpmode">
Navigate
</property>
<property name="ExportMode" type="exportmode">
All
</property>
</genericWebPartProperties>
</data>
</webPart>
</webParts>