Dot Net Mafia

Group site for developer blogs dealing with (usually) Ionic, .NET, SharePoint, Office 365, Mobile Development, and other Microsoft products, as well as some discussion of general programming related concepts.

This Blog



Corey Roth [MVP]

A SharePoint MVP bringing you the latest time saving tips for Ionic, SharePoint, and Office 365.

How to: Build a SharePoint-hosted Client Web Part in SharePoint 2013

NOTE: This post is build with Visual Studio 2012 RC and Preview 1 of the Office Developer Tools.  See this post for an update with Preview 2 of the Office Developer Tools and the RTM version of SharePoint 2013.

I am extremely interested in the new SharePoint 2013 App model so I have been doing a lot with them lately.  The latest thing I was trying was building a SharePoint-hosted Client Web Part.  I have found that there is not a lot of information out there yet on how to use these so I wanted to share some of the things I ran into.  This post on MSDN is good to help you get started with the setup of your app.  Hopefully this info will help you get started.  This post assumes you have installed Visual Studio 2012 RC as well as the SharePoint development tools.

After you open Visual Studio 2012 RC, create a new SharePoint app by choosing Office / SharePoint –> Apps –> App for SharePoint 2013.


You’ll then be prompted for the type of app as well as a name and deployment location.  For the deployment location, you need to specify the URL to a site created with the Development Site template.  I created a new site collection for this.  I am not sure if it is required or not but I am fairly certain it is.


At this point, you’ll have a new SharePoint-hosted App project.  Now, we just need to add the pieces that we need.  However, first you need to understand a little bit about the ClientWebPart.  This new type of web part is essentially two pieces: an elements.xml file and an .aspx page.  The elements.xml file performs many of the same functions as a .webpart file, but it has different parameters.  It’s main purpose is to specify the path to a .aspx page which it then loads in an IFRAME.  Since it is an IFRAME, this page can actually be hosted anywhere: locally, on a remote web server, or in Azure.  However, hosting it locally inside SharePoint is by far the simplest.

We’ll create the Client Web Part using the New Item menu:


When the Client Web Part is created, you’ll get an XML file that looks like this.


You can update the Client Web Part title, description, and size here.  Note, that end users can’t change the size of the Client Web part once it’s deployed so set the value correctly here.  Note the Content element. We need to update this value to the location of the associated page we are about to create. We need to specify the URL to the page associated with our ClientWebPart.  To do this we make use of the ~appWebUrl token and then just specify the relative path Pages/HelloWorldClientWebPart.aspx.  Here is what the entire XML looks like.

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

<Elements xmlns="">

  <ClientWebPart Name="HelloWorldClientWebPart" Title="HelloWorldClientWebPart" Description="This is my awesome HelloWorldClientWebPart." DefaultWidth="300" DefaultHeight="200">


    <!-- Content element identifies the location of the page that will render inside the client web part

         Properties are referenced on the query string using the pattern _propertyName_

         Example: Src="~appWebUrl/Pages/ClientWebPart1.aspx?Property1=_property1_" -->

    <Content Type="html" Src="~appWebUrl/Pages/HelloWorldClientWebPart.aspx" />


    <!-- Define properties in the Properties element

           Remember to put Property Name on the Src attribute of the Content element above


      <Property Name="property1" Type="string" WebBrowsable="true" WebDisplayName="First Property" WebDescription="Description 1" WebCategory="Custom Properties" DefaultValue="String Property" RequiresDesignerPermission="true" />

    </Properties>   -->




You can pass properties from the the user enters from ClientWebPart itself to the page here, but we’ll cover that in another post.

Now, we need to create the page that will be loaded in the IFRAME by the Client Web Part.  For simplicity, I go with the same name as the Client Web part. 


The default page looks like this.


It’s this part where I couldn’t find any details on how to proceed.  You might be wondering if you need to do something to this page before it will work in a Client Web Part.  The answer is “yes”.  If you do try to deploy it as is, you’ll get the following error when trying to use the Client Web Part.

This content cannot be displayed in a frame.


Luckily, Saurabh Bhatia came through for me in the forums and helped me out.  You need to include the AllowFraming tag in your page to allow it to render in an IFRAME.  Everything else in the page needs to go with the exception of the reference to the WebPartPages tag.  If you leave references to the master page or content place holders, you’ll receive a heap of JavaScript errors.  Here’s what my complete page looks like.

