Understanding SharePoint Solutions as Deployment Units
Although console applications are a great way to play around with the SharePoint API, you will not be using them to deploy new functionality to SharePoint. The recommended way to deploy functionality is through SharePoint solutions, which are cab files with a .wsp extension, which stands for Windows SharePoint Solution Packages. The most important file in the WSP file is the manifest.xml. This file contains information about the other files in the solution. In SharePoint 2010 you can create two types of solutions: farm solutions and sandboxed solutions.
Understanding Farm Solutions
A farm solution is a SharePoint solution that is deployed to the Solution Store in Central Administration of your SharePoint farm. People who have worked with SharePoint 2007 will find this familiar.
Try It Yourself: Write a Farm Solution
1. Open Visual Studio and create a new Empty SharePoint Project named HelloWorldFarm as shown in Figure 3.2.
Figure 3.2. New Project screen
2. Select Deploy as a Farm Solution as the trust level for the solution, as shown in Figure 3.3, and click Finish.
Figure 3.3. Creating a farm solution
3. Right-click the project and select Add, New Item.
4. Select Visual Web Part, name it HelloWorldVWP, and click Add, as shown in Figure 3.4. A visual web part is simply a web part with a user control that makes it easier to build the user interface of your web part by enabling you to drag and drop controls on the user control.
Figure 3.4. Add New Item screen
5. A new web part is added to your project. The project structure should look similar to Figure 3.5.
Figure 3.5. Project structure for HelloWorldFarm project
Hour 5, “Working with Web Parts and Web Pages,” discusses in detail most of these files. You can see in your solution something called Feature1 under Features. You learn more about features in the “Introducing SharePoint Features” section later in this hour. For now just understand that features enable you to toggle a functionality On or Off in SharePoint and that most functionality is deployed in SharePoint as SharePoint features.
6. Double-click Feature1. You see the feature designer as shown in Figure 3.6. Change the title to HelloWorldVWP.
Figure 3.6. Visual Studio 2010 feature designer
7. Select Feature1 in the Solution Explorer and rename it to HelloWorldVWP.
8. Open HelloWorldVWPUserControl.ascx and add the following at the end:
<asp:Label runat="server" ID="lblHelloWorld"
Text="Hello World - My First Visual Webpart" />
9. Now build the solution.
10. Once the build has succeeded deploy the solution by right-clicking on the project and then clicking Deploy. If you look at the output window you can see a lot of information on what is happening during deployment. Remember in Hour 1 we looked at the deployment configurations in the Visual Studio. You will find that the output in the output window corresponds to the steps of the default deployment configuration.
Active Deployment Configuration: Default
Run Pre-Deployment Command:
Skipping deployment step because a pre-deployment command is not specified.
Recycle IIS Application Pool:
Skipping application pool recycle
because no matching package on the server was found.
Retract Solution:
Skipping package retraction because no matching package on the server was found.
Add Solution:
Adding solution 'HelloWorldFarm.wsp'...
Deploying solution 'HelloWorldFarm.wsp'...
Activate Features:
Activating feature 'HellowWorldVWP' ...
Run Post-Deployment Command:
Skipping deployment step because a post-deployment command is not specified.
========== Build: 1 succeeded or up-to-date, 0 failed, 0 skipped ==========
========== Deploy: 1 succeeded, 0 failed, 0 skipped ==========
You have now built and deployed your first SharePoint solution. In the preceding output you can see that your HelloWorldVWP feature was activated while deploying. This means that the web part is now available for adding to the pages in the site.
In the preceding scenario we deployed the solution directly through Visual Studio. But we could have just as easily packaged the solution by right-clicking on the project and clicking on Package. We could then deploy the solution using the following stsadm commands.
Stsadm -o addsolution -filename HelloWorldFarm.wsp
Stsadm -o deploysolution -name HelloWorldFarm.wsp -url http://splearn –allowgacdeployment
Stsadm is a command line tool that you will be coming across frequently. This tool is present in the <14 Hive>Bin folder. You need to include this folder in the Path environment variable to be able to use this command as indicated here.
1. Go to Start, All Programs, Control Panel, System.
2. On the Advanced tab, click the Environment Variables button.
3. Select the variable path and click the Edit button.
4. Add the following to the end of the Variable value field: Change the drive if SharePoint is not installed in c: drive.
;C:Program FilesCommon FilesMicrosoft SharedWeb Server Extensions14BIN
5. Click OK.
The preceding deployment could have been done through PowerShell commands in place of the stsadm commands. Even though the stsadm commands still work in SharePoint 2010 it is recommended to use PowerShell in SharePoint 2010. PowerShell is discussed in more detail in Hour 16, “Understanding SharePoint 2010 Central Administration.”
You can see the contents of the .wsp file generated when you packaged the solution. To view the contents of the .wsp, perform the following steps:
1. Go to the BinDebug folder of your project. Rename HelloWorldFarm.wsp to HelloWorldFarm.wsp.cab.
2. Open the .cab file and you should see the contents of the solution, as shown in Figure 3.7.
3. Select the Details view and notice the path column.
Figure 3.7. Contents of the WSP file
4. Open the manifest.xml file. You can see it contains all the information about the contents of the solution, as shown in Figure 3.8.
Figure 3.8. Sample manifest.xml
5. You can also find the SafeControl tag for the web.config file, which is required to allow the web part to run on your site.
6. Now browse to the <14 Hive>TemplateFeatures folder and you should see a directory named HelloWorldFarm_HelloWorldVWP. Notice that this maps to the path column in the WSP file. Also go to the <14 Hive>TemplateCONTROLTEMPLATES folder. You can see your HelloWorldFarm folder in there. Notice again that this maps to the path column in your WSP file.
Browse to your SharePoint 2010 Central Administration site. Navigate to System Setting and under Farm Management click Manage Farm Solutions. You should see your solution along with other solutions, as shown in Figure 3.9.
Figure 3.9. Solution Store in the SharePoint 2010 Central Administration
Finally you can see your web part in action. Follow these steps:
1. Browse to your SharePoint site (in my case it is http://splearn).
2. Select the Page tab on the ribbon and click Edit. Two new tabs—FormatText and Insert—appear.
3. Go to the Insert tab and click web part. The list of web parts appears below the tab.
4. Select Custom under Categories on the left side. You see your HelloWorldVWP web part, as shown in Figure 3.10.
Figure 3.10. Insert web part screen
5. Click Add and the web part is added at the top, as displayed in Figure 3.11.
Figure 3.11. HelloWorldVWP web part added to top zone
One of the most important factors that differentiate a farm solution from a sandboxed solution is that the farm solution is always deployed to your Central Administration Solution Store. Farm solutions can run any type of code without any restrictions. This can be at times counterproductive as there is an increased chance that some code can bring your entire farm down.
Understanding Sandboxed Solutions
Sandboxed solutions are newly introduced in SharePoint 2010. Sandboxed solutions are not deployed to your Central Administration Solution Store like farm solutions. They are deployed to the solutions gallery of your site collection. Also they run with a lot of restrictions compared to farm solutions. In addition sandboxed solutions do not run under the worker process like farm solutions but in a special process known as the Sandboxed Code Service. You can see this service by browsing to SharePoint 2010 Central Administration, System Settings, Manage Services on Server. There you can find the Microsoft SharePoint Foundation Sandboxed Code Service as shown in Figure 3.12. Make sure that this is started.
Figure 3.12. The Manage Service On Server screen in SharePoint 2010 Central Administration
Try It Yourself: Write a Sandboxed Solution
1. Create a new Empty SharePoint Project and name it HelloWorldSandBoxed.
2. Select Deploy as a Sandboxed Solution for the trust level and click Finish.
3. Right-click the project and select Add, New Item.
4. Select the Web Part template, name it HelloWorldWP, and click Add. Note that you cannot select the Visual Web Part template as it requires you to deploy the user control to the CONTROLTEMPLATES folder and one of the restrictions of sandboxed solutions is that they cannot deploy files to the file system.
5. Select the project and look at the properties window shown in Figure 3.13. You can see the Sandboxed Solution property set to True, which indicates this is a sandboxed solution.
Figure 3.13. Properties window
6. Open the HelloWorldWP.cs and add the following to the CreateChildControls method:
Label lbl = new Label()
{ Text = "Hello World - My first sandboxed solution in SharePoint 2010" };
this.Controls.Add(lbl);
7. Rename the feature title and feature node to HelloWorldWP.
8. Right-click the project and click Deploy Solution. You should see the following in the output window of your Visual Studio. You can see that the application pool was not restarted as sandboxed solutions do not run in the worker process.
Active Deployment Configuration: Default
Run Pre-Deployment Command:
Skipping deployment step because a pre-deployment command is not specified.
Recycle IIS Application Pool:
Skipping application pool recycle
because a sandboxed solution is being deployed.
Retract Solution:
Skipping package retraction because no matching
package on the server was found.
Add Solution:
Adding solution 'HelloWorldSandBoxed.wsp'...
Deploying solution 'HelloWorldSandBoxed.wsp'...
Activate Features:
Activating feature 'HelloWorldWP' ...
Run Post-Deployment Command:
Skipping deployment step because a post-deployment command is not specified.
========== Build: 1 succeeded or up-to-date, 0 failed, 0 skipped ==========
========== Deploy: 1 succeeded, 0 failed, 0 skipped ==========
9. Now go to the Solutions gallery of your SharePoint site by going to Site Actions, Site Settings, Solutions under Galleries. In Figure 3.20 you can see that the status is activated. This is as per our deployment configuration in Visual Studio.
Figure 3.14. Site Collection Solution Gallery
10. Now go ahead and add the web part to your site (see Figure 3.15).
Figure 3.15. HelloWorldWP web part
Though we created and deployed simple web parts without much functionality, the steps to create and deploy web parts will be applicable to most of the other things including more complex web parts and other project types in SharePoint. However you need to know when you should create sandboxed solutions and when you should create farm solutions. Sandboxed solutions are the recommended way to go in SharePoint 2010 as they can be monitored more easily and due to restrictions imposed on them cannot cause issues that rogue code in a farm solution might. Sandboxed solutions are an important topic, and Hour 21 is devoted to them. You should go with a farm solution only if you cannot achieve the functionality through a sandboxed solution due to the restrictions imposed on them. Even then various workarounds are available for overcoming the sandboxed solutions’ restrictions as you see later.
Understanding Sandboxed Solutions Restrictions
It is important to know the restrictions imposed on sandboxed solutions if you are to be able to work with them. Following are the SharePoint project items that will not work with a sandboxed solution:
• Visual web parts
• Application pages
• Custom action group
• HideCustomAction element
• Content type binding
• Web application-scoped features
• Farm-scoped features
• Workflows with code
Don’t worry if you do not understand all the items listed here. You will come across all these items in subsequent hours. In addition to the previous items, you can access only the following from the SharePoint object model in a sandboxed solution:
• All of Microsoft.SharePoint, except
• SPSite constructor
• SPSecurity
• SPWorkItem and SPWorkItemCollection
• SPAlertCollection.Add
• SPAlertTemplateCollection.Add
• SPUserSolution and SPUserSolutionCollection
• SPTransformUtilities
• Microsoft.SharePoint.Navigation
• Microsoft.SharePoint.Utilities, except
• SPUtility.SendEmail
• SPUtility.GetNTFullNameandEmailFromLogin
• Microsoft.SharePoint.Workflow
• Microsoft.SharePoint.WebPartPages, except
• SPWebPartManager
• SPWebPartConnection
• WebPartZone
• ToolPane
• ToolPart
In addition to the preceding restrictions the administrator can apply further restrictions to the API. The Microsoft.SharePoint.Administration.SPWebService class provides a collection in the form of the API block list that enables an administrator to specify additional types in the API to block.