Creating a Clean Visual Studio Solution from a SharePoint 2013 Site Template


Quite often for SPDevs it can be useful to reverse-engineer a SharePoint site into code if you need to build a site definition for sites that don’t exist yet. Usually this would mean starting a new project & added each project item by hand but in this example we’re going to start a new VS project by importing an existing site rather than coding everything from scratch.

Many people know about this import functionality but it can be a pain to clean-up, and mainly I aim to show here how it’s a great way you can harness the rapidness of the GUI to create the model you want and then get that into a Visual Studio project. In this guide I’ll show you how to do this but also discarding all the inevitable junk that comes with the bits you want.

This post is all about how to create a SharePoint solution to create new sites with our own master-page, content page(s), and lists, all of which need to self-prevision upon creation. We want a way to quickly be able to do this by designing our phantom site elements with an actual site and then import that into a new Visual Studio SharePoint project, and this guide shows how. For this guide we’ll provision new lists, our own master-page, and a default.aspx page to mirror something the guide I did a while back – SharePoint application development for n00bs - http://blogs.msdn.com/b/sambetts/archive/2012/04/19/sharepoint-2010-apps-for-n00bs-introduction.aspx.

In short, we need to generate our model site; save it as a template, then import that template-file (WSP) into Visual Studio & clean-up said generated project, and finally deploy the solution to the farm. Below is the guide how to do this.

1. Create Template Site in the GUI/SharePoint Designer

First, we need to create our dummy site to model our list and other pieces with. Create new site collection – select template as just a basic team site (nothing with publishing features).

clip_image002

This will create us an almost empty site; not too many crazy fields/content types/lists etc we don’t want, just a bare-bones SharePoint site & site-collection. Less is more; we just want to grab one or two key elements for our new solution from this site.

Now we need to add the lists and other assets we want to import into Visual Studio solution. I’m going to model this example on our previous SPDev example app – the Pet Shop app. We want to make this app reusable so we can sell it to pet-shops around the world and make millions of € of course.

Application Lists

As per the pet-shop previously, we need to add the same lists. Let’s add those custom lists either in SharePoint Designer (SPD) or viewlsts.aspx. The last example if you need a reference for the exact list definitions are @ http://blogs.msdn.com/b/sambetts/archive/2012/04/19/sharepoint-2010-apps-for-n00bs-data-and-lists.aspx but basically we’re talking x2 lists: inventory & sales – sales linking to inventory.

The nice thing about custom lists here is there’s no list template needed so that’s one less dependency but some people like to define the fields at a list template level, then override instances as necessary. That’s way too complicated for us; we just want a basic list for now. In fact, we’re going to create the example in this post but in a Visual Studio solution so we create multiple instances of our “pet-store” application as needed -

clip_image004

Site Master-pages

Now to add our own master-page. SharePoint will give you a default master-page but we want our own modified version of it to be used automatically. We’re going to copy the default master-page; edit it; set it as the temporary site master-page then see that file imported into our yet-to-exist Visual Studio solution.

It’s also good to have available the default master-pages in the site too as a fallback option if necessary. Copy “seattle.master” for SharePoint 2013 (“v4.master” for 2010); rename it to something sensible and edit it. For now we just want to know we’re using our master-page so we’re going to make it hideous looking just for now so there’s no mistake which master-page we’re using – the proper development will come later once we’ve exported it to a solution and we can create sites with it.

So in our custom master I’ve just change the background

clip_image006

When you save this, SPD will mention you’re override the site definition – continue anyway. Overriding the site-defined file mean

Now go back to the list of master-pages. Right click on our one and set as “default master”. The difference between “custom master” and “default master” is for another day.

clip_image008

Now if you refresh the single page of the “blank” site you should see your change:

image

A truly bizarre-looking, but noticeable SharePoint master-page theme.

Default ASPX Page

We want to keep the default page but not the others. Delete the others from “All files”.

clip_image012

Now to make sure we get our own default.aspx we should edit the one in the site now so it differs from the standard site definition and is imported directly into our solution-to-be. That’s to say (for those that may not know), if your project uses just a standard team-site default.aspx (or any other resource) then the file is only referenced but not copied into the solution & referenced. We want the file in the solution because we’re going to mess around with it later so edit it and make a change like we did for the master-page. Find the default.aspx page and edit it in advanced mode so you can change the code (it’s locked otherwise due to no editable regions for n00bs). Now change something in the file so you know it’s being used and not the out-the-box page.

clip_image014

SPD will warn you that you’re changing the file from its original site definition, which is actually exactly what we want so the import will include the file rather than copying the default-installed file that comes with SharePoint.

It’s at this point we’re nearly ready to import whatever we have here into a new Visual Studio solution so make sure everything’s as you want it, especially lists – test them in the dummy site to make sure they behave just as you want. Any validations; modifications are way easier to do now than later; that’s kind of the point of this article 🙂

2. Import Site into Visual Studio

Generate Site Template WSP File

We’re done with our site now but we just one more thing to do. SharePoint has had this excellent template-generating functionality since forever that we’re going to use. The idea is, within the context of an existing site-collection, we can save a site as a template and generate as many sub-sites based on this. We’re essentially hijacking this functionality to kick-start our own Visual Studio project for new site-collections (and sites).

So in the browser, go-to site setting and click this link:

clip_image016

clip_image018

Fill this out with whatever you like & click “OK”. After a bit of thinking, SharePoint should give you a success page:

clip_image020

Click on the solution gallery link (also available in site-settings)

clip_image022

Now we need to download our resulting WSP file to import into Visual Studio. Click it and save somewhere local on your PC ready for import into Visual Studio. We’re now done with our blank site-collection.

Create new Visual Studio Project from WSP

Open Visual Studio 2012 on a machine with SharePoint 2013 installed on too; create a new project of this type:

clip_image024

Click OK.

clip_image026

Make sure this is a farm solution – sandbox solutions are too limited in scope for what we want.

clip_image028

Find the WSP you’ve just downloaded & click next.

clip_image030

Import everything. It’s quicker to delete what’s not wanted than actually unselect everything unwanted.

clip_image031

Once done you’ll get a fairly large solution:

clip_image033

What we’re going to do is delete 95% of what we’ve imported. This is because most of these elements are just standard site fields/content-types/more that are always created as part of standard template provisioning so no need to explicitly define this. Visual Studio doesn’t know what’s standard and what’s yours so imports everything.

3. Clean-up Visual Studio Imported Solution

So now we have the job of ripping out everything we don’t want. In case we delete something accidently, we can always add a new import project to the solution and get everything back again so don’t be too shy removing things.

Clean-up Unwanted Project Items

There’s a lot that we just don’t need. Delete files:

  • Entire content-types folder.
  • Everything in the “Built-In List Instances” folder except “Master Page Gallery”. Moving that item out the folder then deleting the folder is probably the quickest way.
  • Expand the library item children so we can weed out what we don’t want. We’re going to delete all modules that aren’t our master-page or the out-of-the-box one.

clip_image034

Above I’ve highlighted the two modules we want to keep and crossed out what to throw away. How do I know which ones we’re keeping? One module has our custom master-page and the other has a reference in elements.xml to the out-of-the-box file (as touched on earlier, the file isn’t included for this reason; that it comes with the core product). So here’s the section in “Elements.xml” for the module that’ll give us the default master-page:

clip_image036

Whatever module has this reference you need to keep. Rename the legitimate modules to something sensible and delete the others. Continue deleting:

  • “Fields” (all). Most of these come from the standard team-site/core-site definition and will be provisioned again anyway as our base-template for our custom VS site definition is the same.
  • Everything in the “List instances” folder except our two lists (yep, they’re there).
  • Everything in the “Modules” folder except “_SiteTemplates_STS” – that’s our default.aspx module right there. Move it out, rename the module to “default page” and delete the old folder. You’ll notice under the module is the actual default.aspx file that’ll be copied into the root folder of the site; it’s been imported because it’s a non-standard file so does not come with the core product, thus we have to include it. This is exactly what we want.
  • All in “Other elements” folder.
  • PropertyBags.

Now we should have a more reasonable-looking solution

clip_image037

Oops I Deleted a File I Wanted…

If you get too gung-ho and accidently delete something you actually wanted just add a 2nd project to the solution, repeating the import process. So far your Visual Studio solution should be something like this (in my case):

  • Pet Store Solution
    • Pet Store Project (Imported WSP) – all nice & clean now.
    • Add new project here – import all items again.

Once you have your 2nd project with everything ever in again, copy items from it into your cleaned project then unload the 2nd project so you don’t accidently deploy it.

clip_image038

Final Touches – Organise Features

We’re nearly done; just need to clean up and change the features. Visual Studio tries to separate things into relevant features; obviously lists can’t be instantiated without their dependant fields created 1st etc, but it’s kinda irrelevant for us as we’re using either only fields that exist in our list or out-the-box fields (“title” for example). Anyway, let’s finish the job.

We want to delete empty features; they would’ve had stuff in them but after our solution-item massacre, now they look rather sad and empty. In fact we only want x2 features; 1 for the web-template, and another for everything else, given we have no dependencies.