<%@ Register Tagprefix="WebPartPages" Namespace="Microsoft.SharePoint.WebPartPages" Assembly="Microsoft.SharePoint, Version=, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>

<WebPartPages:AllowFraming ID="AllowFraming1" runat="server" />

<div>Hello World Client Web Part!</div>

At this point, we are ready to deploy.  You can do so by pressing F5 or choosing Build –> Deploy.  This will package your app and after a moment, you’ll see your app listed.


This is a Client Web Part so you don’t need to click on your App here.  Instead, go to the Home Page and then edit it.  Pick a place on the page and then click on Insert in the ribbon.  You’ll notice this looks a bit different, choose App Part and you’ll see your new Client Web Part listed.


You might be wondering what the difference between this and Web Parts are.  Not much really.  If you click Web Part and then choose Apps and you’ll see the same list.


If all goes well, your Client Web Part should now be visible on the page.  You may be prompted for authentication again when it loads.  You can adjust your browser security settings to avoid this.


At this point, you have a working Client Web Part.  You can then make use of the Client Object Model or the new REST API to interact with SharePoint.  I hope this helps you get started with building some apps.  Try it out and see what you can do.

UPDATE: To use the JavaScript Client Object Model with an App Part, see this post.



SharePoint Daily » Blog Archive » Build a SharePoint 2013 Web Part; Fighting for the Workplace; Free Microsoft eBooks said:

Pingback from  SharePoint Daily  &raquo; Blog Archive   &raquo; Build a SharePoint 2013 Web Part; Fighting for the Workplace; Free Microsoft eBooks

August 2, 2012 7:48 AM

SharePoint Daily said:

Microsoft is building a robotic &quot; big brother &quot; to watch over you at work. - Dooley Top News

August 2, 2012 7:57 AM

Hilton Giesenow said:

Hey Cory,

thanks for the intro. One typo, I think. For "If all goes well, your Client Web Part should not be visible on the page.", I think you mean "...should NOW be visible..."

August 2, 2012 3:16 PM

CoreyRoth said:

Thanks Hilton for the catch.  I've updated the post.

August 2, 2012 3:30 PM

Peso said:

The part with the AllowFraming tag is mentioned in the offical Microsoft Developer Videos ;-) The particular one I think of is from Scot Hillier. You should definitely watch them.

August 3, 2012 12:01 AM

The Microsoft MVP Award Program Blog said:

1. Creating OData Service Using WCF By Visual C# MVP Amit Choudhary – @vendettamit 2. Active Directory

August 10, 2012 4:05 PM

UpSearch said:

Pingback from  UpSearch

August 10, 2012 7:14 PM

UpSearch said:

Pingback from  UpSearch

August 10, 2012 7:15 PM

Friday Five???August 10, 2012 | MSDN Blogs said:

Pingback from  Friday Five???August 10, 2012 | MSDN Blogs

August 11, 2012 9:00 AM

Friday Five???August 10, 2012 | MSDN Blogs said:

Pingback from  Friday Five???August 10, 2012 | MSDN Blogs

August 11, 2012 10:00 AM

Hannes said:

Hi Corey,

Thanks for the information.

Referring to the folling excerpt from your post:

"You can pass properties from the the user enters from ClientWebPart itself to the page here, but we’ll cover that in another post."

Could you please direct me to the location of this post, if it exists?

I have a situation like this: SharePoint-Hosted WebPart with a custom property. The user should be able to enter a value for the property which should then be sent to the WebPart to alter appearance and behaviour. Error handling might also be necessary.

Thank you in advance for your time and effort.

Kind regards,


August 23, 2012 3:23 AM

UpSearch said:

Pingback from  UpSearch

August 26, 2012 1:25 PM

UpSearch said:

Pingback from  UpSearch

August 26, 2012 7:43 PM

UpSearch said:

Pingback from  UpSearch

August 26, 2012 11:26 PM

UpSearch said:

Pingback from  UpSearch

August 26, 2012 11:33 PM

UpSearch said:

Pingback from  UpSearch

August 27, 2012 6:32 AM

CoreyRoth said:

@Hannes I haven't had a chance to right it yet but I should have it in the next week or so barring any unusual circumstances.

