The Web Part Imported into Share-Point

Note that you can ensure the creation of .webpart deployment files by inheriting from the WebPart class in the System.Web.UI.WebControls.WebParts namespace rather than Microsoft.SharePoint.WebPartPages namespace. (For examples of when you might want to inherit from SharePoint’s WebPart class, see the source listed in the “Resources” sidebar.)

Microsoft exposes a significant subset of the SharePoint object model through Web services. Using SharePoint Web services to access the object model allows you to develop a solution without a dependency on direct access to SharePoint assemblies. SharePoint hosts the Web services in the _vti_bin virtual directory on each Web Front End (WFE) server.

In Visual Studio, you add SharePoint Web services to a solution in the same manner as you do any Web service reference. SharePoint Web service URLs have the following format:

where <SharePointServer> is the URL associated with the Web application. For example:

When you add a Web service reference, Visual Studio creates proxy classes for both the service and the data types used by the service. For more information on interacting with these Web services, please see ” WSS SDK 3.0 Topic: Web Service Guidelines” and ” SharePoint Web Services.”

Implementing a three-tiered architecture furthers the goal of isolating code and removing dependencies on SharePoint and other outside sources. This approach can improve your ability to develop off-server by abstracting business, data access, and UI logic from one another, enabling you to break code into manageable pieces and reduce dependencies between them. This approach also yields more testable code; more on this in the section “Testing Code and Managing Dependencies”.

There are other tools you can use. Removing the dependency on SharePoint across the entire codebase is unrealistic. Developing for SharePoint off-server generally requires the use of a SharePoint instance, usually hosted in a virtual machine, early in the SDLC. With the growth of SharePoint development, several tools have been created to deal with this significant dependency. One such tool is Bamboo Solutions’ SharePoint on Vista Installation Helper. This tool enables the installation of WSS 3.0 SP1 or MOSS 2007 SP1 on Windows Vista, giving you the ability to develop SharePoint-dependent solutions without needing Windows Server.

Microsoft does not support running SharePoint in this way. However, this approach has resonated in the SharePoint development community because it helps reduce the footprint that this dependency on SharePoint creates. For further information, see ” How to install Windows SharePoint Services 3.0 SP1 on Vista x64/x86.”

5. Testing Code and Managing Dependencies

The widespread adoption of unit test frameworks and related test tools has naturally made its way into SharePoint development. Unit tests and integration tests are two primary test categories. Both test types exhibit different characteristics and require the use of different tools and techniques.

When writing unit or off-server tests, it’s considered a best practice to simulate external dependencies with substitutes such as stubs or mocks. Bypassing in objects that mimic external dependencies, your test becomes faster and more focused on the behavior you are testing. To be effective, this approach requires that you follow the principles of testable, object-oriented design, or use a specialized framework for isolating tightly coupled components of your solution.

Identify the behaviors and business rules that are infrastructure independent and make sure you have a strategy for testing them in isolation. To isolate interactions with SharePoint, a database, or a Web service, you can introduce the Repository pattern to abstract away the details of the back-end system. These repository objects can be passed into higher-level components by using inversion of control (IoC) and dependency injection (DI) principles. For information on IoC and DI, see ” Tame Your Software Dependencies for More Flexible Apps.”

To increase the testability of your presentation components implement the Model-View-Presenter (MVP) pattern. For more information about testable code patterns, see ” Design for Testability.”

Other major challenges that SharePoint developers face when unit testing deals with the SharePoint object model. Simply put, testing those components in isolation is a nontrivial task. It is a direct result of a limited number of interfaces and abstractions as well as a high number of sealed classes—classes with inner dependencies or without a public constructor.

One product equipped to deal with these shortcomings is TypeMock Isolator, a commercial mocking framework that allows for the mocking of sealed, concrete, static, or internally constructed classes. For other mocking frameworks to be applicable, you need to adhere to patterns and principles we have already eluded to. TypeMock Isolator or its new SharePoint-specific version, Isolator for SharePoint, will work around these limitations and allow for increased code coverage without relying on a running instance of SharePoint. The patterns and practices (P&P) team also use TypeMock Isolator in their SharePoint Guidance reference architecture.

At some point, you will have to write integration tests that are dependent on the SharePoint object model. It is good practice to manage your unit tests that are server-independent from those that are server-dependent.

You can use the Test List Editor in the Test Manager in Visual Studio to separate your unit and integration tests. For instance, you could create two lists of tests: server-dependent and server-independent. This approach allows you to select which set of tests to run, depending on whether or not you’re on the server.

The Test List Editor Showing a Categorized Test List

