Home > sharepoint, wspbuilder > Developing SharePoint Solutions in Visual Studio

Developing SharePoint Solutions in Visual Studio

SharePoint is built on top of .net, but is not like a regular webpage. SharePoint uses a process of storing information in databases and using files on the server (in the 12 hive – which we will talk about later). When a SharePoint site is created it uses the files in the 12 hive to dynamically create all the information in the database to create the actual site. Some of the information it stores in the database is just references to files on the server (in the 12 hive). Thus, when developing for SharePoint we should modify the files in the servers 12 hive to create customizations (actually, we should never modify the out-of-the-box files on the 12 hive, we should just create new files for our customizations). This way our SharePoint pages will have references to our custom files in the servers 12 hive and will use those custom files to create the site, as well as keep the references to these custom files. Keeping these references around is a concept call ghosting. If you try to customize SharePoint any other way (SharePoint designer, site templates, etc…) you will un-ghost your site. This basically means you are losing the references to the 12 hive and it makes a copy of everything directly in the database. This can be a bad thing because you won’t have one place to make changes for all your sites. On a side note: I have heard the argument un-ghosting is not that bad because of master pages (as long as all your sites reference the same master page). I don’t buy this argument, because there are changes you can make outside of the master page that you want to keep ghosted still. An example of this would be your web zone layout in your aspx pages.

So, you can create site definitions and features in .net and push them out to the servers 12 hive in order for SharePoint to use them. Site definitions are custom xml files and aspx pages that create the webpages for SharePoint and reference the Features to activate within the SharePoint site. Features, which can be activated on the site definition, wrap all the actions we can do on SharePont. If you want to create lists – wrap them in a feature that can be activated. If you want to create webparts – wrap them in a feature that can be activated. Basically, if you want to create things in SharePoint – wrap them in a feature that can be activated. One of the great advantages of building custom Site Definitions is that we have complete control over which features get automatically activated on our site (thus, the features do not have to be manually turned on in the SharePoint site settings).

Site Definitions should always be used to create sites if you want to do true development modifications. You should not use Site Templates if you are a developer (believe me, you will regret using Site Templates if you ever have to modify them or if something goes wrong in them). SharePoint is built upon this concept of Site Definitions and Features for all of the out-of-the-box sites that you can create. Thus, following the SharePoint model of creating Site Definitions is the best option available to us as developers.

Below I am showing how to create a custom SharePoint solution in Visual Studio. I am leveraging a third party tool called WSPBuilder. Using WSPBuilder, or any third party tool, is not required to build solutions, but I have found that it makes life easier. This solution will create features and site definitions and package them up into a wsp file. A wsp file is like an install file for SharePoint (in fact, it actually is a cab file renamed). The acual feature we will be creating in this demo is a feature to deploy a master page to the master page gallery in the SharePoint site. However, following these techniques you can deploy any feature and activate it in a site definition.

1.   Installs

      The recommended way to develop in SharePoint is a Virual Environment – whether VPC or VMWare or any other kind of Virtual Environment. The reason is you need to develop on a SharePoint machine which needs to be on a server. And, it is really hard to get a dedicated server machine just to develop on. If you want to share a server with other developers it is really hard to develop in SharePoint because of the constant App Pool Recycles that are needed. Also, a virtual environment lets us make backup points for the whole server, so if we mess up the environment we have a good snapshot to roll back to. Thus, a virtual environment, in which each develop can have their own virtual server, with their own virtual SharePoint environment is the best way to develop in SharePoint.

a.      WSS or MOSS server

b.      Visual Studio 2005 or 2008

c.      WSPBuilder (version 1.01)


2.    Start Visual Studio and choose a new WSPBuilder project.



3.    Create a folder structure for the solution that matches the folder structure for the SharePoint 12 hive (this is really important – WSPBuilder works on the premise that the Visual Studio solution matches the structure of the SharePoint 12 hive). For now we are just going to create the following folders:

a.   1033 – holds the xml files that will tell SharePoint about our new site definitions

b.   Features – holds the new features we are going to build (i.e.: lists, webparts, master pages, etc…)

c.    Layouts – holds our reference files (i.e.: images, css, js, etc…)

d.   Site Templates – holds our site definitions


Server 12 hive structure



VS Solution



4.       Create a new site definition based off the team site definition in SharePoint.

a.   Copy the team site definition folder from the 12 hive:

C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\SiteTemplates\sts

b.   Paste the folder in the Visual Studio solutions SiteTemplates folder.

c.   Rename the sts folder to something unique (DemoCompanySiteDef for this example)

d.   Delete the defaultdws.aspx file because we aren’t going to use it for this example.


e.    Open the default.aspx file and change the master page to a new master page. Call this custom.master (yes, I know that this is not the name of our master page. We are going to configure SharePoint to do a string replacement of custom.master with DemoCompany.master in later steps). We will create this master page in the next step.


f.     Open the Onet.xml file (located in the xml folder) and clean it up for our simple site definition.

The Onet.xml file is the file that tells SharePoint how to create the site definition. Whenever you create a new site in SharePoint it reads from the Onet.xml file to determine how to create the site. It is important to note that SharePoint is reading from the Onet.xml file when the site is being created. So, if you already have created a site, you can’t go back to the Onet.xml file, make changes, and expect it to show up on your already created sites. On a side note: I heard that Onet stands for Office Net.

                                   i.     Scroll down to the Configurations XML nodes and remove 2 configurations:

1.       ID=1  – Blank

2.       ID-2 – DWS

      Be very careful not to remove ID=0 – Default because this is the configuration we are going to use for this site definition. When removing the other two get rid of the whole xml tag as well as everything within their xml tag.

                                   ii.    Scroll down to the Modules XML nodes and remove 2 modules:

