Redeploying Customizations and Solutions in SharePoint Foundation 2010 and SharePoint Server 2010
Summary: Learn how to redeploy customizations and custom solutions that you created for Windows SharePoint Services 3.0 and Microsoft Office SharePoint Server 2007 in Microsoft SharePoint Server 2010 and Microsoft SharePoint Foundation 2010.
Applies to: Business Connectivity Services | Office 2010 | Open XML | SharePoint Designer 2010 | SharePoint Foundation 2010 | SharePoint Online | SharePoint Server 2010 | Visual Studio
Provided by: James Crowley, Microsoft Corporation | Michael Washam, Microsoft Corporation
Contents
Getting Started with the 2010 Object Model
Installing the Upgrades
Working with the 2010 Object Model
Changes to the User Interface and Visual Upgrade
Conclusion
Additional Resources
.jpg "Click to get code")
Download Microsoft SharePoint Server 2010: Deprecated Types and Methods
Getting Started with the 2010 Object Model
Microsoft SharePoint Foundation 2010 and Microsoft SharePoint Server 2010 contain object model upgrades that are designed to be compatible with existing solutions developed for Windows SharePoint Services 3.0 and Microsoft Office SharePoint Server 2007. Some namespaces, classes, and methods are now obsolete, but they are still available and will continue to work as expected in your custom code. Additionally, although the user interface (UI) has changed significantly, the Visual Upgrade feature provides a way to preserve your visual customizations until you can adopt the enhancements to the UI. You can synchronize your customizations and applications with the upgraded versions of Microsoft SharePoint Foundation 2010 and Microsoft SharePoint Server 2010 after you have redeployed them. This article provides guidance to help you avoid and overcome challenges that you might find as you redeploy, test, and debug your Windows SharePoint Services 3.0 and Office SharePoint Server 2007 code in SharePoint Foundation 2010 and Microsoft SharePoint Server 2010, respectively.
If you have created Windows SharePoint Services 3.0 or Office SharePoint Server 2007 projects with Microsoft Visual Studio 2005 Extensions for Windows SharePoint Services 3.0, version 1.1, Microsoft Visual Studio 2005 Extensions for Windows SharePoint Services 3.0, version 1.2, and Microsoft Visual Studio 2005 Extensions for Windows SharePoint Services 3.0, version 1.3, you can upgrade them by using the VSeWSS upgrade tool, which installs templates that convert existing Visual Studio extensions for Windows SharePoint Services solution packages (written in either Microsoft Visual Basic or Microsoft Visual C#) into Microsoft Visual Studio 2010 solutions (Figure 1).
Figure 1. Importing a Visual Studio extensions for Windows SharePoint Services project into Visual Studio 2010
.jpg "Import VSeWSS to Visual Studio 2010")
After you run this tool, you can view your upgraded feature in the Visual Studio 2010 Packaging Explorer (Figure 2).
Figure 2. Visual Studio 2010 Packaging Explorer
.jpg "Visual Studio 2010 Packaging Explorer")
Visual Studio 2010 provides greater flexibility in your project structure. For more information about the new packaging options that are possible in Visual Studio 2010, see Creating SharePoint Solution Packages.
After you convert your Visual Studio extensions for Windows SharePoint Services solutions into Visual Studio 2010 solutions and add your non-packaged files (for example, scripts and documents), you must deploy your new solution packages to the upgraded framework.
Installing the Upgrades
You can perform your upgrades either in place (on a server farm in which either Windows SharePoint Services 3.0 or Office SharePoint Server 2007 is already installed) or on a new server farm to which you or your administrator will attach your existing content database. In either case, your redeployments will likely work best if you use SharePoint solution package (.wsp) files instead of Windows Installer (.msi) packages. If you need to redeploy a site template, you must create a site from the template and save it as a solution package. The most important initial consideration is ensuring that the "14" folder is the target location for all your deployments, not the "12" folder; solution packages simplify this. Both SharePoint Foundation 2010 and SharePoint Server 2010 check the 12\TEMPLATE\FEATURES folder whenever they do not find a file in the corresponding "14" folder. However, they might not find custom files deployed to other folders, and it is much easier to debug your installations if all of your custom files are deployed in the "14" folder.
Using Solution Packages (.wsp Files)
If possible, deploy your custom solutions by using solution packages (.wsp files), because this is the best way to ensure that all of your custom files are deployed to the correct locations. For information about creating solution files in Windows SharePoint Services 3.0 and Office SharePoint Server 2007, see Creating a Solution. For information about deploying solution files in SharePoint Foundation 2010 and SharePoint Server 2010, see Installation and Deployment of a Farm Solution in SharePoint 2010.
Using Windows Installer Files
If you deploy your custom solutions by using Windows Installer (.msi) packages, ensure that you change them so that your custom files are deployed to their correct locations in the "14" folder, especially if you are deploying files to locations other than the TEMPLATE\FEATURES folder.
Site Template Redeployment
Site templates are deprecated. If you need to redeploy a site template to either SharePoint Foundation 2010 or SharePoint Server 2010, follow these steps:
Create a site from the site template.
Install SharePoint Foundation 2010 or SharePoint Server 2010 on your existing server farm or on a new server farm. If you install the upgrades on a new server farm, attach the content database that contains the site that you created to the new farm.
On the new installation, on the Site Settings page, select Save Site as Template. This creates a solution package with a .wsp file name extension.
Working with the 2010 Object Model
The object model contains many changes and enhancements, but your custom code will still compile and, with one potential exception, it will run as expected. If any of your customizations rely on list queries that can generate result sets in excess of 5,000 items or that scan all rows of lists that consist of more than 5,000 items, you must change the query size threshold (for instructions, see Large List Query Throttling). Otherwise, you can look closely at the changes and incorporate the object model's new elements according to your own schedule. The upgraded object model provides alternative approaches that can help to improve the design and performance of your customizations in many cases.
Obsolete Classes and Namespaces
Because the changes to the API in the upgrades are backward compatible, you should not have to make any changes to your Windows SharePoint Services 3.0 or Office SharePoint Server 2007 custom solutions before you redeploy them in either SharePoint Foundation 2010 or SharePoint Server 2010. Some classes and namespaces are obsolete, but they will continue to work as expected. If you want to start upgrading your applications so that they use the most current classes and methods, recompile your code. The compiler warnings will tell you which elements of the object model are obsolete, and which newer alternatives you should use. Figure 3 shows an example compiler warning and the corresponding mouse-over warning in Visual Studio 2010.
Figure 3. Compiler warning for deprecated constructor in Visual Studio 2010
.jpg "Compiler warning in Visual Studio 2010")
For a list of deprecated types and methods in the Microsoft SharePoint 2010 object model, see Microsoft SharePoint Server 2010: Deprecated Types and Methods.
SharePoint Server 2010 contains more than 1,500 deprecated types; most are in the Microsoft.SharePoint.Portal namespace. SharePoint Foundation 2010 contains a much smaller number of deprecated types, but it does contain several hundred deprecated methods and properties.
Windows SharePoint Services 3.0 and Office SharePoint Server 2007 types that have been deprecated in SharePoint Foundation 2010 and SharePoint Server 2010 will eventually be removed in future versions, so it is a best practice to remove them from your custom solutions.
You do not need to recompile custom code written for Windows SharePoint Services 3.0 and Office SharePoint Server 2007. This means that you can reuse your custom DLLs without recompiling them; however, they may not work as expected in some cases. For example, if you have redeployed all of your files into the "14" folder and emptied your "12" folder, any references to files under the "12" folder will not work. Just as you should rewrite your Windows Installer packages if they refer to locations in the "12" folder, you should rewrite and recompile any code that refers to files and resources that you moved to new locations. You should also replace any references in your custom code to registry keys in the "12" folder so that they refer to registry keys in the "14" folder. Evaluate your customizations in regards to your new installation and ensure that any code that relies on specific details of your old installation will continue to work after you have installed the upgrades.
All console and WinForms applications should be built as X64 and Microsoft .NET 3.5 SP1 projects.
Large List Query Throttling
SharePoint Foundation 2010 and SharePoint Server 2010 apply a default query threshold of 5,000 items. Any custom code that relies on query result sets that can exceed this maximum will not behave as expected after you upgrade. Queries on lists consisting of more than 5,000 items that include non-indexed fields in their query conditions will also fail, because those queries must scan all rows in a list. You can increase this limit (by setting the EnableThrottling property on the SPList object) or enable the object model to override it. See Handling Large Folders and Lists and Writing Efficient Code in SharePoint Server for guidance about how to handle large folders and lists efficiently.
To increase the default query threshold
On the Central Administration site, under Application Management, click Manage Web Applications.
Click General Settings, and then click Resource Throttling (Figure 4).
Figure 4. Setting the query size threshold in SharePoint Foundation 2010 and SharePoint Server 2010
.jpg "Setting the query size threshold")
New SharePoint Functionality
Notable additions to the SharePoint Foundation 2010 and SharePoint Server 2010 object model include new functionality, as follows:
The Microsoft.SharePoint.Linq namespace, which defines a LINQ to SharePoint provider that translates LINQ queries into Collaborative Application Markup Language (CAML) queries (and therefore gives you the option of replacing your list and CAML queries with LINQ).
Three client-side APIs in the Microsoft.SharePoint.Client namespace that enable you to interact with SharePoint sites through scripts that run in the browser from Microsoft .NET Framework managed code, and inside Microsoft Silverlight applications.
Both SharePoint Foundation 2010 and SharePoint Server 2010 contain many additions provided by Business Connectivity Services. These changes make it easier for you to integrate your external business data and processes with both server applications and client applications.
For information about how to use these and other new APIs, see What's New in SharePoint Foundation 2010 and What's New in SharePoint Server 2010.
The chart in Figure 5 provides a sample of the namespaces to which many types have been added.
Figure 5. New types by namespace in SharePoint Server 2010
.gif "New types by namespace")
Changes to the User Interface and Visual Upgrade
Because the UI has changed significantly in both SharePoint Foundation 2010 and SharePoint Server 2010, any customizations that rely on specific CSS classes and UI elements will work best for your users in the old user interface. When you upgrade to either SharePoint Foundation 2010 or SharePoint Server 2010, you are able to choose either the old or the upgraded user interface (Visual Upgrade). You can switch between the old user interface and Visual Upgrade at the site-collection level or at the site level:
To preserve the look and feel of existing sites, use PSConfig and PSConfigUI.
To preserve the look and feel of existing sites when you are upgrading by attaching your old content database to a new server farm, use the Windows PowerShell cmdlet Mount-SPContentDatabase.
You can also use the Web interface to set all sites in a site collection to the upgraded UI (and prevent users from using the older interface).
To set all sites in a site collection to the upgraded UI
Under Site Settings, click Site Collection Administration
Click Supported User Experiences (Figure 6).
Figure 6. Changing the UI at the site-collection level
.jpg "Changing the UI at the site-collection level")
You can also choose the previous look and feel for a specific site. Under Site Settings, click Title, click Description, and then click Appearance (Figure 7).
Figure 7. Changing the user interface at the site level
.jpg "Changing the UI at the site level")
You can also programmatically get or set the UI version (3 for the old user interface and 4 for the new interface) by using the SPWeb.UIVersion property.
Note
After setting SPWeb.UIVersion to 3 or 4, you must use the SPWeb.Update method to save the change.
The UIVersion property is also available for the SharePoint:VersionedContent control and the SharePoint:VersionedPlaceHolder control. Both controls place versioned content on the page, but the SharePoint:VersionedPlaceHolder works at render time, after the page is finished loading.
The following examples show how to implement these controls in your .aspx files.
<SharePoint:VersionedPlaceHolder ID="vph4" runat="server" UIVersion="4">
<div>Content</div>
</SharePoint:VersionedPlaceHolder>
<SharePoint:UIVersionedContent ID="vc4" runat="server" UIVersion="4">
<ContentTemplate>
<div>Content</div>
</ContentTemplate>
<SharePoint:UIVersionedContent>
You can programmatically enable or disable the Supported User Experiences setting in the Web interface by setting the SPWeb.UIVersionConfigurationEnabled, and SPSite.UIVersionConfigurationEnabled Boolean properties. Setting SPSite.UIVersionConfigurationEnabled to false has the same effect as selecting the Commit new user experience option under Site Actions. In either case, you can no longer switch from one version of the UI to another by using the Web interface (although you can still switch programmatically by setting the properties mentioned previously).
Additionally, you can upgrade the user experience of all Webs in a site collection by using the VisualUpgradeWebs() method. The GetVisualReport() method retrieves a list of reports that contain all of the visual upgrade data for each Web in a site collection.
If you choose not to use Visual Upgrade, your visual customizations will continue to work and you will have access to all the infrastructure (including CSS) related to themes. Choosing to use the old user interface instead of Visual Upgrade enables you to take your time to migrate and upgrade your customizations so that they will work with the new interface. Some visual elements will work as expected in the new interface, but a few custom actions (those using the ControlAssembly, ControlClass, and ControlSrc attributes) will not work. If you have made many visual customizations, especially CSS and toolbar customizations, you should start with the old user interface. After you deploy your customizations, you should test them with the upgraded interface to determine what elements you need to change.
Master Page Changes
Some controls that were previously included in the default master page have moved to the ribbon user interface. If you plan to update an existing master page with ribbon functionality, you must remove these controls from your existing master page. These controls will be added when you incorporate the ribbon into your master page. For information about removing these controls and adding ribbon functionality to an existing master page, see Upgrading an Existing Master Page to the SharePoint Foundation Master Page. Also see Displaying the Server Ribbon and Site Actions Menu on Customized Search Pages Upgraded to SharePoint 2010 Using Visual Upgrade for an example of a fully updated master page.
Changes to CSS Classes
Because the new CSS has changed significantly, any customizations and designs that rely on the CSS classes in Windows SharePoint Services 3.0 and Office SharePoint Server 2007 will work only in the old user interface. Themes work differently in SharePoint Foundation 2010 and SharePoint Server 2010, so any customizations and design work that you have done with themes will not be imported into the new interface. When you redesign your pages after upgrading and redeploying, you should customize the new master page instead of trying to make your old CSS work with the redesigned UI.
Custom Actions and Toolbar Additions
Most custom actions, including those targeted at links and edit control block (ECB) menus, continue to work as expected in the upgraded interface. Because the toolbar is replaced by the ribbon, most custom actions that add buttons to a toolbar will be placed in the Custom Commands tab of the ribbon (Figure 8).
Figure 8. Custom actions on the toolbar and on the Custom Commands tab of the ribbon
.jpg "Custom actions on the toolbar and in the ribbon")
Any Custom Action Element that uses the ControlAssembly attribute, the ControlClass attribute, or the ControlSrc attribute, however, will not appear in the new interface. To make these toolbar additions work before you redesign your application, you can use the old user interface. Or you can choose the Show full toolbar option for each list view and list form that uses a customized toolbar that contains this type of custom action. The Show full toolbar option causes the toolbar to appear with the ribbon and, although this might create redundant functionality, it might be a good option if your customized toolbars appear in a limited number of contexts.
Conclusion
You can take advantage of the enhanced capabilities in SharePoint Foundation 2010 and SharePoint Server 2010 as soon as you install them; however, you do not need to rewrite your code immediately. All deprecated elements of the API continue to be available to you, so that you have time to review the newer elements of the API before incorporating them into your customizations. Additionally, the option of using the old user interface enables you to take your time to rethink and, if necessary, redesign your customizations so that they take full advantage of the new UI. You also do not have to adopt the new UI for all of your sites at one time. Some sites can stay in the last version of the interface and other sites can immediately adopt the new version. The framework gives you the ability to migrate your customizations and take advantage of the new capabilities methodically and in stages, so that you can adopt the enhancements at a pace that works best for you.