In cases in which Visual Studio is installed on the server, you can run and debug your tests in the IDE or use the MSTest.exe command-line tool to run server-dependent tests. Unfortunately, MSTest does not run unless Visual Studio is installed on the server. Our hope is that a future version of MSTest will not include this heavy dependency.

MSTest.exe allows you to specify which tests you want to run through command-line arguments. When you run MSTest.exe, you must specify either the /test container or the /test metadata option. By using the /test metadata option, you can specify which tests will run. For example, to run all server-dependent tests, type:

To run a specific test within the server-dependent tests, type:

For examples of on-server tests and tests using a mocking framework, see the sample code in the Visual Studio SPTips solution included with this article’s code download.

6. Continuous Integration and Automated Build

Keeping code in source control, relying on continuous integration, and automating the build process are essential steps to the efficient release of high-quality code assets. SharePoint makes the setup of this environment challenging, to say the least. For this trip, the most important starting point is the ” Team Development Overview” topic.

Later in the overview, you’ll see the SharePoint Guidance topic “How to: Create an Automated Build and Deployment Solution with Team Foundation Server Build.” This topic focuses on creating build targets to build and deploy solutions. While this method has merit, it is not useable when the TFS build and SharePoint servers do not reside in the same environment, as is often the case in the enterprise. Building your solution packages using targets limits the use of packages to the automated build environment and thus does not encourage early development and testing of packages by developers.

The alternative is to use post-build events within Visual Studio. The post-build events can be set up to perform the same packaging steps as the MSBuild targets and allow developers to build packages for deployment to their own sandbox environments. This approach also works with third-party tools such as WSPBuilder and STSDEV.

When deploying to the enterprise, you might also need to consider versioning solution packages. Tying the solution version to the current build version is one approach. This can be facilitated by using custom application code run in the AfterBuild MSBuild event or from the post-build event. Also consider solution IDs in the automated build and whether to generate new IDs with each build. This decision will impact your ability to upgrade solutions in the future. As a general rule, generate new solution IDs when assembly versions change. Otherwise, keep the solution IDs the same where version IDs are static between builds.

Rather than repeat information that you can get from the SharePoint Server Developer Center, we will augment this tip by focusing on how to further simplify the automated build process. In the SharePoint guidance topic “How to: Create an Automated Build and Deployment Solution with Team Foundation Server Team Build,” the P&P team assumes you are using VSeWSS/extensions.

While VSeWSS is a fantastic addition to a SharePoint developer’s toolkit, with capabilities like the WSPView panel that allows you to configure your solution on the fly, we’ve found that it is not well suited for medium to large implementations or teams that follow agile development methodologies.

The P&P SharePoint guidance team documentation states that VSeWSS provides one-click deployment and F5 debugging. The one-click deployment capability is certainly part of VSeWSS, but the F5 debugging capability has more to do with the fact that you must run Visual Studio locally on your instance of SharePoint. This is a requirement for installing VSeWSS. Although you can use a registry hack for getting VSeWSS installed on a workstation, most of the extension’s benefit is lost when installed on a workstation.

The documentation also states that many tools such as WSPBuilder and STSDEV require developers to maintain Feature.xml and Manifest.xml files for SharePoint solution packaging in a Web solution package. In reality, these tools are constantly evolving. For example, WSPBuilder now includes extensions that allow easy maintenance of Feature.xml and Manifest.xml in Visual Studio 2005 and 2008.

VSeWSS is most useful when you are unsure about how to structure a SharePoint project. For example, you might want to use a VSeWSS project type to determine the structure of a Web Part or a SharePoint Workflow project. Once your know-how, you can take that information and move it to a ubiquitous project type. The primary issues around using VSeWSS for a medium to large project are as follows:

• The extensions are designed to be installed on an instance of Visual Studio running on a SharePoint server. Therefore, they have a hard dependency on WSS.
• Developers who have not installed VSeWSS will not have the special project types that VSeWSS creates and will not be able to open projects that rely on them.
• Rebuilding a solution is made more complicated by VSeWSS.

The guidance documentation suggests that the other approach is to manually create a SharePoint solution file for each Visual Studio solution, along with the deployment manifest manifest.xml. However, tools such as WSPBuilder allow you to automate this step within your build.

The keys to a successful automated build are:

• Use standard Visual Studio project types (i.e., class projects for Web Parts) so that all developers can easily open a project.
• Structure your code project so that solution packaging is integrated into the project. There is no need to create a separate deployment project.
• Set up a post-build event to run WSPBuilder or another automated solution-building tool to build the Sharepoint solution file. This approach works both for the local deployment of the solution and for the automated build process.
• Use Macro conditions to control the parts of your post-build event that get called depending on where the build is occurring.
• An automated build is further complicated by an InfoPath project. For information on this, see the tip “Dealing with InfoPath Projects in an Automated Build” in the online version of this article.