Feature 3 normally has the web-template in. Open it and check – if so, change the scope of the feature to be “farm”. This will let us create new site-collection of that template.

clip_image040

Rename the feature to say “Site Definition”. Now delete every other feature except one. Open it and add all the items to activate with it. Your Visual Studio should look something like this:

clip_image042

Final stage: ONet.xml clean-up. If you deployed and tested now you’d see a big hairy error-message on creating a site saying SharePoint requires a feature with {GUID} to be activated first. That’s because the ONet.xml file is still referencing the old (now deleted) features. Find Onet.XML (under the site definition item) and open it. Next, find the ID of our one remaining feature – in the feature item under “manifest” you’ll see it:

clip_image044

In ONet.xml at the end of the file you’ll see a section “WebFeatures” – these are all the features to be activated @ web (read: sub-site) level. You’ll find references to all the auto-generated features there, the old one’s included. Remove them as so:

clip_image046

That’s it – you’re done!

4. Test Deploy Your Application

Right-click on the project and click “Deploy” (we don’t want to debug as we haven’t got any managed code in the solution yet). Visual Studio will compile & build a WSP; add it to the solution-store; deploy it to the web-application and try to activate any web-level features on the site @ the URL. The truth be told we don’t care if feature activation on an existing site worked because we’re creating our own, so as long as it was deployed to the farm we should be ok.

clip_image047

Your output window should look something like this if it worked, although I’ve already deployed once so Visual Studio cleans up the old solution too. If anyone has any issues here please comment below and I’ll try my best to reply when I can, but there can be many reasons why a deployment from Visual Studio doesn’t work – some legitimate errors, some not.

Now go-to “Create Site Collection” in Central Admin. You should have a new tab “custom” for the templates with our example in (the tab name can be changed).

image

Fill out the details for a new site-collection and create a “pet shop” site. All being well you should see this:

image

Now Start Developing!

Well done - you have a new project with some pretty complicated elements added already without much effort; much quicker a less painfully than if you were to write is all by hand. Now of course you have to actually build the rest of your app.

Cheers,

// Sam Betts

Comments (14)

  1. FrancoisSouyri says:

    nice and concise, just what I needed.  thanks

  2. Ahsan Jawad says:

    How to implemenet webpart on home page.?

  3. That's more complicated – you need to provision the root-site list for the web-part gallery for one thing, but I'll certainly consider putting a guide out if there's interest.

  4. John Ruggiero says:

    There is definite interest in having a web part on the home page. I am migrating a 2010 site template to 2013 and cannot get a web part that appears on the 2010 default page to appear on the 2013 page

  5. Great – I'll have a crack myself and post it up here when I get a chance. It won't be anytime soon but in a week or two I hope!

  6. Michael says:

    I have two questions… Why "Edit" button in site do not work?

    Example, if I want to change "Text Layout".

    Also, what I need to change, if I change default.aspx name example demo.aspx.

    I get 404 error and I have tried edit Elements.xml file.

  7. Hmmm sounds like an ASPX form is probably not being provisioned correctly. I'll take a look and update this article when I can – thanks for the heads-up!

  8. Franco says:

    By chance do you know how to add webparts to the SitePages/Home.aspx page that gets generated when you enable the WikiPageHomePage Feature. I'm trying to create a Web Template using the Team Site template and I'm enabling the mentioned feature to match with what Team Sites do. The problem is the Home.aspx page is empty and I cannot figure out how to add webparts to it. Thanks for any help.

  9. I'll be looking at this soon; check back in a $unitOfTime – just as soon as I can 🙂

  10. RMini says:

    Is this only for On-Prem Sharepoint 2013 or can this be used for SharePoint Online 2013 as well?  It was my understanding that there were limitations with creating/modifying Farm solutions for SharePoint Online 2013 (Office 365).

  11. SharePoint Administration says:

    Wonderful post however I was wondering if you could write a little more on this topic? I’d be very thankful if you could elaborate a little bit further. Thank you!

    <a href="http://staygreenacademy.com">SharePoint Administration</a>

  12. SharePoint Admin says:

    The scope of the referenced feature does not match the scope where it appears in the web template definition

    I'm facing this issue when I try to create a site using the template

  13. Do you mind if I quote a couple of your articles as long as I provide credit and sources back to your website?
    My blog is in the very same area of interest as
    yours and my visitors would certainly benefit from some
    of the information you provide here. Please let
    me know if this alright with you. Thanks!

    1. No problem! Thanks for asking.

Skip to main content