MOSS 2007
Automate Web App Deployment with the SharePoint API
Ethan Wilansky and Paul Olszewski and Rick Sneddon
This article discusses:
- SharePoint deployment basics
- Deploying custom Web Parts
- Customizing site branding
- Deploying lists, forms, and reports
|
This article uses the following technologies:
SharePoint
|
Contents
At the 2008 Office System Developer's Conference, one presenter metaphorically described a .NET developer's first look at SharePoint® as equivalent to an experienced mountain climber staring at a smooth wall 100 feet tall and trying to figure out exactly how to scale it. Many Microsoft products offer a dizzying array of approaches to completing a task, and deploying custom SharePoint applications is a good example of such a case. Because SharePoint is a complex and sophisticated application platform, deployment can present some puzzles to the uninitiated.
In this article, we will show you how to automate custom SharePoint application deployments by taking advantage of the SharePoint API. Following this approach allows you to avoid having to create and maintain a custom site definition. You benefit from a more modular set of components to deploy and manage in your source control system, which is an essential part of a continuous integration effort. Finally, you are following a model that Microsoft will continue to improve in the coming years.
We will explain how you can leverage the SharePoint object model to automate deployment from Web application creation to Feature activation. The Visual Studio® code project included with this article provides a number of code samples that demonstrate how to automate some essential tasks in a custom deployment.
Along the way, we will explore tools and techniques provided by Microsoft and members of the SharePoint developer community that we have found to be especially valuable in your quest toward a fully automated deployment.
SharePoint Deployment Basics
Microsoft significantly improved the SharePoint deployment infrastructure with the release of Windows® SharePoint Services (WSS) 3.0 and Microsoft® Office SharePoint Server (MOSS) 2007. The primary components in this deployment infrastructure are the classes in the Microsoft.SharePoint.Administration and Microsoft.SharePoint namespaces and the SharePoint solution deployment framework.
Microsoft also improved the way site definitions and site templates work and how they can be customized. At first glance, it might seem to make sense to use all of these capabilities to support your deployment, but think again. If your goal is to deploy a highly customized portal application in an automated and centralized fashion, you should stay away from site templates and even reconsider a deployment strategy involving custom site definitions.
Most experienced SharePoint developers are likely to agree with our view on site template customization. While they are fine for simple customizations, they are inappropriate for significant customizations because page rendering performance can suffer. Template customizations are stored as differences from the originating site definition and persist as an .stp file in the SharePoint database rather than being served from the file system. When the page renders, the .stp is merged at run time with the underlying site definition in the file system.
What might be more surprising to experienced SharePoint developers is our recommendation to stay away from custom site definitions. Microsoft strongly encourages developers not to customize the out-of-the-box site definitions for a number of reasons. Future service packs may overwrite the existing site definitions and migrations to the next version of SharePoint might not be possible without losing the customizations.
Even if you abide by the recommendation by Microsoft to leave the out-of-the box site definitions alone, there are still more reasons to avoid custom site definitions. For highly customized deployments, site definitions can become huge and unwieldy to manage. A complete site definition can contain multiple Webs. Within each Web there will be one or more pages, and on these pages will be a variety of elements, such as Web Part zones, Web Parts, modules, list definitions, and navigation components. The onet.xml file maintains configuration information about each Web. This file can quickly become a maintenance nightmare as requirements and configurations change. In our experience, it contains between 300 and 600 lines of XML for moderate customizations. If you have five custom Webs in your site definition, suddenly you have between 1,500 and 3,000 lines of XML to maintain.
The SharePoint API and the solution deployment framework provide a better answer. Solutions are deployment packages for SharePoint—they can contain almost anything you need to deploy to SharePoint. An important part of a solution, though technically not required in all instances, is called a Feature. While the solution is the deployable package, the Feature defines aspects of the package that allow it to employ the SharePoint object model and other managed code and to advertise itself within the SharePoint hierarchy (the farm, Web application, site collection, or Web levels).
Microsoft provides a model for automating the initial installation of SharePoint. Note that the task of configuring a SharePoint instance or farm is typically completed by an administrator. The next step is to create a Web application and site for your custom portal application.
While these tasks can be completed by using SharePoint Central Administration, you have the ability to automate them via the SPWebApplicationBuilder and SPWebApplication classes in the Microsoft.SharePoint.Administration namespace. The SharePoint command-line administrative tool (Stsadm) does not support Web application creation by default. By automating these tasks, they will not only get completed faster, but you can ensure consistency across your single server or farm implementations and as your custom solution moves from development to production.
When SharePoint creates a Web application and generates the top-level site collection and root Web, there is a lot happening behind the scenes. When creating a typical Web application, SharePoint does the following:
- Creates a unique entry in the SharePoint configuration database for the Web app and assigns a GUID to that entry
- Creates and configures a Web application in IIS
- Creates a root folder to store the Web application pages and associated resources
- Creates and configures an IIS application pool
- Configures authentication protocol and encryption settings
- Assigns a Default alternate access mapping for the Web app
- Creates the first content database for the Web application
- Associates a search service with the Web application
- Assigns a name to the Web application that appears in the Web application list in SharePoint Central Administration
- Assigns general settings to the Web application, such as maximum file upload size and default time zone
Optionally, you can add alternate access URLs to the Web application. This is just one of many optional tasks you might want to complete after creating a Web application. And when creating a site collection, SharePoint also creates the top-level site based on a site definition and sets general properties for the site, such as the site title and site owner. Completing these tasks manually can take quite a while—they are tedious and error prone because of the amount of data entry involved. Automating this task speeds up task completion and ensures data consistency from one environment to the next.
As you might expect, there is a fair amount of code involved in automating this task. Rather than show it all here, you should download the code that accompanies this article. You'll find the CreateWebApp method in the SPDeployTests project. (Be sure to read the prerequisites document included in the code sample before attempting to run the console application.) We will emphasize key elements of the code here and call out some specific items that could cause trouble when you automate this part of your custom portal deployment.
One more thing to remember: be sure to run the code from a SharePoint server. It is not designed to run remotely. In our experience, it's best to run an automated SharePoint deployment routine on a SharePoint server in the farm.
Web App Provisioning and Settings
In order to create a new Web application, you start by calling the AdministrationService.Farm property from an SPWebService object. Calling the Farm property returns an SPFarm object. The SPFarm object is at the top of the configuration hierarchy and manages all of the servers, services, and solutions in a SharePoint farm. Once you have the SPFarm object, you can pass it to the SPWebApplicationBuilder constructor:
|
SPFarm farm =
SPWebService.AdministrationService.Farm;
SPWebApplicationBuilder webAppBld =
new SPWebApplicationBuilder(farm);
|
SPWebApplicationBuilder is the worker class for creating SharePoint Web applications. It can complete all of the steps previously outlined for creating a Web application. To make use of this class, set properties of the SPWebApplicationBuilder class, and then call its Create method, which returns an SPWebApplication object for the new Web application:
|
SPWebApplication webApp = webAppBld.Create();
|
Use the SPWebApplication class to set additional properties, and then call the Update method to send any changes back to the farm. Finally, call the SPWebApplication Provision method to create the IIS Web application and application pool.
Calling these methods in the right order and at the right time in your code is important. Therefore, be sure to review the code samples for this article to see a working example.
When setting properties on a Web application, there are a couple of points to consider. First, be clear on what a setting actually means. If you're not sure what the implications are of a setting, such as choosing Windows NT LAN Manager (NTLM) authentication versus Kerberos, work with a SharePoint infrastructure expert to make this decision. Secondly, some properties can be tricky to set or are unclear as to their affect. For instance, here is an example of setting the ID property in the SPWebApplicationBuilder object:
|
webAppBld.Id = new Guid("3798E478-4E16-4856-A152-F05EF8C2C777");
|
Like most of the properties in this object, SharePoint will either set the property to a default value or assign a value. In this case, SharePoint will generate a unique GUID and store that along with the Web application in the Objects table of the configuration database. You can run the following query against the SharePoint Configuration database to see all of the Web application objects and their associated ID GUIDs:
|
SELECT id, name FROM OBJECTS
WHERE Properties
LIKE '%Microsoft.SharePoint.Administration.SPWebApplication%'
|
You can assign this value or let SharePoint assign one for you.
If you are configuring a new application pool and assigning a user account, which is the preferred method of setting up SharePoint, there are a couple of important caveats. First, in a workgroup, ApplicationPoolUserName is the name of a local user, without the server name prepended. If SharePoint is part of an Active Directory® domain, then you should use an Active Directory user account and prepend the domain name for this property:
For the ApplicationPoolPassword, you must pass in a SecureString data type for the value. Here is the pattern for building a secure password:
|
// build the password as a secure string
SecureString appPoolPwd = new SecureString();
appPoolPwd.AppendChar('k');
appPoolPwd.AppendChar('E');
// more of the same to build-up the password
appPoolPwd.MakeReadOnly();
|
Be sure that the user name and password you assign to these values match the values as you've set them in your identity repository before attempting to create the Web application.
The next property, ApplicationPoolId, is simply the name of the application pool as it appears in IIS. It's important to note that the WSS 3.0 SDK help file incorrectly states that ApplicationPoolId is a GUID that identifies the application pool. One could argue that it is a unique identifier within the list of application pools in IIS, but it is neither globally unique nor in the format we typically think of for a GUID.
The next stumbling block is encountered when associating a search service instance with the new Web application. Figure 1 shows how to accomplish this task and is followed by further explanation as to how you find the proper search service instance.
Figure 1 Associating a Search Service Instance
|
// get the server hosting the search service
SPServer server = new SPServer("myServer");
// get the office SharePoint server search instances
SPSearchService srchService =
SPFarm.Local.Services.GetValue<SPSearchService>("SPSearch");
// get the proper instance of the search service
SPSearchServiceInstance searchServiceInst =
(SPSearchServiceInstance)srchService.Instances[new Guid(
"C22E9545-71B4-471F-81A7-A213D5A7F8B2")];
// set the search service instance to crawl the web application
webAppBld.SearchServiceInstance = searchServiceInst;
|
There is a service hierarchy in SharePoint where a service contains service instances that actually do the work. Unfortunately, finding a search service instance can be difficult because the instances might have type names, but their Name and possibly DisplayName properties are empty. Therefore, passing the GUID into the Instances collection as in Figure 1 is one way to set this value.
There are two ways you can find the proper GUID of the search service instance. The first option is to query the objects table in the SharePoint Configuration database, as demonstrated in the following code:
|
SELECT id, name, properties FROM OBJECTS
WHERE (Properties LIKE
'<object type=' +
'"Microsoft.SharePoint.Search.' +
'Administration.SPSearchServiceInstance%')
ORDER by ID
|
Another option is to run the EnumFarmServices method in the code SPDeployTests project contained in the code download. Figure 2 shows output from one of our servers with the proper search service instance shown in red.
Figure 2 Instances of SPSearch
|
Name: SPSearch
ID: 7fd9c4b0-25c2-4867-b716-cd3b61e7a08e
DisplayName: SPSearch
Instance 1
Name:
ID:c9043683-a431-4cc7-b30a-fa52163f649b
Type name:Windows SharePoint Services Search
DisplayName:
Instance 2
Name:
ID:c22e9545-71b4-471f-81a7-a213d5a7f8b2
Type name:Windows SharePoint Services Search
DisplayName:Search index file on the search server
|
If you want to configure the search service instance from code and you don't select the proper search service instance, Web application creation will fail with a database foreign key dependency error. There are significantly more settings that you can configure for your Web application. The code download provides some examples to get you started.
Creating the first site collection is straightforward. However, before you create the top-level site collection in a Web farm environment you should reset IIS (using iisreset /noforce). Figure 3 demonstrates how to create a top-level site collection. For brevity, we moved some of the variables into the input parameters for the Add method. The interesting or potentially confusing variables are declared and described above the Add method.
Figure 3 Creating a Site Collection
|
// for the top-level site
string url = "/";
// this is the MS language Locale ID.
// see http://www.microsoft.com/globaldev/reference/lcid-all.mspx
uint LCID = 1033;
// this is the site template for the
// Publishing Site - Collaboration Portal merged site definition
string template = "SPSPORTAL";
// create a site collection with an out of the box site definition
SPSite MSDNSiteCollection = webApp.Sites.Add(url,
"The MSDN site collection", "a description of this site",
LCID, template, "mydomain\\myLoginName",
"my owner name", "my email address");
// close the site collection
MSDNSiteCollection.Close();
|
Managing Web.config
A common task in most SharePoint code projects is updating web.config for each Web application. While updates can be made manually in small implementations, that doesn't scale to large, multi-developer projects. Keeping a copy of a SharePoint Web application's web.config in a source control system and having developers check out the file, update it for their project, and check it in is one obvious possibility. You could then script the web.config deployment to your Web front-end servers on a schedule or based on a particular event, such as check-in. However, this approach does not take advantage of the ability of SharePoint to manage web.config settings for you.
If you use the SharePoint API to update web.config, new front ends added to the SharePoint farm receive the updates to the web.config and SharePoint maintains these settings in existing front ends. There are two common approaches for getting SharePoint managed updates into web.config programmatically. For Web Part SafeControl entries and custom access control policies, rely on the SharePoint solution packaging framework. For unique entries, use the SPWebConfigModification class in the Microsoft.SharePoint.Administration namespace.
Figure 4 shows how to add an XML child element to your web.config file using SPWebConfigModificationType.EnsureChildNode. In this example, the SPWebConfigModification class ensures that the <add key = "key01" value = "Setting01" /> element appears inside of the appSettings element. The comments in the code explain how to achieve this result. Notice the single quotes for the values 'key01' and 'Setting01' in the xmlValue variable. Using single quotes makes the code clearer and the SPWebConfigModification class takes care of changing these to double quotes when the values are written to each front-end Web server.
Figure 4 Adding a Child Node in Web.config
|
// get the webApp
SPWebApplication webApp =
new SPSite("http://msdn.fabrikam.com").WebApplication;
// the element to add or verify contains
// the following name and attributes:
string elementName = "add[@key='key01'][@value='Setting01']";
// the location where the new element should be added or verified is
// present in the target web.config
string xPath = "configuration/appSettings";
// the value exactly as it should be written
string xmlValue = @"<add key = 'Key01' value = 'Setting01' />";
SPWebConfigModification modification =
new SPWebConfigModification(elementName, xPath);
// this name determines who can modify this entry -
// only the owning name (typically a fully qualified program name,
// GUID or possibly the WebConfigModificationFeatureReceiver.OwnerID
// name can modify the entry
modification.Owner = "SPWebConfigTestAddChild";
// for identical entries, this controls what order the entry is made
// typically fine to leave this at 0
modification.Sequence = 0;
// EnsureChildNode means to add or verify that the child node is present
// as specified by the Value property next
modification.Type =
SPWebConfigModification.SPWebConfigModificationType.EnsureChildNode;
// the actual value to write
modification.Value = xmlValue;
// add the modification to the SPWebConfigModification collection
webApp.WebConfigModifications.Add(modification);
// check all web applications on the farm front ends to ensure
// that the web.config modification(s) have been applied
webApp.Farm.Services.GetValue<SPWebService>().ApplyWebConfigModifications();
// propagate changes in web application across the farm
webApp.Update();
|
You can also use the SPWebConfigModification class to add, change, or ensure that an attribute value within an XML node appears in web.config. This is simple when you're writing or verifying an XML attribute that is unique in the web.config file. For example, you might want to change the autoDetect attribute from true to false in the following unique XML fragment:
|
<system.net>
<defaultProxy>
<proxy autoDetect="true" />
</defaultProxy>
</system.net>
|
In this case, the SPWebConfigModification constructor looks like the following:
|
SPWebConfigModification modification =
new SPWebConfigModification(
"autoDetect", "system.net/defaultProxy");
|
The SPWebConfigModificationType enumeration is then set to EnsureAttribute, like this:
|
modification.Type =
SPWebConfigModification.SPWebConfigModificationType.EnsureAttribute;
|
EnsureChildNode and EnsureAttribute are the two values in this enumeration that you should use for your updates. There are a number of blog entries suggesting that EnsureSection (the third enumeration) works for writing whole sections into web.config. Unfortunately, you cannot remove the entries easily.
Other than the differences mentioned, there is little difference to the pattern you use for writing an attribute versus writing one or more XML nodes to web.config. What's a little trickier is writing or verifying an attribute when there are identically named elements inside of a parent element (for example, multiple add child elements in the appSettings element). In this case, the xPath string gets you to the correct element.
Consider the following appSettings element:
|
<appSettings>
<add key="FeedCacheTime" value="300" />
<add key="FeedPageUrl"
value="/_layouts/feed.aspx?" />
<add key="FeedXsl1"
value="/Style Library/Xsl Style Sheets/Rss.xsl" />
<add key="key01" value="Setting01" />
</appSettings>
|
In order to change the value attribute of the fourth add element, use an xPath statement that specifies the child element, like so:
|
configuration/appSettings/add[4]
|
xPath syntax is the key to pinpointing exactly what you need to update. One reference for xPath syntax is available at msdn2.microsoft.com/ms256115 .
Figure 5 shows how to modify or verify that the value attribute is set to Setting02 in the fourth "add" child element of the appSettings element. For brevity, we removed comments that appear in Figure 4. Now that these settings have been added, you can inspect the web.config file on any Web front end running the target Web application.
Figure 5 Modifying the Fourth Attribute of a Child Node
|
SPWebApplication webApp =
new SPSite("http://msdn.fabrikam.com").WebApplication;
// the attribute's name to which a value will be added,
// changed or verified:
string attributeName = "value";
// the location of the element that should be modified or verified
string xPath = "configuration/appSettings/add[4]";
// the value of the attribute as it should be written
string attributeValue = "Setting02";
SPWebConfigModification modification =
new SPWebConfigModification(attributeName, xPath);
modification.Owner = "SPWebConfigTestModifyAttribute";
modification.Sequence = 0;
// EnsureAttribute means to add or verify that an attribute value is
// present as specified by the Value property next
modification.Type =
SPWebConfigModification.SPWebConfigModificationType.EnsureAttribute;
modification.Value = attributeValue;
webApp.WebConfigModifications.Add(modification);
webApp.Farm.Services.GetValue<SPWebService>().ApplyWebConfigModifications();
webApp.Update();
|
Figure 6 shows how to see what settings are being managed by SharePoint by enumerating the collection of settings contained in the WebConfigModfications property of the Web app. Manually removing or changing the entries in web.config that are managed by SharePoint won't do you any good in the long term. SharePoint tracks these entries and ensures that they are in web.config each time the WSS service restarts.
Figure 6 Enumerating a List of Modifications
|
SPWebApplication webApp =
new SPSite("http://msdn.fabrikam.com").WebApplication;
// use the System.Collection collection class to get
// a collection of modifications in the configuration database
Collection<SPWebConfigModification> collection =
webApp.WebConfigModifications;
// iterate the collection of modifications and return properties
// about the items
foreach (SPWebConfigModification item in collection)
{
Console.WriteLine("\nitem {0}", collection.IndexOf(item));
Console.WriteLine("owner is: {0}", item.Owner);
Console.WriteLine("path is: {0}", item.Path);
Console.WriteLine("name is: {0}", item.Name);
Console.WriteLine("value is: {0}", item.Value);
Console.WriteLine("sequence is: {0}", item.Sequence);
}
|
To remove entries, you need to know the value of the Owner property for the modification. Then you can use the Remove method of the SPWebApplication's WebConfigModificatons property to delete entries maintained by SharePoint. See Vincent Rothwell's blog post at
blog.thekid.me.uk/archive/2007/03/20/removing-web-config-entries-from-sharepoint-using-spwebconfigmodification.aspx for more information about removing entries. There is also a sample in the code download for this column showing how to remove an entry.
Modifying web.config can be tricky using the SPWebConfigModification class. There are a number of caveats that you should be aware of. You can read about the most common ones at Reza Alirezaei's blog (
blogs.devhorizon.com/reza/?p=459) and Mark Wagner's blog (
www.crsw.com/mark/default.aspx). We highly recommend you take a close look at these articles before getting started using this class. After you've done your research, be sure to carefully test your modifications and your ability to remove these modifications using the SPWebConfigModification class in an isolated environment, in a shared development environment, and in a Web farm development environment.
Even with the ability of SharePoint to manage web.config settings, there are instances when you might want to manage settings without the SharePoint API, for example, managing a unique section of sensitive credential information. In this case, consider using the WebConfigurationManager in the System.Web.Configuration namespace. To encrypt the information, you can use either the aspnet_regiis utility or use the AppSettingsSection class in the System.Configuration namespace. You can read about how to edit and encrypt Web.Config sections using C# 2.0 at
c-sharpcorner.com/UploadFile/neo_matrix/EditWebConfig05042007091116AM/EditWebConfig.aspx.
Custom Web Parts
Microsoft built the solution packaging and deployment framework with Web Parts in mind. The key to end-to-end Web Part deployment starts with the Web Part deployment file, officially known as the Web Part Control Description file. There are two Web Part deployment formats: .WebPart and .dwp. Both are XML files with underlying schemas. Web Parts Control Description Files at
msdn2.microsoft.com/library/ms227561(VS.80).aspx describes the .WebPart schema.
The .dwp format is available for backward compatibility. It was the SharePoint Web Part control description file format in WSS 2.0 and SharePoint Portal Server 2003. While you can use this format for your Web Part deployment in WSS 3.0 and MOSS 2007, you should avoid .dwp if your goal is to fully automate your Web Part deployments. This is because the .dwp schema does not include some of the essential settings that are required for full automation. For example, if you need to hide the chrome (otherwise known as the styling) of a custom Web Part, you can't do that directly with a .dwp file.
How you begin creating your custom Web Part affects the type of deployment file that is generated and is expected for deploying your component. Surprisingly, there is little guidance explaining the scenarios that automatically generate a .dwp file or a .WebPart file. If you deploy a Web Part to SharePoint using the older .dwp format, the only way we have found to switch to a .WebPart file is to uninstall the solution or, if you're not using a solution, manually remove the Web Part from SharePoint, rebuild the project, and recreate the solution with a .WebPart file.
There are two approaches you can take to ensure that your custom Web Part is deployable using the newer ASP.NET .WebPart format. The first approach is to start a Visual Studio class project. Note that when you declare your Web Part class, instead of inheriting from the SharePoint Web Part class (Microsoft.SharePoint.WebPartPages.WebPart), inherit from the ASP.NET Web Part class, like so:
|
public class WebPart1 : System.Web.UI.WebControls.WebParts.WebPart
|
Microsoft recommends inheriting from the ASP.NET Web Part class in most of its documentation chiefly because a Web Part that inherits from this class is potentially deployable both to SharePoint and to a custom ASP.NET portal. We say potentially because a Web Part that interacts with the SharePoint object model might be dependent on running in the context of a SharePoint portal. If you end up requiring one of the handful of features available in the SharePoint Web Part class, you can later switch to inheriting from the SharePoint namespace. However, you should create your SharePoint solution and your .WebPart file before making this switch.
The second approach to ensuring that a .WebPart deployment file is automatically created is by using the Visual Studio Extensions for WSS 3.0 or the new WSPBuilder Extension. When using these tools and the included SharePoint Web Part project template, it doesn't matter which namespace you use when inheriting from the Web Part class.
Once you have a .WebPart file, the next step in full deployment automation has more to do with the solution, which we explore only briefly in this article. For now, the key is to get the .WebPart file prepared for the deployment.
While you can manually add elements to your .WebPart file, the following approach will make this effort significantly easier. In the constructor for your Web Part, add the following code:
|
// make the web part deployment file exportable
this.ExportMode = WebPartExportMode.All;
|
When you build and later install and configure your Web Part, this allows you to export the .WebPart file. You can also manually set this in the tool part properties instead of declaring this in code.
Next, install your Web Part into SharePoint or a custom ASP.NET Web application and drop it onto a Web Part zone on the page. (Later in this article, we will describe ways to automate the initial Web Part deployment.) From the Web Part's Tool Part Properties dialog, configure the Web Part exactly as you would like it to appear and function on the page. From the edit menu of the Web Part, click Export. Save the exported .WebPart file into the Visual Studio project created for the Web Part.
Figure 7 shows a basic .WebPart file as prepared by version 1.1 of the Visual Studio Extensions for WSS following the configuration steps outlined previously. The settings for custom toolpart properties and custom toolparts with properties will also appear in the .WebPart export after configuring their settings.
Figure 7 Web Part XML File
Prior to Configuration
|
<?xml version="1.0" encoding="utf-8"?>
<webParts>
<webPart xmlns="http://schemas.microsoft.com/WebPart/v3">
<metaData>
<!--
The following Guid is used as a reference to the web part class,
and it will be automatically replaced with actual type name
at deployment time.
-->
<type name="5ad2f5ec-8c67-4ca9-b2fb-83c4dadd50c0" />
<importErrorMessage>
Cannot import WebPart1 Web Part.</importErrorMessage>
</metaData>
<data>
<properties>
<property name="Title" type="string">WebPart1 Web Part</property>
<property name="Description" type="string">
WebPart1 Description</property>
</properties>
</data>
</webPart>
</webParts>
|
|
<webParts>
<webPart xmlns="http://schemas.microsoft.com/WebPart/v3">
<metaData>
<type name="WPUsingVSeWSS1dot1.WebPart1, WPUsingVSeWSS1dot1,
Version=1.0.0.0, Culture=neutral, PublicKeyToken=9f4da00116c38ec5" />
<importErrorMessage>
Cannot import WebPart1 Web Part.</importErrorMessage>
</metaData>
<data>
<properties>
<property name="AllowClose" type="bool">False</property>
<property name="Width" type="unit">170px</property>
<property name="AllowMinimize" type="bool">False</property>
<property name="AllowConnect" type="bool">True</property>
<property name="ChromeType" type="chrometype">None</property>
<property name="TitleIconImageUrl" type="string" />
<property name="Description" type="string">
WebPart1 Description</property>
<property name="Hidden" type="bool">False</property>
<property name="TitleUrl" type="string" />
<property name="AllowEdit" type="bool">True</property>
<property name="Height" type="unit">25px</property>
<property name="HelpUrl" type="string">
/pages/SimpleHelp.htm</property>
<property name="Title" type="string">WebPart1 Web Part</property>
<property name="CatalogIconImageUrl" type="string" />
<property name="Direction" type="direction">NotSet</property>
<property name="ChromeState" type="chromestate">Normal</property>
<property name="AllowZoneChange" type="bool">False</property>
<property name="AllowHide" type="bool">False</property>
<property name="HelpMode" type="helpmode">Modal</property>
<property name="ExportMode" type="exportmode">All</property>
</properties>
</data>
</webPart>
</webParts>
|
Unfortunately, if your Web Part uses the connection provider or connection consumer interface, you have to either programmatically wire up your Web Parts or, more commonly, allow the connection to be made at run time via the Web Part edit pulldown menu. The tool part connection settings aren't saved in the export file. If you don't want to wire up your Web Parts in the Web Part code, use the SharePoint object model to automate this part of the deployment. Figure 8 shows how to programmatically connect the provider and consumer connection points of two Web Parts.
Figure 8 Connecting Web Parts
|
// webPartPage is an SPFile object
// page check out is required before modifying publishing pages
webPartPage.CheckOut();
// get the web part manager for the page
SPLimitedWebPartManager webPartMgr =
webPartPage.GetLimitedWebPartManager(PersonalizationScope.Shared);
// providerWebPart and consumerWebPart are of type
// System.Web.UI.WebControls.WebParts.WebPart
// providerConnection is type
// System.Web.UI.WebControls.WebParts.ProviderConnectionPoint
// consumerConnection is type
// System.Web.UI.WebControls.WebParts.ConsumerConnectionPoint
// connect the web parts
webPartMgr.SPConnectWebParts(providerWebPart,
providerConnection, consumerWebPart, consumerConnection);
// update, check in, and publish the page
webPartPage.Update();
webPartPage.CheckIn("");
webPartPage.Publish("");
|
You obtain the consumer and provider connection points for the corresponding Web Parts from the collections returned by the GetConsumerConnectionPoints and GetProviderConnectionPoints methods of SPLimitedWebPartManager. This approach works if the connection types are compatible. If they are not, such as when you need to pass filter values from a QueryStringFilter Web Part to a consumer Web Part, you add a transformer to the SPConnectWebParts call, like so: