使用遷移 API 遷移網頁元件Migrate web parts by using the Migration API

透過呼叫 CSOM/REST/SOAP WS 以取得網頁元件資料和屬性來建立主要套件,遷移 API 支援使用主要套件將網頁元件遷移至 Microsoft 365 中 SharePoint 的功能。The Migration API supports the ability to migrate web parts to SharePoint in Microsoft 365 using the PRIME package by calling CSOM/REST/SOAP WS to get web part data and properties to build the PRIME package.

這種方法的優點是,您可以在一個呼叫中遷移網頁元件,並改善效能。An advantage of this method is that you can migrate your web parts in one call and improve performance. 當您匯入其相關頁面時,資訊清單會包含網頁元件。The manifest includes the web part as you import its associated page. 當您使用遷移 API 時,您可以放入該頁面上的所有網頁元件。When you use the Migration API, you can put all the web parts you have on that page.

使用序列化程式 DLLUsing the Serializer DLL

這兩個屬性的處理方式必須使用 WebPart 使用者屬性序列化器 DLL 的唯一方式。Two attributes are handled in a unique way that requires using the WebPart User Properties Serializer DLL.

當您建立主要套件時產生 AllUsersPropertiesPerUserProperties 的屬性值的技術挑戰,因為屬性值是 BASE64 編碼的 blob。It's a technical challenge to generate the property values for AllUsersProperties and PerUserProperties when you build the PRIME package because the property values are a BASE64-encoded blob. 該 blob 包含序列化網頁元件屬性和網頁元件連線資訊。That blob contains serialized web part properties and web part connection information.

若要取得序列化的 .dll,請遵循下列步驟:To get the serializer .dll, follow these steps:

  1. 在本機電腦上安裝 SharePoint 遷移工具 (SPMT) 用戶端Install the SharePoint Migration Tool (SPMT) client on your local computer.
  2. 流覽至 SPMT 的安裝位置。Browse to the install location of SPMT.
  3. 找到 microsoft.sharepoint.migration.webpart.serializer.dll ,讓您將它複製到專案中。Locate microsoft.sharepoint.migration.webpart.serializer.dll so you can copy it into your project.

如需支援之網頁元件的完整清單,請參閱:For a complete list of the supported web parts, see:

SchemaSchema

如需 SPWebPart 欄位的說明,請參閱 SPWebPartFor an explanation of the SPWebPart fields, see SPWebPart.

