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
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
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.
This is my awesome
<!-- Content element identifies the
location of the page that will render inside the client web
Properties are referenced on the query string using the
<!-- Define properties in the Properties
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"
You can pass properties from the the user enters from
ClientWebPart itself to the page here, but we'll cover that in
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
Here's what my complete page looks like.
<%@ Register Tagprefix="WebPartPages"
Assembly="Microsoft.SharePoint, Version=126.96.36.199, Culture=neutral,
<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
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.
This blog was first published by Corey Roth on Dot Net Mafia. Check out our
resource centre for more
SharePoint content from Corey and other SharePoint specialists!
Booking Offer of €795 available until end
of September. Book NOW >> Meet and
connect with the European SharePoint Community at the conference in
Copenhagen, 4-7 Feb 2013. Be a part of it!