1.       DefaultBlank

2.       DWS

      Once again, be very careful not to remove the Default module because this is the module we are going to use for this site definition. When removing the other two get rid of the whole xml tag as well as everything within their xml tag.

5.    Create the new master page feature

The master page will be created as a feature. The reason for this is that if the master page is in a feature the page can be added to the master page gallery of SharePoint. This allows you to set out-of-the-box pages to the master page or your own custom site definitions. It also allows you to turn on or turn off the master page features on specific sites. Basically, having it in a feature (rather than directly in the site definition or in the layouts folder) gives you much more flexibility.

a.    Create a new folder under features and call it something unique for your master page. For this example we will call it DemoCompanyMasterPage.

b.    Create a folder under the DemoCompanyMasterPage called “MasterPages”.

                            i.      Copy the general SharePoint master page from the 12 hive: C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\GLOBAL\default.master

                           ii.      Paste the file under the “MasterPages” folder in the Visual Studio solution.

                           iii.     Rename the file to something unique (DemoCompany.master for this example).

c.      Create two xml files under the DemoCompanyMasterPage folder.

                           i.      Feature.xml – this will give a unique GUID to the feature (which we will reference later). This file also gives some important information about the Scope of the feature. Lastly, this file tells SharePoint where all the other files that make up this feature lives. This file must be called feature.xml (this is because SharePoint will read all files called feature.xml from the Features folder).

Please note that the Scope=”Site”. This is very important. This is telling SharePoint that this feature is for the site collection. If that Scope=”Web” then it would be telling SharePoint that this feature is for an individual site.


                           ii.      Elements.xml – this file is telling SharePoint to place the new master page into the master page gallery. This file does not have to be called elements.xml (unlike the feature file which has to be called feature.xml). It just has to match the name located in the “ElementManifest” of the feature.xml file.


6.    Modify the site definitions onet.xml file to tell the site to install and use this new masterpage feature when a new site is created.

a.    Open the onet.xml file in Visual Studio (located at SiteTemplates/DemoCompanySiteDef/xml).

b.     Find the xml node that says Configuration ID=0 Name=”Default”.

c.     Add in a reference for the new master page: 

Note: SharePoint will do a string replacement of any aspx page with ~masterurl/custom.master with the reference in CustomMasterUrl. And, it will replace any aspx page with ~masterurl/default.master with the reference in MasterUrl.

d.   Find the SiteFeatures XML node.

e.   Add a new Feature node in there that matches the GUID of the feature.xml file we created for our master page.


This section of the onet.xml basically tells the site to activatethis particular feature on this particular site when it is being created. The reason it goes into the SiteFeatures (instead of the WebFeatures) is because this particular feature was scoped for a Site Collection (refer to step 5c where we created the feature and scoped it for a Site Collection). If the feature was scoped for an individual site then it would go in the WebFeatures.


7.    Create the WebTemp*.xml file

WebTemp*.xml files tell SharePoint about site definitions. When a new site is being created in SharePoint the “Select Templates” list box is populated by anything it can find in the WebTemp*.xml files. There can be multiple of these files in SharePoint as long as they are in the 12/Template/1033/XML folder. SharePoint will basically read this folder for any file that starts with the word WebTemp.

a.    Add a new folder under 12/Template in our Visual Studio solution called 1033. Then, add a new folder under 1033 called XML.

b.    Add a new file to the 12/Template/1033/XML folder in our Visual Studio solution. This file must start with WebTemp. We will call this file WebTempDemoCompany.xml.


c.       Add in the proper xml to tell SharePoint about our new site definition


A few things to note:

    The Name must match the site definition folder exactly. We used the name DemoCompanySiteDef. This matches our site definition name exactly.


    The Configuration ID must match the configuration ID in our onet.xml file of our Site Definition. We used configuration id 0.

     The display category will create a new tab on the new site screen in SharePoint.

     The ID has to be unique and SharePoint has already reserved certain IDs. To be safe use an ID over 10000 and make sure it is unique.


8.    Now, at this point (in a regular SharePoint solution) we would create manifest.xml and ddf files. These are files SharePoint needs to install the solution properly. However, since we are using WSPBuilder, it will do that for us.

a.     Right click the project and click WSPBuilder – Build


b.    Verify your Web Application is created on your local SharePoint environment. Note: the Site Collection should not be created at this point, just the Web Application. And, you only need to do this once.

c.     If the build is successful, right click the project and click WSPBuilder – Deploy.

This is needed because the build command in WSPBuilder just builds a wsp file. This file can be sent to other machines and you can use stsadm scripts to install it on other SharePoint farms. However, in development, we need a quick way to deploy it to the current SharePoint farm. The WSPBuilder – Deploy command will deploy the wsp file on all the Web Applications in the local SharePoint farm.


9.    Open up SharePoint Central Administration and create a new Site Collection with the site definition we just created.


Now you can go back and modify the master page or default.aspx page as you wish. Just be careful not to mess with the ContentPlaceHolders too much. SharePoint reserve these for certain actions on some of its internal pages. After every change you make you can rebuild by clicking WSPBuilder – Build and update the solution by clicking WSPBuilder – Deploy. Then you can just go to the website and see your changes. Just be aware that everytime you deploy WSPBuilder does an app pool recycle (to ensure the changes get pushed out through IIS), so you might have to wait a few seconds to see your changes (during that few seconds the site could say Service Unavailable).

It is also important to note that the first time you deploy with WSPBuilder it does a true SharePoint install. However, every subsequent time it does a SharePoint solution update. Solution updates work for most changes, however, there are some things it can’t do. So, if you run into errors it is sometimes good to do WSPBuilder – Uninstall and then a WSPBuilder-Deploy to do a real install in certain situations when you are making changes.