主要網頁元件架構範例PRIME web part schema example

    <!-- SPFile definition -->
    <xs:complexType name="SPFile">
        <xs:sequence>
            <xs:element name="Properties" type="Dictionary" minOccurs="0" />
            <xs:element name="Versions" type="SPFileVersionCollection" minOccurs="0" maxOccurs="1" />
            <xs:element name="WebParts" type="SPWebPartCollection" minOccurs="0" maxOccurs="1" />
            <xs:element name="Links" type="SPLinkCollection" minOccurs="0" maxOccurs="1" />
            <xs:element name="EventReceivers" type="SPEventReceiverDefinitionCollection" minOccurs="0" maxOccurs="1" />
            <xs:element name="VersionEvents" type="SPFileVersionEventCollection" minOccurs="0" maxOccurs="1" />
        </xs:sequence>
        ……
    </xs:complexType>

    <!-- SPWebPartCollection definition -->
    <xs:complexType name="SPWebPartCollection">
        <xs:sequence>
            <xs:element name="WebPart" type="SPWebPart" minOccurs="1" maxOccurs="unbounded" />
        </xs:sequence>
    </xs:complexType>

    <!-- SPWebPart definition -->
    <xs:complexType name="SPWebPart">
        <xs:sequence>
            <xs:choice minOccurs="0" maxOccurs="35">
                <xs:element name="Script" minOccurs="0" maxOccurs="1" />
                <xs:element name="PagedRowset" minOccurs="0" maxOccurs="unbounded" />
                <xs:element name="PagedClientCallbackRowset" minOccurs="0" maxOccurs="unbounded" />
                <xs:element name="PagedRecurrenceRowset" minOccurs="0" maxOccurs="unbounded" />
                <xs:element name="ViewFields" type="SPFieldLinkCollection" minOccurs="0" maxOccurs="1" />
                <xs:element name="ViewData" minOccurs="0" maxOccurs="1" />
                <xs:element name="Query" minOccurs="0" maxOccurs="unbounded" />
                <xs:element name="RowLimit" minOccurs="0" maxOccurs="unbounded" />
                <xs:element name="RowLimitExceeded" minOccurs="0" maxOccurs="unbounded" />
                <xs:element name="Toolbar" minOccurs="0" maxOccurs="unbounded" />
                <xs:element name="Formats" minOccurs="0" maxOccurs="unbounded" />
                <xs:element name="Aggregations" minOccurs="0" maxOccurs="unbounded" />
                <xs:element name="List" minOccurs="0" maxOccurs="1" />
                <xs:element name="MetaData" minOccurs="0" maxOccurs="1" />
                <xs:element name="View" minOccurs="0" maxOccurs="1" />
                <xs:element name="ViewStyle" minOccurs="0" maxOccurs="unbounded" />
                <xs:element name="ViewBody" minOccurs="0" maxOccurs="unbounded" />
                <xs:element name="ViewEmpty" minOccurs="0" maxOccurs="unbounded" />
                <xs:element name="ViewFooter" minOccurs="0" maxOccurs="unbounded" />
                <xs:element name="ViewHeader" minOccurs="0" maxOccurs="unbounded" />
                <xs:element name="ViewBidiHeader" minOccurs="0" maxOccurs="unbounded" />
                <xs:element name="GroupByFooter" minOccurs="0" maxOccurs="unbounded" />
                <xs:element name="GroupByHeader" minOccurs="0" maxOccurs="unbounded" />
                <xs:element name="CalendarViewStyles" minOccurs="0" maxOccurs="1" />
                <xs:element name="CalendarSettings" minOccurs="0" maxOccurs="1" />
                <xs:element name="ListFormBody" minOccurs="0" maxOccurs="1" />
                <xs:element name="Xsl" minOccurs="0" maxOccurs="1" />
                <xs:element name="XslLink" minOccurs="0" maxOccurs="1" />
                <xs:element name="JS" minOccurs="0" maxOccurs="1" />
                <xs:element name="JSLink" minOccurs="0" maxOccurs="1" />
                <xs:element name="ParameterBindings" minOccurs="0" maxOccurs="1" />
                <xs:element name="OpenApplicationExtension" minOccurs="0" maxOccurs="1" />
                <xs:element name="Mobile" minOccurs="0" maxOccurs="1" />
                <xs:element name="MobileItemLimit" minOccurs="0" maxOccurs="1" />
                <xs:element name="Method" minOccurs="0" maxOccurs="1" />
                <xs:element name="WebParts" minOccurs="0" maxOccurs="1" />
                <xs:element name="InlineEdit" minOccurs="0" maxOccurs="1" />
                <xs:element name="Joins" minOccurs="0" maxOccurs="1" />
                <xs:element name="ProjectedFields" minOccurs="0" maxOccurs="1" />
                <xs:element name="SpotlightInfo" minOccurs="0" maxOccurs="1" />
                <xs:element name="Visualization" minOccurs="0" maxOccurs="unbounded" />
           </xs:choice>
        </xs:sequence>

        <xs:attribute name="Name" type="Guid" use="required" />
        <xs:attribute name="ListId" type="Guid" use="optional" />
        <xs:attribute name="ListRootFolderUrl" type="xs:string" use="optional" />
        <xs:attribute name="Type" type="xs:string" use="optional" />
        <xs:attribute name="UserId" type="xs:int" use="optional" />
        <xs:attribute name="DisplayName" type="xs:string" use="optional" />
        <xs:attribute name="WebPartTypeId" type="Guid" use="optional" />
        <xs:attribute name="Assembly" type="xs:string" use="optional" />
        <xs:attribute name="Class" type="xs:string" use="optional" />
        <xs:attribute name="SolutionId" type="Guid" use="optional" />
        <xs:attribute name="Version" type="xs:string" use="optional" />
        <xs:attribute name="BaseViewID" type="xs:string" use="optional" />
        <xs:attribute name="WebPartZoneID" type="xs:string" use="optional" />
        <xs:attribute name="IsIncluded" type="xs:string" use="optional" />
        <xs:attribute name="WebPartOrder" type="xs:string" use="optional" />
        <xs:attribute name="FrameState" type="xs:string" use="optional" />
        <xs:attribute name="Source" type="xs:string" use="optional" />
        <xs:attribute name="AllUsersProperties" type="xs:string" use="optional" />
        <xs:attribute name="PerUserProperties" type="xs:string" use="optional" />
        <xs:attribute name="WebPartIdProperty" type="xs:string" use="optional" />
        <xs:attribute name="ContentTypeId" type="xs:string" use="optional" />

        <!-- For files (major [default] or minor) -->
        <xs:attribute name="Level" type="xs:string" use="optional" />

        <!-- Flags -->
        <xs:attribute name="Flags" type="xs:string" use="optional" />
        <xs:attribute name="Scope" type="xs:string" use="optional" />
        <xs:attribute name="Hidden" type="xs:boolean" use="optional" />
        <xs:attribute name="Threaded" type="xs:boolean" use="optional" />
        <xs:attribute name="ReadOnly" type="xs:boolean" use="optional" />
        <xs:attribute name="RecurrenceRowset" type="xs:boolean" use="optional" />
        <xs:attribute name="FPModified" type="xs:boolean" use="optional" />
        <xs:attribute name="ModerationType" type="xs:string" use="optional" />
        <xs:attribute name="Personal" type="xs:boolean" use="optional" />
        <xs:attribute name="OrderedView" type="xs:boolean" use="optional" />