August 29, 2012 6:38 PM

Sara said:

Very useful information.

One big area that I have enjoyed looking into SHarepoint 2013 is the area of Social within SharePoint. In the past, social elements such as My Sites and tagging were nice, but they didn’t really drive me to use them. Within 2013, the story changes. So much more is available and the changes are great improvements that will drive Social sites to be the central hub for a user.

- Sara

September 4, 2012 4:19 AM

Blog del CIIN said:

Os dejo un primer recopilatorio de recursos sobre el nuevo modelo de Aplicaciones de SharePoint 2013

October 5, 2012 6:51 AM

SharePoint 2013: Recursos sobre el nuevo modelo de creación de aplicaciones (I)! « Pasi??n por la tecnolog??a… said:

Pingback from  SharePoint 2013: Recursos sobre el nuevo modelo de creaci&oacute;n de aplicaciones (I)! &laquo; Pasi??n por la tecnolog??a&#8230;

October 5, 2012 6:55 AM

Getting started with building apps for SharePoint 2013 « Software Architecture Blog said:

Pingback from  Getting started with building apps for SharePoint 2013 &laquo; Software Architecture Blog

November 19, 2012 3:18 PM

Vijay Arul Lourdu said:


Thanks for the great post.I am trying to achieve the same with the custom app part properties also.

for example working fine in IFRAME

<Content Type="html" Src="~appWebUrl/Pages/Home.aspx"/>

i am exactly getting the Provider Hosted app web in IFRAME.

But when i am trying to do the same with custom app part properties.


I have a html file for reading the properties and i am navigating to the Provider host web in Appmanifest.xml file.

when i have properties its opening in different window than IFRAME.

Is it possible to open the Provider hosted app web in IFRAME along with custom app part properties.

i have used the cofee maker app part sample in

December 4, 2012 7:04 AM

Matt Ranlett said:

The HTML version specified in the MSDN examples require in newer builds the inclusion of the 405 fix - a handler for static files.  Works great on the app part but no other pages for that app will work - they get rendered as flat HTML

December 21, 2012 1:38 AM

Nick Johnson said:

Thanx for explaining a complex structure in a very simple way. Screen-shots attached became very helpful in understanding the whole process.....

March 1, 2013 4:10 AM

sandronikos said:

I followed all the steps & I get an error like:

Warning 1 File '~masterurl/default.master' was not found. What am i doing wrong ?

March 1, 2013 8:49 AM

CoreyRoth said:

@Nick Thanks!

@sandronikos I haven't seen it before.

April 11, 2013 10:18 PM

Use the SharePoint 2013 Client Object Model (SP.js) from a Client Web Part said:

Pingback from  Use the SharePoint 2013 Client Object Model (SP.js) from a Client Web Part

July 10, 2013 10:29 PM

Alex said:

Hi Corey,

Thanks for the clear get started tutorial. I succeeded to make it works, but I still have an issue that you don't seems to face in your post :

I'm seeing the top ribbon of the void master page in the WebPart, and not only the content.

It appear you kept the 4 directives on the top of the aspx page. If I remove those, it won't work anymore, if I keep it, I see the complete page in the iframe (top ribbon, link to get back to the SP site, ...)

if you got 2 min, thanks for your help,


March 24, 2015 9:01 AM

CoreyRoth said:

@Alex it should work.  You can try removing the master page attribute from the page directive.

March 24, 2015 10:22 AM

Alex said:

@CoreyRoth finally I got rid of SharePoint hosted application, and moved to a provider-hosted one. It better fill my needs, as I wanted to stay on the same domain name when integrating app in a page (i'm using self-signed certificate, so from the iframe, it will be displaying a warning for the certificate).

March 27, 2015 4:53 AM

Build a SharePoint 2013 Web Part; Fighting for the Workplace; Free Microsoft eBooks – Bamboo Solutions said:

Pingback from  Build a SharePoint 2013 Web Part; Fighting for the Workplace; Free Microsoft eBooks &#8211; Bamboo Solutions

June 6, 2016 2:46 AM

Leave a Comment


About CoreyRoth

Corey Roth is an independent SharePoint consultant specializing in ECM, Apps, and Search.
2018 dotnetmafia.
Powered by Community Server (Non-Commercial Edition), by Telligent Systems