If you are curious to what a SharePoint solution is doing, then just check out the files in the 12 hive:

C:\Program Files\Common Files\Microsoft Shared\web server extensions\12

You will notice that all the files we created in our Visual Studio solution have been “pushed” down to the folders in the 12 hive. The WSP knows to “push” these files there. The WSP also knows to tell SharePoint that these files exist. This is exactly how SharePoint develops it’s out of the box site definitions (they are all located in the 12 hive and you can actually go and see them).

Because this blog is starting to get long I am not going to show how to create other features, but the principals are the same:

      Create the feature and note the “Scope” you set it to

      Go to your Onet.xml file, of your site definition, and place a reference to the GUID of the feature in the appropriate xml tag (SiteFeatures or WebFeatures).

      Now that feature is associated with the particular Site Definition every time a new site is created with the selected Site Definition

The other features you can create in SharePointis a pretty long list. These include custom lists, webparts, custom actions, features that call other features, custom code that runs after another feature is created, etc… The key point I am making in this blog is that when you learn how to create another type of feature, you can just added into this solution and tie it to your site definition in the onet.xml file.

Side Notes:

1.    Any file you place in the Layouts folder can be reference in the aspx pages as “/_layouts/{filename}”. I usually recommend placing another folder under Layouts in the Visual Studio solution (just because it makes it easy to find later – you can call this folder the name of your company or the name of your project or anything that is obvious that it contains your custom reference files). Then you can reference everything in there by “/_layouts/{folder}/{filename}”. An example of this is css files in the master page. This is possible because SharePoint sets an IIS path up to the Layouts folder in the 12 hive and calls it _layouts.

2.    If you want to create a custom webpart with WSPBuilder just click Add – new item… WSPBuilder – WebPartFeature. This will create the feature folder, for your webpart, and the .cs class for your webpart. This way you can go directly into coding and not have to worry about the Feature creation. Once you are done coding the webpart just make sure it is in the appropriate scope of your onet.xml file (SiteFeatures or WebFeatures) and it will become available to you in your webpart gallery. Then all you have to do is worry about your dll being installed in the Bin or GAC. If you choose GAC I recommend post-build scripts to move it.

3.    Do not remove Content Place Holders from your master page if you start doing customizations. The reason for this is if you assign other files in SharePoint (such as list pages) to use your master pages, they will assume certain Content Place Holders exist. If they are not there, your site will just break.


Since I wrote this I was informed that my demo only works for the top level page (i.e.: the site collection). If you use the code above on a sub-site, it won’t work. The reason is the example deals with the “Site” scope only. There are two ways to fix this for sub-sites:

1. Change the example to “Web” scope. This will place the master page in the master page gallery for each sub-site. To do this you need to change the feature.xml file to scope=Web. And, you need to change the onet.xml file to have the feature registered under the “WebFeatures” instead of the “SiteFeatures”.

2. In the Configuration node of the onet.xml, where we set the CustomMasterUrl and the MasterUrl to _catelags/masterpage/DemoCompany.master – we should replace those to point to ~SiteCollection/_catalogs/masterpage/DemoCompany.master. This approach will just point all the site definitions to use the master page at the root site collection level. 