Solution Packaging Structure Integrated into the Web Part Project Code Download

Don’t deploy to the global assembly cache (GAC) until you move to an integration environment. Keeping assemblies in the BIN folder makes debugging custom SharePoint applications significantly easier. There are certain project types that don’t fit this model, such as SharePoint event handlers and SharePoint Features. By placing compatible assemblies in the BIN folder, developers in a shared development environment won’t have to endure frequent IIS resets after each deployment.

Some pointers for running SharePoint assemblies from the BIN are:

• Decorate your assembly with the [assembly: System.Security.AllowPartiallyTrustedCallers] attribute.
• Configure custom code access security (CAS) policy or set web.config to full trust, as shown here:

(Note that setting the trust level to full is only appropriate for local or internal development where your code assets will eventually be deployed to the GAC.)

• Sign your assemblies for eventual deployment to the GAC.

7. Have SharePoint Manage Custom Config Settings

Like any application, SharePoint solutions rely on configuration settings to operate properly. A custom application with only a few configuration settings may be easy to manage manually. In contrast, when developing enterprise or commercial applications in SharePoint, the number of configuration settings can be considerable.

As a result, knowing the different setting types and how to manage them is important to developing, deploying, and managing applications. The best approach is to increase the number of settings that SharePoint manages and reduce the number of settings managed manually.

Understanding the types of settings helps identify where the settings belong. SharePoint configuration settings generally fall into three categories: core, custom, and SharePoint settings.

Core settings are used across a SharePoint Web application. Enterprise Library application blocks and external Web services configurations are examples of typical core settings.

Custom settings are for custom build components. These settings are used to provide configuration settings for the custom component and are not shared outside the component. For example, custom settings could be used to provide directory server settings for an LDAP lookup.

SharePoint settings are required to make the solution work within SharePoint. Settings in this category include SafeControls entries, SessionState customizations, or registering HttpModules.

After you categorize your settings, you can deploy them to the right locations to manage them. The goal is to reduce the number of settings managed manually. Letting SharePoint handle settings reduces the number of errors that can occur when applications are deployed.

Core settings are best managed in source control. This allows for maintaining the history of a setting while providing a single source of truth for the settings. In addition, this approach allows for maintaining discrete versions of configuration files for development, test, and production environments.

You can automate custom settings installation and management by using the SharePoint object model and deployment tools. Use the SPWebConfigModification class, solution deployment, and the CONFIG directory under the SharePoint 12 hive to form your configuration management strategy. Please see the “Build Deployable Solutions” section in this article for additional details about deploying through solutions.

The SharePoint SPWebConfigModification class allows you to programmatically register settings in the web.config of a SharePoint Web application. Using SPWebConfigModification, you can write a console application or stsadm extension to list, add, or delete configuration entries. This approach allows for rapid and consistent modification of large sets of SharePoint configuration settings. The SPWebConfigModificationType enumeration within this class contains three values specifying the type of modification being made: EnsureChildNode, EnsureAttribute, and EnsureSection. Exercise caution when using EnsureSection because entries added with this enumeration cannot be easily removed. For more information, see ” Automate Web App Deployment with the SharePoint API.”

The SharePoint CONFIG directory allows you to declaratively register settings by maintaining XML files in this directory. WSS applies settings in the XML files to the web.config when SharePoint creates a Web application. Settings in this folder are applied to all Web applications. For information on this approach, see ” Managing Web.Config Customizations.”

8. Know Where Configuration Settings Belong

The previous tip explored different types of SharePoint configuration settings and how to manage them. As an application is promoted through environments, such as from test to production, changes to the configuration settings, especially those pointing to external systems, can feel like sand shifting under your feet. Knowing where configuration settings belong can put the management of environmental settings on more solid ground.

Composite application development has increased reliance on configuration settings. The power and ease of use of configuration settings have arguably led to their overuse. One way to reduce constant changes to these settings is by applying the convention-over-configuration paradigm by instead inferring values from things such as naming conventions. We outline an example of the convention-over-configuration paradigm in the “Continuous Integration and Automated Build” section by demonstrating how to integrate SharePoint Solution packaging into your Visual Studio projects. A related example of this paradigm appears in the Web content tip, “Use Relative Links Whenever Possible.”

Instance-specific settings are unique to each instance of a Web Part. For example, you might have a Web Part that displays a list of projects on a program manager’s page, while on a developer’s page it shows project and task details. Instance-specific settings are best stored in a custom Tool Part or in a Web Part’s miscellaneous Tool Part properties.

