Loading custom web parts inside your Onet.xml

How would you go about adding a custom built web part to a page in a site definition? MSDN shows an example using the <AllUsersWebPart> tag in the <module> section of a site definitions onet.xml file. Inside there is a CDATA area where it uses some more (presumably) XML to define and configure the web part. You can check out the example here: MSDN’s AllWebUsersWebPart page. I had some issues adapting this to my own custom built web parts, which made me come up with the solution in this article instead.

Here is an example of one of my Onet.xml files:

<?xml version="1.0" encoding="utf-8" ?>
<!-- _lcid="1033" _version="12.0.2220" _dal="1" -->
<!-- _LocalBinding -->
<Project Revision="1" Title="Home page" ListDir="Lists" xmlns:ows="Microsoft SharePoint">
    <NavBar Name="SharePoint Top Navbar" ID="1002">
    <Configuration ID="0" Name="Web Home" MasterUrl="~SiteCollection/_catalogs/masterpage/ClientIntranetBaseMaster.master">
        <Module Name="$Resources:Client.Publishing.Intranet.SiteTemplates,module_Home_Name;" />
    <Module Name="$Resources:Client.Publishing.Intranet.SiteTemplates,module_Home_Name;" Url="$Resources:cmscore,List_Pages_UrlName;" Path="">
      <File Url="default.aspx" NavBarHome="True" Type="GhostableInLibrary">
        <Property Name="Title" Value="$Resources:Client.Publishing.Intranet.SiteTemplates,module_StartPage_Title;" />
        <Property Name="PublishingPageLayout" Value="~SiteCollection/_catalogs/masterpage/ClientIntranetLanding.aspx, ~SiteCollection/_catalogs/masterpage/ClientIntranetLanding.aspx" />
        <Property Name="ContentType" Value="Client Intranet Publishing Page" />
        <AllUsersWebPart WebPartZoneID="Header" WebPartOrder="1">
             <webPart xmlns="<a href="http://schemas.microsoft.com/WebPart/v3">http://schemas.microsoft.com/WebPart/v3</a>">
                 <type name="Client.Publishing.Intranet.WebParts.ClientStoryRotator,Client.Publishing.Intranet.WebParts, Version=, Culture=neutral, PublicKeyToken=320209e28e1f8058" />
                   <property name="Title" type="string">$Resources:Client.Publishing.Intranet.Lists.Articles,list_Stories_Title;</property>
                   <property name="Description" type="string">$Resources:Client.Publishing.Intranet.Lists.Articles,list_Stories_Description;</property>
                   <property name="ListName" type="string">$Resources:Client.Publishing.Intranet.Lists.Articles,list_Stories_Title;</property>
                   <property name="WebName" type="string">$Resources:Client.Publishing.Intranet.SiteTemplates,webpart_Library_Url;</property>
                   <property name="Width" type="string">$Resources:Client.Publishing.Intranet.SiteTemplates,webpart_Stories_Width;</property>

I’ve collapsed some of the nodes here just to make it a little more managable. Notice how the web part is being referenced in a different way then the example presented in the MSDN article for AllUsersWebPart. Here is a small breakdown of what I’m doing.

<type name=”” />

This specifiec the namespace and class name of your web part, as well as the version, culture and public key. You can obtain these values by using .Net reflector on your DLL file.


This is the message that will appear if the web part was not loaded correctly.

<properties> and <property name=””>

You can set the properties of any custom (or default) properties in your web part here. Notice how in the example I’ve referenced Title, Description and Width, which are all default properties that all web parts have in common. Then in addition I have WebName and ListName which refer to two properties that was included in that specific web part.

Here’s a sort code snippet from my web part showing the declaration of one of these properties:

[Description("Root relative URL of the Site which contains your story library (/MyWeb)")]
public string WebName
  get { return _webName; }
  set { _webName = value; }


  1. Hi all,

    I’ve edited the ONET.XML file of my site collection in order to add my custom webpart when a new site is created.

    But I had to create a new site collection (PWA in my case), if i wanna see my WebPart added in the new sites.

    What is the trick to apply the change of my ONET.XML file in the current site collection ??

    Thank you

    • You can’t.

      Changes to Onet.xml are only applied when creating a new site collection based on that site definition. You can’t modify it to change an already existing site collection.

      If you want to add a web part to already existing site, you’d have to either write a feature or a powershell script.

Leave a Reply

Your email address will not be published. Required fields are marked *