</xs:complexType>

安全性控制Security controls

伺服器端的安全性控制設計可啟用下列功能:The security control design on the server side enables the following functionality:

  • 如果 NoScript 關閉,請遷移所有網頁元件。If NoScript is off, migrate all web parts.
  • 如果 NoScript 開啟,則必須先檢查網頁元件層級的安全性:If NoScript is on, first check web part level safety:
    • 如果 SafeAgainstScript 為 false,請勿匯入。If SafeAgainstScript is false, don't import it.
    • 如果 SafeAgainstScript 為 true,請檢查網頁元件屬性層級的安全性:If SafeAgainstScript is true, check the web part property level safety:
      • 如果此網頁元件的任何屬性有 RequiresDesignerPermission,請忽略該網頁元件 (或略過此屬性(如果有的話)) 。If this web part has any property that has RequiresDesignerPermission, ignore that web part (or ignore this property if feasible).
      • 否則,請遷移此網頁元件。Otherwise, migrate this web part.

NoScript 開啟時,這些網頁元件將會被視為不受信任網頁元件的伺服器端程式碼 (忽略) :These web parts will be ignored by server-side code (treated as untrusted web part) when NoScript is turned on:

  • XsltListViewWebPartXsltListViewWebPart
  • ContentEditorWebPartContentEditorWebPart
  • ContentByQueryWebPartContentByQueryWebPart
  • SiteFeedWebPartSiteFeedWebPart
  • ScriptEditorWebPartScriptEditorWebPart
  • ContactFieldControlContactFieldControl
  • SearchBoxScriptWebPartSearchBoxScriptWebPart
  • PageViewerWebPartPageViewerWebPart
  • ProfileBrowserProfileBrowser
  • UserTasksWebPartUserTasksWebPart
  • SocialCommentWebPartSocialCommentWebPart
  • SilverlightWebPartSilverlightWebPart
  • RSSAggregatorWebPartRSSAggregatorWebPart
  • SummaryLinkWebPartSummaryLinkWebPart
  • TableOfContentsWebPartTableOfContentsWebPart
  • UserDocsWebPartUserDocsWebPart
  • SPTimelineWebPartSPTimelineWebPart
  • XmlWebPartXmlWebPart
  • SiteDocumentsSiteDocuments
  • CategoryResultsWebPartCategoryResultsWebPart

常見問題集FAQ

如何將網頁元件屬性提取為序列化 API 的輸入?How do I fetch the web part properties as the input for serialization API?

網頁元件屬性可在 WebPartPagesWebService 的 [作業 <webpart> GetWebPartProperties2 回應] 中的元素中找到。The web part properties can be found in the <webpart> element in the response of operation GetWebPartProperties2 in WebPartPagesWebService. 在 WSDL/_vti_bin/WebPartPage.asmx 中尋找 [負載詳細資料] ?WSDLFind the payload details in WSDL /_vti_bin/WebPartPage.asmx?WSDL.

如何將網頁元件連線資訊當做序列化 API 的輸入提取?How do I fetch the web part connection info as the input for serialization API?

網頁元件連線可以 <SPWebPartConnection> 從網頁元件頁面的 [ GetWebPartPage 中的作業回應] WebPartPagesWebService 中找到。The web part connections can be found in <SPWebPartConnection> elements from the web part page in the response of operation GetWebPartPage in WebPartPagesWebService.

範例Examples

範例網頁元件屬性 v2 XmlNode 元素Sample web part properties v2 XmlNode element


  <WebPart xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.microsoft.com/WebPart/v2" ID="1c845edf-42c6-4094-a105-302015642f43">
    <Title>Content Editor</Title>
    <FrameType>Default</FrameType>
    <Description>Allows authors to enter rich text content.</Description>
    <IsIncluded>true</IsIncluded>
    <ZoneID>wpz</ZoneID>
    <PartOrder>0</PartOrder>
    <FrameState>Normal</FrameState>
    <Height />
    <Width />
    <AllowRemove>true</AllowRemove>
    <AllowZoneChange>true</AllowZoneChange>
    <AllowMinimize>true</AllowMinimize>
    <AllowConnect>true</AllowConnect>
    <AllowEdit>true</AllowEdit>
    <AllowHide>true</AllowHide>
    <IsVisible>true</IsVisible>
    <DetailLink />
    <HelpLink />
    <HelpMode>Modeless</HelpMode>
    <Dir>Default</Dir>
    <PartImageSmall />
    <MissingAssembly></MissingAssembly>
    <PartImageLarge>/_layouts/15/images/mscontl.gif</PartImageLarge>
    <IsIncludedFilter />
    <ExportControlledProperties>true</ExportControlledProperties>
    <ConnectionID>00000000-0000-0000-0000-000000000000</ConnectionID>
    <ID>g_d6def51c_7a91_40fe_9f59_de9ceed5c347</ID>
    <Assembly>Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c</Assembly>
    <TypeName>Microsoft.SharePoint.WebPartPages.ContentEditorWebPart</TypeName>
    <ContentLink xmlns="http://schemas.microsoft.com/WebPart/v2/ContentEditor" />
    <Content xmlns="http://schemas.microsoft.com/WebPart/v2/ContentEditor" />
    <PartStorage xmlns="http://schemas.microsoft.com/WebPart/v2/ContentEditor" />
  </WebPart>

範例網頁元件屬性 v3 XmlNode 元素Sample web part properties v3 XmlNode element


  <webPart xmlns="http://schemas.microsoft.com/WebPart/v3">
    <metaData>
      <type name="Microsoft.SharePoint.WebPartPages.XsltListViewWebPart, Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" />
      <importErrorMessage></importErrorMessage>
    </metaData>
    <data>
      <properties>
        <property name="ShowWithSampleData" type="bool">False</property>
        <property name="Default" type="string" />
        <property name="NoDefaultStyle" type="string" />
        <property name="CacheXslStorage" type="bool">True</property>
        <property name="ViewContentTypeId" type="string" />
        <property name="XmlDefinitionLink" type="string" />
        <property name="ManualRefresh" type="bool">False</property>
        <property name="ListUrl" type="string" null="true" />
        <property name="ListId" type="System.Guid, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089">a316c9a6-e664-426b-9069-77cabd22429c</property>
        <property name="TitleUrl" type="string">/Lists/TestPromotedLinks</property>
        <property name="EnableOriginalValue" type="bool">False</property>
        <property name="Direction" type="direction">NotSet</property>
        <property name="ServerRender" type="bool">False</property>
        <property name=" ViewFlags " type="Microsoft.SharePoint.SPViewFlags, Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c">Html, TabularView, Hidden, Ordered</property>
        <property name="AllowConnect" type="bool">True</property>
        <property name="ListName" type="string">{A316C9A6-E664-426B-9069-77CABD22429C}</property>
        <property name="ListDisplayName" type="string" null="true" />
        <property name="AllowZoneChange" type="bool">True</property>
        <property name="ChromeState" type="chromestate">Normal</property>
        <property name="DisableSaveAsNewViewButton" type="bool">True</property>
        <property name="ViewFlag" type="string" />
        <property name="DataSourceID" type="string" />
        <property name="ExportMode" type="exportmode">All</property>
        <property name="AutoRefresh" type="bool">False</property>
        <property name="FireInitialRow" type="bool">True</property>
        <property name="AllowEdit" type="bool">True</property>
        <property name="Description" type="string" />
        <property name="HelpMode" type="helpmode">Modeless</property>
        <property name="BaseXsltHashKey" type="string" null="true" />
        <property name="AllowMinimize" type="bool">True</property>
        <property name="CacheXslTimeOut" type="int">86400</property>
        <property name="ChromeType" type="chrometype">Default</property>
        <property name="Xsl" type="string" null="true" />
        <property name="JSLink" type="string" null="true" />
        <property name="CatalogIconImageUrl" type="string">/_layouts/15/images/itgen.png?rev=23</property>
        <property name="SampleData" type="string" null="true" />
        <property name="UseSQLDataSourcePaging" type="bool">True</property>
        <property name="TitleIconImageUrl" type="string" />
        <property name="PageSize" type="int">-1</property>
        <property name="ShowTimelineIfAvailable" type="bool">True</property>
        <property name="Width" type="string" />
        <property name="DataFields" type="string" />
        <property name="Hidden" type="bool">False</property>
        <property name="Title" type="string" />
        <property name="PageType" type="Microsoft.SharePoint.PAGETYPE, Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c">PAGE_NORMALVIEW</property>
        <property name="DataSourcesString" type="string" />
        <property name="AllowClose" type="bool">True</property>
        <property name="InplaceSearchEnabled" type="bool">False</property>
        <property name="WebId" type="System.Guid, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089">00000000-0000-0000-0000-000000000000</property>
        <property name="Height" type="string" />
        <property name="GhostedXslLink" type="string">main.xsl</property>
        <property name="DisableViewSelectorMenu" type="bool">True</property>
        <property name="DisplayName" type="string" />
        <property name="IsClientRender" type="bool">False</property>
        <property name="XmlDefinition" type="string">&lt;View Name="{2B37E456-6FD3-4708-AC83-5D7B0D13E9B4}" Type="HTML" Hidden="TRUE" OrderedView="TRUE" DisplayName="" Url="/SitePages/TestPage.aspx" Level="1" BaseViewID="3" ContentTypeID="0x" &gt;&lt;Query&gt;&lt;OrderBy&gt;&lt;FieldRef Name="TileOrder" Ascending="TRUE"/&gt;&lt;FieldRef Name="Modified" Ascending="FALSE"/&gt;&lt;/OrderBy&gt;&lt;/Query&gt;&lt;ViewFields&gt;&lt;FieldRef Name="Title"/&gt;&lt;FieldRef Name="BackgroundImageLocation"/&gt;&lt;FieldRef Name="Description"/&gt;&lt;FieldRef Name="LinkLocation"/&gt;&lt;FieldRef Name="LaunchBehavior"/&gt;&lt;FieldRef Name="TileOrder"/&gt;&lt;/ViewFields&gt;&lt;RowLimit Paged="TRUE"&gt;30&lt;/RowLimit&gt;&lt;JSLink&gt;clienttemplates.js&lt;/JSLink&gt;&lt;XslLink Default="TRUE"&gt;main.xsl&lt;/XslLink&gt;&lt;Toolbar Type="Standard"/&gt;&lt;/View&gt;</property>
        <property name="InitialAsyncDataFetch" type="bool">False</property>
        <property name="AllowHide" type="bool">True</property>
        <property name="ParameterBindings" type="string">&lt;ParameterBinding Name="dvt_sortdir" Location="Postback;Connection" /&gt;&lt;ParameterBinding Name="dvt_sortfield" Location="Postback;Connection" /&gt;&lt;ParameterBinding Name="dvt_startposition" Location="Postback" DefaultValue="" /&gt;&lt;ParameterBinding Name="dvt_firstrow" Location="Postback;Connection" /&gt;&lt;ParameterBinding Name="OpenMenuKeyAccessible" Location="Resource(wss,OpenMenuKeyAccessible)" /&gt;&lt;ParameterBinding Name="open_menu" Location="Resource(wss,open_menu)" /&gt;&lt;ParameterBinding Name="select_deselect_all" Location="Resource(wss,select_deselect_all)" /&gt;&lt;ParameterBinding Name="idPresEnabled" Location="Resource(wss,idPresEnabled)" /&gt;&lt;ParameterBinding Name="NoAnnouncements" Location="Resource(wss,noXinviewofY_LIST)" /&gt;&lt;ParameterBinding Name="NoAnnouncementsHowTo" Location="Resource(wss,noXinviewofY_DEFAULT)" /&gt;</property>
        <property name="DataSourceMode" type="Microsoft.SharePoint.WebControls.SPDataSourceMode, Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c">List</property>
        <property name="AutoRefreshInterval" type="int">60</property>
        <property name="AsyncRefresh" type="bool">False</property>
        <property name="HelpUrl" type="string" />
        <property name="MissingAssembly" type="string">Cannot import this Web Part.</property>
        <property name="XslLink" type="string" null="true" />
        <property name="SelectParameters" type="string" />
      </properties>
    </data>
  </webPart>

範例網頁元件 connection XmlNode 元素Sample web part connection XmlNode element

<WebPartPages:SPWebPartConnection ConsumerConnectionPointID="DFWP Filter Consumer ID" ConsumerID="g_bcca2ac1_f0f1_4640_af30_8a0730ca840e" ID="c1638508205" ProviderConnectionPointID="ITransformableFilterValues" ProviderID="g_7fc41891_2e27_4835_99c8_5b6f80feb20f"><WebPartPages:TransformableFilterValuesToParametersTransformer ConsumerFieldNames="PageType" ProviderFieldNames="Page Field"></WebPartPages:TransformableFilterValuesToParametersTransformer>
</WebPartPages:SPWebPartConnection>