Configuration settings being used by more than one component are considered global settings. Examples of settings in this category are URLs for external Web services, business object settings, and data settings. These settings are best kept in web.config and managed as described in the “Have SharePoint Manage Custom Config Settings” section.

9. Brand SharePoint for Scale and Maintenance

Branding your SharePoint site provides users with the most obvious visual indication of your application’s purpose. Branding involves working with various artifacts, such as Master Pages, content pages, page layouts, site definitions, and CSS. For a tip on creating custom Master Pages, see the online tip “Creating Custom Master Pages.”

Make sure your application scaling and maintenance strategy takes into account how you will manage these branding artifacts. For details on SharePoint branding, see “Microsoft Office SharePoint Server 2007 and Windows SharePoint Server v3” in the “Resources” sidebar.

Before choosing a tool for branding, consider the size of your SharePoint implementation, the extent of your branding effort, and the expertise of the developers supporting the application. We will focus on two tools: SharePoint Designer and Visual Studio.

SharePoint Designer has its roots in FrontPage and is a Web design tool useful for editing Master Pages and CSS. However, the ease of use provided by SharePoint Designer comes at a price:

• There’s no integrated source control support.
• Changes made within SharePoint Designer result in the modified content becoming unghosted.

In an unghosted state, copies of the content are stored in the content database instead of the file system. As a result, unghosting has the following effects:

• Makes deployments difficult to manage because the content can be updated only within SharePoint or SharePoint Designer
• Disconnects a site from updated content deployed to the file system
• This leads to potential performance issues on large, active SharePoint implementations

For these reasons, we believe SharePoint Designer is most appropriate for small to medium implementations and prototypes.

Visual Studio provides a consistent development environment for both application components and branding artifacts, but it lacks the graphical editing functionality found in SharePoint Designer. Because of this, developers must be more proficient in editing HTML and CSS. A good project structure must be set up to maintain the branding artifacts. With Visual Studio’s integrated source control support, it’s easier to manage environment-specific configurations and package branding artifacts to be deployed across multiple environments. In addition, branding artifacts remain ghosted. Therefore, Visual Studio is our preferred SharePoint branding tool for large enterprise and commercial implementations.

There are three approaches to applying to the brand: site templates, custom site definitions, and OOB site definitions coupled with customizations via Feature Stapling. Creating custom site templates may be the fastest approach for small implementations and prototypes. However, sites created from a template will not update when a new template is uploaded. Custom templates do not allow you to specify the template ID, which will require changes to any provisioning code that references the templates. Also, site templates create only unhosted content, which could impact performance.

Site definitions are more flexible and portable than site templates. You can manage the site definition file (onet.xml) and associated content in source control and deploy ghosted content, allowing a site to be updated with new content provided that it has not already been customized. Site definitions can be difficult to create because of the complexity of the XML you need to edit. This task is made easier by using OOB site definitions (found in 12\Template\SiteTemplates) as a starting point or by exporting a site definition using VSeWSS. For information about site definitions, see ” Site Definitions Demystified.”

When dealing with medium to large implementations, combining OOB site definitions with custom Features is the best approach. Features can be used to extend site definitions and provide a modular approach to provisioning sites. For a good overview of Features, look at the Office Space column ” Features for SharePoint.” The VSeWSS extensions, as well as some third-party tools, provide templates for creating common Features used in branding Web sites.

Feature stapling lets you attach a Feature to a site definition and have it enabled when a new Web site is created. This is a great way to apply your branding to the SharePoint OOB site definitions.

10. Build Deployable Solutions

You can get your components into a SharePoint Web application in several ways. This section focuses on how to utilize the packaging and deployment frameworks that SharePoint provides, including Web solution packages (Solutions/WSPs), Features, and the SharePoint object model.

Deciding how to package components depends largely on where the components are being deployed. Solutions contain files that will be deployed to the server. Features contain content that will be deployed to the content database.

A Sharepoint solution contains the assemblies and resources to be deployed to SharePoint Web applications. Solutions are compact and simple to deploy and retract, and SharePoint handles mirroring file updates in Sharepoint solutions across multiple servers in a farm. You can also use Sharepoint solutions for web.config modifications. See the sections “Know Critical SPDev Tasks and Information Sources” and “Have SharePoint Manage Custom Config Settings” for additional details on solutions and web.config modifications. Figure 8 lists the common folder locations supported by solutions and their contents. The “12 hive” refers to the SharePoint application root, or <%CommonProgramFiles%>\Microsoft Shared\Web server extensions\12 by default.

• Because SharePoint solutions are managed in the configuration database, there can be only one unique instance of a SharePoint solution in a farm. This point is important if you intend to use the same farm to host different releases of the same Web application—for example, both current maintenance and future development environments.
• SharePoint tracks Solutions by ID, not by name, so you need to maintain solution IDs in source control if you intend to upgrade Solutions in the future.
• The 12 hive is a shared Web application space. If you plan on hosting multiple Web apps on the same farm, you need to ensure that your SharePoint solutions do not overwrite existing SharePoint files or files deployed by other solutions in this space.
• Solutions cannot deploy files outside the folders listed in Figure 8, including folders under the Web application, such as resources, global _wpresources, or other folders outside the 12 hive.
• Solutions cannot deploy content inside a SharePoint Web application. This is the role of SharePoint Features.

Features can make Web Parts available in the gallery, upload and publish files to document libraries, and perform custom actions such as setting the site theme or default Master Page by using Feature receiver assemblies. See the information about using the right branding technique earlier in this article for information on using Features for branding.

Here are some caveats for creating Features:

• Features do not track added content, so it’s the responsibility of the Feature to clean up after itself when it is deactivated by using a Feature receiver. Consider the entire life cycle of the Feature and whether content deployed by the Feature may be needed by other parts of the Web application before the content is deleted. For example, removing a Master Page on deactivation of a Feature will break any pages that inherit from that Master Page.
• Deactivate a Feature from all Web applications before removing the solution used to deploy the Feature. If you don’t, the solution deployment will fail, and if the Feature folder has been removed, you will need to force an uninstall of the Feature using STSADM.

Enough Said

Using this article as your map, review the references provided for information, and download the article’s code sample to help you get started. Perhaps as you develop applications on the SharePoint platform, you will review these best practices again and also find use in the code samples. If you need clarification or want to give us feedback about the tips we’ve provided or other tips you consider important, please send us your questions or comments, and we will endeavor to respond quickly. You can reach us via e-mail at ewilansky@yahoo.com.

Additional Tips

Here are some additional tips for developing SharePoint solutions.

Use Relative Links Whenever Possible

Consider using relative links rather than absolute links. Including relative links to locations such as Document libraries, data connections, and Reports libraries simplifies deployment from one SharePoint instance to another. With the Reports library example in mind, if you use a consistent Web location for the Report library in all your SharePoint environments, you’ll no longer need to change pointers to reports as you move your application from one environment to the next. Typically, convention over configuration applies to code configuration, but this concept can also be loosely applied to other configuration aspects of your deployments.

On a related note, we hope that Microsoft will support relative links inside the SharePoint platform, where currently some configuration settings require absolute links. For example, you must specify an absolute URL to the Form Library in an InfoPath .udcx data connection file, and the ReportViewer Web Part requires an absolute path to the report definition.

Creating Custom Master Pages

One common way to brand SharePoint sites with your look and feel is to create custom Master Pages, which give you the most control over the layout of your site. You can take an existing SharePoint Master Page and modify it to meet your needs. This approach works best if the existing Master Page is close to the layout you want. If the look and feel you want is very different from any of the OOB Master Pages, you might be inclined to start from scratch. However, because SharePoint requires certain functionality in Master Pages, it’s recommended that you start with a minimal Master Page and build your look and feel from there. To find out more about creating a minimal Master Page, see “ How to: Create a Minimal Master Page” at. You can also download some minimal Master Pages from Heather Solomon’s blog, which is also listed in the Resources section.

Dealing with InfoPath Projects in an Automated Build

Projects created in Microsoft InfoPath Designer will further challenge your efforts to automate your build. The best you can really do is let InfoPath and SharePoint handle the packaging. See “Automate Web App Deployment with the SharePoint API” in the Resources section for details about how to get portable solution packages from InfoPath projects.

Ethan Wilansky is a director in FTI Consulting’s Technology Practice and focuses on creating custom SharePoint solutions. As a Microsoft Directory Services MVP, he concentrates on the DS programming framework and is also a member of the Office Developer Advisory Council.

Paul Olszewski is an Information Specialist on a .NET Capability team. He specializes in creating and deploying reusable component applications leveraging Microsoft technologies.

Tomek Stojecki works at Annapolis Computing where he specializes in the architecture and development of .NET apps using design patterns and agile methodologies. He has consulted on a number of SharePoint-based projects.

Stefan Kowalewski is a senior consultant on a SharePoint development team. He provides technical expertise and brings proven agile experience to custom SharePoint development efforts.

SOURCE: Microsoft Magazine