Categories: sharepoint, wspbuilder
  1. Anand Balasubramanian
    May 18, 2008 at 8:26 pm


    Thanks a lot for posting the demo material to your blog right away as promised. It will be very useful to know more about what you spoke about yesterday and try it out pretty soon. I have already started setting up the Virtual Server so that I can go ahead and install all the required software to run my own server instance.

    Thanks once again,

  2. May 20, 2008 at 7:29 am


    I followed the steps as mentioned by you to create a site definition and define my own master page as a feature. The solution deployed successfully but when i tried to create a new site collection using that site definition in my sharepoint server then it simply gave the error –

    Feature ‘6a27ee94-cbe3-4ade-9b6f-a2280eb05311’ is not installed in this farm, and can not be added to this scope.

    I tried the uninstall-deploy routine again with no luck. Please tell me, what is wrong with my feature definition.

    Sabah Tahir

  3. Greg Galipeau
    May 20, 2008 at 12:48 pm

    The error is basically saying your feature is not getting installed correctly. It seems that your onet.xml file is referencing the guid ‘6a27….’ in order to activate it. However, SharePoint does not see that feature installed at the scope you are referencing it at. That means, there is something wrong with your actual feature, the deployment of the feature, or you have the wrong guid.
    First, double check the guid ‘6a27…’ and make sure that matches the feature.xml file exactly.
    Second, make sure the feature folder got moved to the servers 12 hive during deployment (just go check the 12 hive to see if it is there).
    Third, go to Central Administration/Operations/Solution Management. Click on your solution and make sure it got successfully deployed to the web application in which your site collection is on. Or, make sure it says globally deployed.
    Lastly, if all that fails. Retract the solution in Central Administration/Operations/Solution and then go back to WSPBuilder and Re-deploy the solution (I have found retracting and removing the solution in Central Admin works better than the uninstall in WSPBuilder sometimes). Make sure the web app is already created before you do this and then go and recreate the site collection.

    If those steps fail, then there is probably something very small wrong in one of the files. This is one of the biggest issues with SharePoint, you will not get good errors to tell you exactly what is going on. I spend a lot of time pounding my head because of one little mistype in an xml file.

    Good luck.

  4. May 21, 2008 at 2:29 pm

    Thanx for the response Greg. After my numerous hit & trails (i have to resort to those techiques !!) i finally solved the issue. It worked when I directly moved the default.master, feature.xml as well as elements.xml files into the parent folder “DemoCompanyMasterPage” rather then the “MasterPages” folder. But i can’t figure out any logical explanation of my issue.


  5. Greg Galipeau
    May 21, 2008 at 2:39 pm

    That actually makes perfect sense. Maybe my directions were a little unclear (actually, I just relooked at them and one of the sentences is a little confusing, I will fix it). The feature.xml file has to be directly under the feature folder (in this case “DemoCompanyMasterPage”). That file has references to all the other files. So, the way I built it in the example says to look for the elements.xml in the same folder and look for the master page in the MasterPages folder.
    Glad to hear you got it working,

  6. Luca Giornetti
    May 22, 2008 at 1:56 pm

    Hi Greg,

    I followed your steps and the solution deployed successfully but when i tried to create a new site collection, in the “template selection” section there’s not any Demo Company Tab as you show in the selectatemplate.jpg image.
    Any ideas?

    thank you in advice,


  7. Greg Galipeau
    May 22, 2008 at 2:03 pm

    The actual tab shows up because of the webtemp*.xml file. There is a node in that file called DisplayCategory. Make sure that is set correctly and the tab should show. If the tab still isn’t showing, that means SharePoint cannot read your webtemp*.xml file. This can be for multiple reasons – the most common is naming conventions. It has to be called webtemp and then something specific and then .xml. An example is webtempdemo.xml. And you have to make sure this file is getting copied to the 12/Template/XML folder on the server (check this directly on the server after you deploy). If those things are set correctly, then the only other issue could be that you have mistype within the webtemp*.xml file. So, check that file very carefully.
    Other than that, make sure you do an app pool recycle. These are very important. WSPbuilder will do one with every deploy, I just wanted to mention this if you are using some other technique.

  8. Luca Giornetti
    May 22, 2008 at 3:09 pm

    Hi Greg,
    thank you for your answer.
    I checked webtemp*.xml but the template selection tab is’nt still displayed.
    I copied the Onet file from the …\site templates\sts\xml folder and I modified it according to you, but I have a question: do I have to erase all the content in the file and write only xml tags you suggested? Because I modified only Site features and Configuration ID =”0″ parts but I left intact the rest of the file I copied from STS\XML folder.



  9. Greg Galipeau
    May 22, 2008 at 3:14 pm

    You don’t “have” to remove the other configurations like I suggested. It just cleans things up a little bit to make the file more readable. If you leave them there, it shouldn’t break anything.
    I don’t know why your site def is not showing up under the tab. The big issue is that these xml files don’t have validation. Thus, one little mistype can break the whole thing. In fact, my company is working on a project right now to help with this (it will be internal to my company). But, if it is successful, we will put it on open source.
    This fact won’t help you right now, but it just goes to show that it is really hard to deal with these xml files without proper validation and developers constently have issues.
    My only suggestion is to try the directions out “exactly” one time through from the begining. I had some other people test out these directions that didn’t know SharePoint and it worked for them.
    But, it is truely understandable that one little mistake can mess up the whole thing.
    Sorry I can’t help more. If you go through the directions again and have the issue, maybe we can set something up where you can send me your solution and I can take a look at it.

  10. Asjad Lakhani
    May 26, 2008 at 11:36 am

    Hi Greg,
    Really nice article.
    But please let me know what shall I do to create .WSP for the site which contains variations.
    I am not able to create .WSP for my site which has variations.

  11. May 26, 2008 at 11:43 am

    Hi Greg,

    As mentioned earlier, I followed the steps as defined above and successfully created a custom site collection. Now I want to use that site collection to create subsites based on my clients. But whenever i tried creating subsites using the my custom template the sub site creates successfully but on accessing it gives a “HTTP 404 : the resource not found error”. When I open the site in the Sharepoint designer, i found that the “DemoCompany.master” file is not present in the master page gallery. I checked it thoroughly, for all probabilities, but still the issue persists. Any ideas ??

    Thanks again,

  12. Greg Galipeau
    May 26, 2008 at 11:49 am

    Hi Asjad,
    What exactly are you trying to do with the variations? Are you adding your site definitions to other folders other than the 1033? Are you not seeing them show up in your list of variations. If you are not seeing them in your lists of variations, research this property “FilterCategories”. It is one of the properties in the configuration xml of the webtemp*.xml. Unfortunately a subject on localization and variations is a whole other blog post, so I can’t get too detailed on it in a comment. Hopefully this gets you on your way.

  13. Greg Galipeau
    May 26, 2008 at 11:57 am

    Hi Sabah,
    Where are you deploying your DemoCompany.master? To the site or the site collection? What master page gallery are you not seeing it in?
    This might just be a reference/deployment issue. You might be deploying it to one place and referencing another. Try putting the reference to the master page in the “WebFeatures” (of course, change the scope of the feature if you do this) or keep it in the “SiteFeatures” and change your reference in your onet.xml to go to the master page of the site collection.

    p.s. – this will be covered more in my next blog that talks about publishing sites. I am going to show how to create a top level site collection that will automatically create the subsites. I was just looking at the code for it and it seems I place my master page feature reference in the WebFeatures for all my subsites. I just have to find the time to write it up 🙂

  14. May 26, 2008 at 2:14 pm

    I am using my custom site collection(DemoCompany)created by using above defined steps to create a subsite. The top level site for which i have to create a sub site is also created by the same process, though there solution (.sln file) is different. But when i try accessing the sub site, the particular master page is not present in its master gallery. I also enable all the options of publishing too with no luck.

    May be i have to wait for your next post. 😀


  15. Greg Galipeau
    May 26, 2008 at 2:43 pm

    Maybe I wasn’t clear on my last comment. It has to do with the path to the master page and the scope you deploy to. If your master gallery on the site doesn’t have the master page, it is because we deployed to scope “Site” and “SiteFeatures” in this example. If you want to have the master page show up for a gallery in a site, you need to deploy to scope “Web” and “WebFeatures”.
    The reason is, when we deploy to scope “Site” and “SiteFeatures” we are telling SharePoint to put the master page in the masterpage gallery for the Site Collection.
    You are probably looking at your masterpage gallery for a single site (thus, you would have to deploy to the “Web” and “WebFeatures” for it to show there).

    There is another option and that is changing the path to the masterpage in the onet.xml file to point to the site collection.

    Anyways, your issue all has to do with what scope you are deploying to for your particular situation.

    As for enabling publishing options (it is really difficult). So, good luck with that and hopefully my next post won’t be too far out (but I don’t think I will write it for a couple of weeks). My only suggestion for you on this is to see how SharePoint does it for their publishing sites and try to copy there techniques.

  16. Pete Naschke
    May 27, 2008 at 1:39 pm


    Is there any way to get a Visual Studio 2005 VB.NET program to “see” and interact with SharePoint folders?

    My program works with standard Intranet and hard disk based folders, but crashes immediately when it encounters SharePoint folders.

    I have been stuck on this issue for more than 3 weeks now…I can find no solution.

    Please help if you can.


    Pete Naschke

  17. Greg Galipeau
    May 27, 2008 at 3:18 pm

    Hello Pete,
    Have you tried using the SharePoint WebServices? I would suggest looking into them to interact with anything in SharePoint from an environment outside of SharePoint.

  18. May 30, 2008 at 2:15 pm

    I tried exactly as written, but it not worked for me, only after the following modifications:
    1) Modify in feature.xml to Scope=”Web”
    2) Put the element in ONET.XML from to
    And voila!

    (In your example, the master page feature got registered for me as passive Site Collection Feature, and the default.aspx page couldn’t find it in _catalogs/masterpage, because it was not there.)

    Anyway, thanks, very great article, helped a lot!!!

  19. May 30, 2008 at 2:16 pm

    2) Put the element in ONET.XML from <SiteFeatures /> to <WebFeatures />

  20. Greg Galipeau
    May 30, 2008 at 2:36 pm

    Thanks mtringel. I am going to update the article to show both ways actually. I was trying to show how to put the masterpage at the sitecollection level so all the sites could reuse it. However, I only showed how to make the top level site reference it. I should show how to make other sites (i.e.: lower level sites reference that same masterpage setting at the sitecollection level).
    However, your approach is good too (i.e.: put the master page at each webs masterpage catelog).
    I definetely need to make that part more clear in the directions.
    Thanks for the feedback.

  21. June 2, 2008 at 11:01 am

    “However, I only showed how to make the top level site reference it.”
    Sooo, that’s why! 🙂

  22. June 2, 2008 at 1:12 pm

    I try to remove the master page feature from your example and add a site column feature instead, but I always receive “Failed to instantiate file “default.master” from module “DefaultMasterPage”: Source path “default.master” not found.” exception when initializing the new site. If I remove all features, it works :(.
    (I removed the DefaultMasterUrl, CustomMasterUrl attributes from the Configuration element of course.)
    Any idea, please?

  23. Greg Galipeau
    June 2, 2008 at 3:48 pm

    It will be hard for me to know exactly what is going on without being in front of the server. However, here are a couple things to check:
    1. You didn’t reuse the guid of the feature from the master page with your new features (i.e: you create a new guid).
    2. You did a retract/uninstall and an install/deploy after creating new features. The upgrade path won’t help with new features.
    3. Check the actual log files out for the “real” errors. SharePoint errors can be deceiving sometimes (even the log errors can be hard to read).

    Anyways, I would start with the above. I wish I could help more, but I would need to be at your server to do that.

  24. Saurabh
    June 12, 2008 at 10:08 am

    Hi Greg

    What if we create a Collaboration Portal……well m trying to create Collaboration Portal and also want to add SiteDirectory Subsite. when ever i create a new SiteCollection of my own SiteTemplate it gives an error of
    “Failed to instantiate file “default.master” from module “DefaultMasterPage”: Source path “default.master” not found”…….
    Whats that have u ever face this error…..??


  25. Greg Galipeau
    June 12, 2008 at 12:50 pm

    Basically, it is trying to find a masterpage called default.master in your master page gallery. It is either looking at the site collection level or the site level (it can be different based on the way you customize it). Basically, your default.aspx has the master page set to something like this ~masterur/default.master. Then, in the onet.xml file of your site definition, there is a configuraiton node. On that node there are two properties “CustomMasterUrl” and “MasterUrl” (they are not there by default, you have to add them). If your default.aspx says ~masterurl/default.master it actually uses the MasterUrl property from the onet.xml. If your default.aspx says ~masterurl/custom.master, it actually uses the CustomMasterUrl from the onet.xml. If neither are set it always tries to look for default.master.

    This subject is actually talked about in this blog.

    One problem that a lot of people run into with this is that their site is looking for the master page in the site gallery, when they actually deployed it to the site collection gallery. In fact, that is an issue someone pointed out in the comment of my blog (i.e.: I showed how to deploy the master page to the site collection gallery, and that only works for the root page, so people were having trouble in the steps when creating sub pages – I still have to fix that, but the comments should explain it).

    Anyways, look into your masterpage gallery on the site and make sure it is really there. Otherwise, make sure you put it there in your site definition.

  26. Saurabh
    June 12, 2008 at 1:46 pm


    The Example u have given to us…..is for Team Site only…Can we add SiteDirectory in it……??


  27. Greg Galipeau
    June 12, 2008 at 1:55 pm

    Yes, the example is for a team site. But, for your particular error about the default.master, the concept is still the same for Collaboration sites.

  28. Saurabh
    June 12, 2008 at 2:29 pm

    Hi Greg….

    I have created the Team SiteDefinition….and Publishing Portal SiteDefinition

    but could not able to create CollaborationPortal
    Can u plz give an example Creating Collaboration Portal with SiteDirectory……in that Portal???

    Thanx n Regards

  29. Greg Galipeau
    June 12, 2008 at 2:32 pm

    Sorry Saruabh,
    That is not really in context of this blog. I would suggest asking questions like this in the technet forums for SharePoint.

  30. Todd Butler
    June 12, 2008 at 7:26 pm


    Thank you for taking the time to be the almighty Sharepoint Guru and sharing your wealth of knowledge. I have a site built and it is working great. I have a local aspx file that I made one small character change too. I did a rebuild and deploy and I can see the files on my Development server. You mentioned earlier that you have to run STSADMIN command to update the files. Do you by chance know what the STSADMIN command is that I need to run? I have looked everywhere and can’t seem to find it to update my build. Help!



  31. Greg Galipeau
    June 12, 2008 at 7:33 pm

    You can do the update through wspbuilder if you want. If the solution is already deployed and you run the deploy command of wspbuilder, it will do an update for you.

    But, if you want to use stsadm, you have to open a command prompt and go to it – it is at 12/Bin. When you open it in a command line you can run stsadm.exe -help. It will list out all the available commands. I think the update one is updatesolution. At that point you can type stsadm.exe -help updatesolution and it should tell you exactly what parameters it takes in.

    But, like I said, WSPBuilder makes the process a lot easier for you so you don’t have to run these stsadm command lines.

  32. Todd Butler
    June 12, 2008 at 7:44 pm


    Thanks for the fast response. I opened up a file called TSCSiteCreation.aspx and changed the wording in an error message and added a change in an Expression Validation. After I made the changes, I right clicked on the SiteCreation project and clicked on WSP Builder and Build WSP and then went back and did the same thing but Deploy this time. However, if I go to the Sharepoint site to see if my code is updated, it still shows the old code. I can see the updated files on my Development box, but they haven’t gone over to my Apps box. So I guess to be clear here, I am assuming I have to move them from my Development box to my live Apps Box. Is that correct? If so, is the only way to do that to use a SYSADMIN command or can I copy them in Explorer view and past them on the Apps box? Sorry to be a nuisance. Thanks.

  33. Greg Galipeau
    June 12, 2008 at 7:50 pm

    Ah, I understand now. Yes, WSPBuilder will only work on the box you run it on.
    So, if you want to install the .wsp on another box, you will have to deal with stsadm commands (or, you could just install Visual Studio and WSPBuilder on the prod box – but most people don’t like to do that).
    So, the wspbuilder tool on your development box will create a .wsp file at the root folder. Take that file over to your production box and run the stsadm command for addsolution (not sure the exact name for it, but use the stsadm help to figure it out). After, the solution is added to production server it will show up in your Central Administraiton – Operations – Solution Management link. From there you can deploy the solution to your web applications. Also, if you don’t want to deploy through Central Administration – you can do that through stsadm also if you like command line scripts better.

  34. Todd Butler
    June 12, 2008 at 8:10 pm

    Sorry again for bugging you..I promise I am not the idiot I sound like. When I look at Visual Studio I have have 1 solution with two projects underneath it. Should I rebuild the solution and redeploy it or just the project that I made the changes too under the solution?

  35. Greg Galipeau
    June 12, 2008 at 8:14 pm

    It kind of depends. Is one of the solutions a WSPBuilder solution? Does that WSPBuilder solution hold dlls for the GAC or BIN? If so, you have to make sure to build the project to place the dll in the correct folder in the WSPBuilder solution so when you install the .wsp it will install the correct dlls to the GAC or BIN.
    It is really a situational kind of question. I would have to understand the structure of the two projects to give you a really good answer.

  36. Todd Butler
    June 12, 2008 at 8:18 pm

    Would it be better if I could send you a screenshot? I would gladly pay you for your assistance.

  37. Greg Galipeau
    June 12, 2008 at 8:21 pm

    Send me a screenshot at . You don’t have to pay for my assitance. Hopefully it will be something I can help with quickly.

  38. Kjell
    June 17, 2008 at 1:49 pm

    Is there anyone encountered following??

    “Install and deploying DemoProject.wsp
    Unable to deploy solution
    Inner exception(1): Name cannot begin with the ‘%’ character, hexadecimal value 0x25. Line 1, position 2.”

    On deployment…

    I’m kind of stucked here…

    The solution build without any problems, but on deployment I’m getting problems…

    Any ideas?

    Kjell Brandes

  39. Greg Galipeau
    June 17, 2008 at 2:01 pm

    You have used a naming convention somewhere that SharePoint does not like. Look for special characters somewhere (they usually cause these issues).

  40. Sharepoint NOOB
    June 23, 2008 at 12:48 pm


    Do we need to create a seperate solution for lower level sites to reference that same masterpage setting at the sitecollection level?


  41. Greg Galipeau
    June 23, 2008 at 12:52 pm

    You do not need a seperate solution, nor will you need a seperate project. However, that is not to say you might want it based on some business requirement, but I usually do this all in the same solution and project.

    However, you might want a seperate site definition for your lower level sites to reference the same masterpage. Once again, this is based on requirements. If your lower level sites have the same requirements as your top level site, they can use the same site definition. However, if they have different requirements (but can still utilize the same master page), then they need to be a different site definition that inherits from the same masterpage.

  42. Sharepoint NOOB
    June 26, 2008 at 10:33 am

    Hi Greg,

    Thanks for the comments. My site is now working fine. The only problem now is when im deploying the solution package to the other machine (VMWare) i get an error “HTTP 404 : the resource not found error”. What could be causing this error?

    Thanks for your help!

  43. Greg Galipeau
    June 26, 2008 at 12:22 pm

    Hey NOOB,
    I am not sure if the solution is causing that error. But, it could be because the solution is not getting deployed correctly for some reason. I do these on Virtual environments all the time, so I don’t think the issue is the fact it is on a virual environment.
    Anyways, this could be a lot of things, so I don’t know if I can help. It could range anywhere from setup of the box to an issue in the specific way it is getting deployed. There are a lot of possibilies with that particular error.
    I would try to narrow down the actual error a little bit more.
    Sorry I couldn’t help,

  44. Sharepoint NOOB
    July 24, 2008 at 10:01 am

    Hi Greg,

    Its me once again ^_^

    My question is not related to the topic but i hope you can still help.

    I created a publishing site and with it our some page layouts with default web parts. I placed the default web parts on the page layouts aspx page. The problem I am encountering is when I am deploying the page layouts containing the default web parts using features, the web parts are rendered twice on the page upon creation of the site. And when you create new pages based on these page layouts, they will get an increasing number of instances of each default web part.

    What could be causing these problem? I hope you could help.


  45. Miljan
    July 24, 2008 at 1:16 pm

    Hi, I tried the workaround with ~SiteCollection/_catalogs in MasterUrl and CustomMasterUrl to enable sub-webs to work, but it does not, when I provision the site the default.aspx still points to WSS default.master, like the configuration in onet.xml was discarded as invalid. When I make the feature to be Web scoped and don’t use ~SiteCollection then it works (but then it provisions my master page for each subweb).
    Is the instruction ok, or am I missing something.

  46. Anurag
    August 10, 2008 at 5:01 pm

    Hi Greg,

    I am trying to create new .aspx page under the sharepoint site. I am followed the given steps.

    1.Create Web Application in VS2008 and new page(called Demo.aspx) under it.
    2.In code behind implement the OnPreInit() method.
    3. In aspx page place the and deployed in LAYOUTS/Test/Demo.aspx.
    4.Signed the assembly and deployed in GAC.

    I think I am following the step to use custom aspx page under sharepoint environment.

    Still It thow error..(Content Controls are allowed only in content page that reference the master page)….

    You help will be highly appriciated….



  47. Kai Loon
    September 15, 2008 at 11:43 am

    Hi Greg Galipeau, instead of registering feature in onet.xml file, wouldn’t it be better to use feature stapling instead, for flexibility and for extensibility?

  48. Greg Galipeau
    September 15, 2008 at 12:06 pm

    Hello Kai,
    Yes, feature stapling is definetly an option. It is a more useful option when you need to change a feature on an existing site definition. But, it is great because you can turn on or off functionality after a site has been created.
    This blog post is trying to show people how to build a Visual Studio Solution, I didn’t want to go too much into other aspects like feature stapling.
    Also, I usually still do this architecture on my sites anyways because when you build a solution from the ground up you can always upgrade your own solution. Thus, you don’t gain too much advantages from feature stapling. For example: If I wanted to change the master page hear, I could just update my master page, I don’t need to turn off the old feature and turn on a new one. But, as you can see from my last statement, there could be advantages in feature stapling, because you can keep around your old feature and then just turn on your new one.
    So, it is all decision based. I usually don’t use feature stapling for master pages (but I can see some small advantages to it based on situations), but I use it a lot for other types of features. Plus, I really take advantage of it to modify the out of the box site definitions in SharePoint. Also, it was a little too advanced to mention in this blog or else the blog would have got really long trying to explain how to build a solution and the feature stapling concepts.

  49. Bala
    September 30, 2008 at 6:22 pm

    Hello Greg, I created a WSPBuilder project using the sample project. I followed exact steps except these two: 1. I put the DemoCompany.master file directly under DemoCompanyMasterPage folder. I did not create ‘MasterPages’ folder.
    In the Elements.xml, I still gave Path=’MasterPages’ in the Module tag. Is that correct? The Site Collection was created successfully. But when I navigat to the site I got 404 NOT FOUND error. Do you have any clue for this error?


  50. Bala
    September 30, 2008 at 6:32 pm

    This is in additon to Comments 51. Also, I checked the master page feature in the Site Collection. It was not activated by default. Any suggesstions?

    If I create a feature for content type and put that feature ID in the SiteFeatures tag of ONET.xml will that feature be activaed by default when I deply the project. Do I have to take any special step for activating feature?


  51. Greg Galipeau
    September 30, 2008 at 11:49 pm

    Hi Bala,
    I have never tried putting master page in and not putting it in another folder. Thus, I cannot tell you if that is your exact issue. But, i would assume it is. So, my suggestion is to just put it in the folder like the steps.
    As for the feature not getting activated, that has to do with the tag in the onet. In the steps I talk about adding the guid to your feature in the tag. If your feature is scoped for the site and you put it in the tag like I mention in the steps, then it will get activated when the site is created.

  52. Chikku
    December 8, 2008 at 3:55 pm

    Hi Bala,

    I have the same issue like you posted
    when I navigat to the site I got 404 NOT FOUND error. Do you have any clue for this error? Di d you resolve it by any chance. PLease let me know. thanks

  53. Chikku
    December 8, 2008 at 4:04 pm

    Hi Greg,

    Thank you very much for the detailed post.

    After the site is created using the site definition when I navigat to the site I got 404 NOT FOUND error

    Can you please confirm the following

    Scope: –
    MasterUrl=”~SiteCollection/_catalogs/masterpage/DemoCompany.master” >

    Where do i place the DemoCompany.master under DemoCompanyMasterPage?

    Under ElementManifest.xml -> what should be Path attribute? Is this correct ? Path=”MasterPages”

  54. Ed
    March 13, 2009 at 12:17 pm

    For the people that got a 404. Look good at the xml files, i got a 404 after with a wrong xml in point 6. The pictures are not full visible so open the image in a new window to see all of the picture.

    Point 6c needs to be:

    CustomMasterUrl=”_catalogs/masterpage DemoCompany.master”

  55. Ed
    March 13, 2009 at 12:19 pm

    And thanks to Greg Galipeau, this is a great article! The only thing you can do to make it better is to give us a download of the project.. 🙂

  56. Yash Dogra
    April 2, 2009 at 6:20 am

    Hello Grg..
    After following all the steps u described i am still getting this error :
    Failed to instantiate file “default.master” from module “DefaultMasterPage”: Source path “default.master” not found

    Please help me..

  57. mahmoud
    May 26, 2009 at 8:44 am

    you look like a sharepoint expert, i would like you to help me with my final year project….. am doing it on sharepoint, i got the solution from my friend working at a company to use it as an example and learn from it, but i can understand nothing, how can u help !? do u have a tutorials or ebooks

  58. sourab
    June 3, 2009 at 5:17 am

    I m a starter in sharepoint development.
    I have the requirement of reading contents of an excel file in the Item Added event of Event receiver . Can any one pls tell me how to accomplish this.

  59. Gary Fuller
    June 9, 2009 at 6:33 pm

    Hi Greg,
    I’ve been unsuccessful in completing the Demo Project. On each WSP build I get the error:

    Creating the WSP file
    Invalid path: \\Servername\C$\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS\CUSTOM\DemoProject\DemoProject

    This is the exact path to the DemoProject files.

    I guess it’s obvious I’m developing on my local machine (XP Professional with Visual Studio (2008) trying to use WSPBuilder on the same machine. I create the Demo Project on the (remote) development server (containing WSS 3.0) successfully, but everything falls apart when I attempt to build the WSP.

    I saw the previous scope issues, but I don’t think this is related (I’m an SP newbie, so I could easily be wrong!)

    Can you please suggest a possible solution to my dilemma? I really like the WSPBuilder, and would like to continue using it. I think it’s a great tool.

    I did just find out there’s a copy of the older VS 2005 on the remote dev server, but I really don’t want to use that unless I have to.

    Best Regards,
    Gary Fuller

    • Greg Galipeau
      June 9, 2009 at 7:45 pm

      Hi Gary,
      You mentioned you are developing on your local machine. Unfortuantely, in SharePoint development you have to develop on a SharePoint server. I have heard some people mentioning that they can develop locally with some creative techniques (but it never usually works out completely). So, your issue probably has to do with this. I recommend installing Windows Server and a SharePoint environment on a virtual machine. I use Microsoft VPC to do all my development.

      • Gary Fuller
        June 10, 2009 at 11:19 am

        Thanks for the quick reply. This kind of sums it up for me. This was my recommendation here at work, but I got the alternative. Now I have some ammunition to plead my case. Thank you!

  60. Gary Fuller
    June 11, 2009 at 12:57 pm

    Hi Greg,

    Your reply to my post worked! The boss has given me permission to build a proper SP dev environment on my workstation.

    I would love to hear details of building a good dev machine (yours or any best practices). I’ve got Ed Robillard’s and Justine Devine’s setup ideas printed out.

    I have a small footprint HP box with one hard drive (and not much room inside), containing 104 GB, 64 GB free, running Windows XP Professional, Intel Core 2 Duo. 1.96 GB RAM (I know I’ll need 1-2 GB more).

    I (or someone here) will be installing VM Workstation, possibly an external hard drive, Windows Server 2003, with WSS 3.0.

    I already have Visual Studio Professional 2008, SharePoint Designer 2007, WSPBuilder and a couple other goodies.

    A big question is where should the VMware and server stuff be installed, on the local c: drive, a second internal drive or on an external hard drive? I know Ed Robillard recommends putting it on an external drive (but for a laptop setup). I don’t think I have room for a second internal drive, but not sure. I also need backup consideration.

    Sorry if this post is a bit off-topic.

    All comments and suggestions welcome,

    Gary Fuller

  61. Thatikonda
    June 22, 2009 at 9:29 pm

    My solution compiles but it gives an error when I try to deploy.
    Install and deploying DemoProject.wsp
    Unable to deploy solution
    Inner exception(1): Name cannot begin with the ‘%’ character, hexadecimal value 0x25. Line 1, position 2.

    I followed the exact steps but not able to figure out in the XML file, the character that is causing this error. Can I upload/email the XML files?

  62. Thatikonda
    June 22, 2009 at 10:12 pm

    Greg Galipeau,

    Could we have your code for download? So I can compare my xml files with yours and find the character that is causing the error. I am right now got stuck.


  63. Suz
    September 22, 2009 at 7:55 am

    Thanks for the blog! worked like a charm 🙂

  64. Jeff
    November 24, 2009 at 7:43 pm

    Awesome!!! thanks for the blog…. Can you also show us how to take advantage of properties, so that they can be set from the web part itself. I have been trying to do it for a day now with no luck.


  65. MOSS_Lover
    November 30, 2009 at 2:50 pm

    Hello Greg,

    I followed the steps in the above article,but I get the below error:

    Cannot complete this action.
    Please try again. at Microsoft.SharePoint.Library.SPRequestInternalClass.ApplyWebTemplate(String bstrUrl, String& bstrWebTemplate, Int32& plWebTemplateId) at Microsoft.SharePoint.Library.SPRequest.ApplyWebTemplate(String bstrUrl, String& bstrWebTemplate, Int32& plWebTemplateId)

    Any ideas?

    Thanks in advance.

  66. March 12, 2010 at 5:28 pm

    Thanks dear for such a wonderful post.

  1. May 19, 2008 at 1:15 am
  2. June 28, 2008 at 11:25 pm
  3. January 18, 2009 at 4:22 pm
  4. July 20, 2009 at 2:10 pm

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: