ASP.NET Web 部件控件的描述文件

Web 部件控件的描述文件是一个扩展名为 .WebPart 的 XML 文件，它包含有属性值、状态数据、以及从 WebPart 控件（或者是用在 Web 部件应用程序中的其它 ASP.NET 服务器或用户控件）所导出的的汇编集或源文件的详细内容。Web 部件的导入特征通过使用描述文件来为 Web 部件页面导入控件的描述，并使用已保存的数据来配置被导入的控件。该文章对描述文件中所包括的基本结构以及 XML 元素进行描述。

<webParts>

  <webPart>

    <metaData>

      <type …/>

      <importErrorMessage .../>

    </metadata>

    <data>

      <properties>

        <ipersonalizable>

          <property …/>

        </ipersonalizable>

        <property …/>

      </properties>

      <genericWebPartProperties>

        <ipersonalizable>

          <property …/>

        </ipersonalizable>

        <property …/>

      </genericWebPartProperties>

    </data>

  </webPart>

</webParts>

备注

下表列出了能够被 Web 部件描述文件所包括的每个元素（以缩进的格式显示这些元素的直接子元素），列出了元素中的任何现有参数，以及元素用途的概要。注意，如果控件实现了 IPersonalizable 接口，那么会出现适当的 <ipersonalizable> 子元素并且把已实现的属性当成 <property> 元素来进行包含；否则，文件中将不会出现 <ipsersonalizable> 元素。

元素	参数	概要
webParts webPart	无。	文件中的父元素；并且在每个文件中只能够出现一次。该元素的 XML 逻辑允许每个文件中可以包含多个 <webPart> 元素，但是作为演示，我们只实现了一个 <webPart> 元素。
webPart metaData data	xmlns= "http:// schemas.microsoft.com/ WebPart/ v3" 提示：这是一个拥有固定值的命名空间参数。	对状态和属性数据被包含在文件中的控件进行展示。作为演示，我们为每个文件只使用了一个 <webPart> 元素。
metaData type importErrorMessage	无。	包含 <webPart> 元素的类型信息以及在导入过程出现错误时显示给用户的错误消息。每个 <webPart> 元素只能有一个实例。
type	type 元素必须拥有一个已指定的 name 或者 src 参数，也能够同时被使用。如果同时使用这两个参数，将优先处理 name 参数。 name 参数由包含类型和（可选的）关于 <webPart> 元素的汇编集信息的字符串所组成。 src 参数提供用户控件的源文件路径。	列出某个包含 <webPart> 元素的汇编集的类型信息，或者由 <webPart> 元素所呈现的用户控件的源文件路径。
importErrorMessage	无。	包含在导入过程中发生错误时显示给用户的错误消息内容。每个 <webPart> 元素只能有一个实例。
data properties genericWebPartProperties	无。	包含 <webPart> 元素的状态和属性值的数据。每个 <webPart> 元素只能有一个实例。
properties ipersonalizable property	无。	包含 <property> 元素，或者是单独的一个 <ipersonalizable> 元素（包含有 <property> 子元素），或者两者同时被包含。<properties> 元素始终能够被呈现，但是只有在 <webPart> 拥有可个性化属性的时候才能够拥有 <property> 子元素。每个 <webPart> 元素只能有一个实例。
genericWebPartProperties ipersonalizable property	无。	包含一个 <property> 元素，或者是单独的一个 <ipersonalizable> 元素（包含有 <property> 子元素），或者两者同时被包含。这个元素只在控件与非继承自 WebPart 类的 <webPart> 元素通讯的时候才被呈现。每个 <webPart> 元素只能有一个实例。
ipersonalizable property	无。	<properties> 元素和 <genericWebPartProperties> 元素的子元素。这个元素只在控件与实现了 IPersonalizable 接口的 <webPart> 元素通讯的时候才会出现。它能够包含一个或者多个 <property> 子元素。每个 <webPart> 元素只能有一个实例。
property	<property> 元素有三个参数：name、type、以及 null。其中 name 和 type 参数是必需的；而 null 参数只在属性拥有空值的时候才被使用。 name 参数是与 <webPart> 元素通讯的控件的特定属性的名称。 null 参数能够获取 true 值或者 false 值；它只在属性拥有空值的时候才被使用，以区别于来自于空字符串（""）的值。 type 参数用于识别 name 参数中被引用的属性的 Type 属性。type 参数实际的值可以是一个完整的类型名称，或者是使用下面所列的类型名称的缩写。 string int bool double single datetime color unit fontsize object direction （展示 ContentDirection） helpmode （展示 WebPartHelpMode） chromestate （展示 PartChromeState） chrometype （展示 PartChromeType） exportmode （展示 WebPartExportMode）	<properties>、<genericWebPartProperties>、以及 <ipersonalizable> 元素的子元素。这个元素为每个属性的值或者 <webPart> 元素中的状态数据项而包含“name/value”对。属性的实际数据则被包含在 <property> 元素的标记中，并且属性项的名称和类型由参数所指定。在包含它们的这三个类型的父元素中能够存在零个或者多个 <property> 元素。

实例

下列代码实例演示了两个在 Web 部件应用程序中导出控件实例的 .WebPart 描述文件。第一个实例显示了一个继承自 WebPart 基类的控件的源文件。注意它的属性数据全部被包含在 <properties> 元素中。第二个实例显示了一个没有继承自 WebPart 类的 ASP.NET 服务器控件的源文件。注意它的属性数据全部被包含在 <genericWebPartProperties> 元素中。

<!-- 由 System.Web.UI.WebControls.WebParts.WebPart 控件所导出的文件。 -->

<?xml version="1.0" encoding="utf-8"?>

<webParts>

  <webPart xmlns="http://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>

<!-- 由位于 Web 部件区域中的 System.Web.UI.WebControls.BulletedList 控件所导出的文件。 -->

<?xml version="1.0" encoding="utf-8"?>

<webParts>

  <webPart xmlns="http://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>