Web Parts Control Description Files

  • Article

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>

See Also

Reference

ExportWebPart

ImportWebPart

ExportMode

ImportCatalogPart