Solution and Authored Artifact Development Models for SharePoint Products and Technologies

  • Article

Summary: Learn about methodologies and strategies to reconcile differences between Microsoft SharePoint Products and Technologies artifact development and assembly development. The strategies include combining these two components into a single version control repository, such as Microsoft Visual Studio 2008 Team Foundation Server. (12 printed pages)

Kurt Allebach, Microsoft Corporation

Eric Charran, Microsoft Corporation

Yvonne Harryman, Microsoft Corporation

Gence Soysal, Microsoft Corporation

David Chesnut, Microsoft Corporation

April 2009

Applies to: Microsoft Visual Studio 2008 Team Foundation Server, Microsoft Office SharePoint Server 2007, Windows SharePoint Services 3.0

Contents

  • Understanding Differences Between Solution and Authored Artifact Development

  • Anatomy of a Custom SharePoint Application

  • Developing Authored Artifacts with Office SharePoint Server 2007

  • Applying ALM to Authored Artifacts and Assemblies in SharePoint Server

  • SharePoint Server and Team Foundation Server Version Control Capabilities 

  • Choosing a Team Model

  • The Mixed Development Team Model

  • The Dedicated Visual Studio Development Team Model

  • Sample Scenarios for Team Models

  • Conclusion

  • Additional Resources

Understanding Differences Between Solution and Authored Artifact Development

Application development for Microsoft SharePoint Products and Technologies (which include Microsoft Office SharePoint Server 2007 and Windows SharePoint Services 3.0) ranges from customizing site templates to creating complex applications involving assemblies and customized content. This article discusses methodologies and strategies that you can use to reconcile the differences between solution artifact development and assembly artifact development. The strategies include combining these two components into a single version control repository such as Microsoft Visual Studio 2008 Team Foundation Server. This article also discusses team models and how developers can organize themselves to ensure that all artifacts and assembly components of a custom SharePoint Products and Technologies application are packaged as a single unit for deployment to a server farm.

Organizations are very interested in building software applications based on SharePoint Products and Technologies because they offer a foundational set of capabilities to developers while helping solve many typical custom application needs. As applications based on SharePoint Products and Technologies grow in number and popularity, teams are challenged to develop larger, and in some cases critical, line-of-business (LOB) SharePoint applications. Building these types of applications requires teams to follow a defined application development life cycle to design, create, and successfully deploy applications on servers running Office SharePoint Server 2007 or Windows SharePoint Services 3.0.

Development teams must understand how to approach a development initiative for the SharePoint platform. You can apply many of the current application lifecycle management (ALM) practices, methodologies, and patterns to SharePoint application development, but you also need specific knowledge about the components that are contained in an application and how they are created, controlled, versioned, and deployed.

Note

This article is part of a series about using SharePoint Products and Technologies and Team Foundation Server in your SharePoint application development. For more information about incorporating Microsoft best practices and toolsets around ALM and applying them to SharePoint development, see the Application Lifecycle Management Resource Center for SharePoint Server.

Anatomy of a Custom SharePoint Application

An application based on Office SharePoint Server 2007 or Windows SharePoint Services 3.0 consists of two core types of components: solution artifacts (which consist of anything contained in a SharePoint solution package [.wsp file], including assemblies) and authored artifacts (which contain created items in the content database). Assemblies are SharePoint components that are written in Microsoft .NET Framework–based languages and compiled before being deployed onto a server running Office SharePoint Server 2007 or Windows SharePoint Services 3.0. You can develop assemblies by using either standard or customized templates for Office SharePoint Server 2007 or Windows SharePoint Services 3.0 in the Microsoft Visual Studio 2008 development environment. These components are frequently used with traditional development practices and techniques. As an example, to develop a feature receiver, you can use the Visual Studio class library project template. The following list provides examples of components that are assemblies in an application that is based on Office SharePoint Server 2007:

  • Web Parts

  • Event handlers

  • Feature receivers

  • Workflow activities

  • Workflow templates

  • Timer jobs

  • Custom Stsadm command-line tool extensions

  • Custom Web services (using the SharePoint API)

  • Unit tests (written against a SharePoint assembly)

  • Web tests (HTTP-based tests executed against an Office SharePoint Server site)

Office SharePoint Server 2007 authored artifacts are not explicitly compiled; they reside in Office SharePoint Server 2007 content. Several artifact types can be defined, either by using an XML-based definition file (in which case they are considered solution artifacts) or from a Web browser or Microsoft Office SharePoint Designer 2007 (in which case they are considered authored artifacts). Additionally, Office SharePoint Server supports customization of solution artifacts at the site collection or site level; customizations made at these levels become authored artifacts for those sites. A best practice is to ensure that any artifact upon which your code logic depends is maintained as a solution artifact and packaged as part of a SharePoint solution package. The following artifacts can be defined as either solution artifacts or authored artifacts and used in an application based on Office SharePoint Server 2007:

  • Lists (definitions and templates)

  • Sites (definitions and templates)

  • Master pages

  • Page layouts

  • Content types

  • Cascading style sheets (CSSs)

  • ECMAScript (JScript, JavaScript) files

  • Customized Web Part definitions

Note

Office SharePoint Designer 2007 workflows can be defined only as authored artifacts. For more information about types of projects and objects that are regarded as assemblies or artifacts, see Team-Based Development in SharePoint Server 2007.

An application developed for the Office SharePoint Server 2007 platform often contains artifacts developed by using a Web browser (Internet Explorer), Office SharePoint Designer, and Visual Studio. Visual Studio is the primary tool for building assemblies; however, an application based on Office SharePoint Server 2007 may contain artifacts developed by any of these sources. The goal is to manage all artifacts that your application logic depends upon, regardless of originating tool, through version control and by containing them in a deployable SharePoint solution package.

Developing Authored Artifacts with Office SharePoint Server 2007

Developing authored artifacts can enable you to powerfully and quickly customize a SharePoint application that is based on Office SharePoint Server 2007. You must understand how this type of development works before you begin to develop authored artifacts. You can manage authored artifacts in two ways:

  • By using Office SharePoint Designer 2007

  • By using Internet Explorer

When used in an authoring environment, Office SharePoint Server 2007 offers many options for creating authored artifacts to enhance or customize your application. You can create authored artifacts by using the tools included in Office SharePoint Server 2007 deployed to target pilot server farms or to production server farms running Office SharePoint Server 2007. (This means that you do not need to create the customizations or new functionality in the production environment.)

Because authored artifacts reside in the content database and, from a versioning and storage point of view, are inherently part of Office SharePoint Server 2007, teams are challenged with combining them with solution artifacts developed in the development process. In addition, you need to plan how the combination and deployment of Office SharePoint Server 2007 solution artifact components and authored artifact components are moved to pilot and production environments. There are varying technical means to achieve this; however, teams must reconcile with their own organizational requirements and standards for software development. Table 1 describes concerns and considerations for development teams when they are deciding how to develop an application that runs on Office SharePoint Server 2007.

Table 1. Development concerns and considerations

Development Concern

Considerations

Will development against production violate your client or company regulatory process compliance requirements?

Because of specific policies, authoring artifacts without an authoring environment or an associated development and release method might violate rules and regulations.

Does the client or company have a mandated centralized source control repository?

If the organization mandates an organization-wide centralized source control repository for all software development, you may need to make use of the guidance given later in this article to include Office SharePoint Server 2007 authored artifacts in centralized source control outside of Office SharePoint Server 2007.

Will you need to move your development to a different environment (development, integration, or staging and production)?

Because the final application may incorporate both solution artifacts that reside in a solution package and authored artifacts that reside in the content database, you need to make specific adjustments based on the guidance given later in this article to deploy the complete application from one farm running Office SharePoint Server 2007 to another.

Applying ALM to Authored Artifacts and Assemblies in SharePoint Server

Many organizations that are in regulated industries require adherence to a software development life cycle that is well documented, regimented, and executed. Because of these conditions, a common mandate is to require a well-documented process for centralized version control. When an organization first considers application development based on Office SharePoint Server 2007, many development managers and team leads confront a natural dichotomy in creating an application. Specifically, the differences between developing advanced aspects of the application that require coding in Visual Studio (for example, creating event receivers, feature receivers, Web Parts, and other assemblies) and authoring customizations or extensions to that application in tools like Office SharePoint Designer and Internet Explorer (creating page layouts, workflows based on Office SharePoint Designer 2007, master pages, and other artifacts). This can challenge a development team with questions about when to extract an artifact that was defined by using one of the authoring tools to a file representation and manage it as a solution artifact in version control, versus when to leave an artifact in the content database and use mechanisms in Office SharePoint Server for deployment.

SharePoint Server and Team Foundation Server Version Control Capabilities 

Because Office SharePoint Server 2007 has content management and approval capability, authored artifacts are automatically versioned and have a version history. Items in a Visual Studio solution are stored in Microsoft Visual SourceSafe or in Microsoft Visual Studio Team System 2008 Team Foundation Server version control, both of which have rich version-control features. The challenge is to reconcile these capabilities and development characteristics and create a composite SharePoint application that consists of both solution and authored artifacts, while adhering to organizational governance and policies.

A key question to answer is when to use a solution artifact, versus when to use an authored artifact. A best practice is to follow a simple rule to make this decision. If your code logic depends upon the artifact, it should be a solution artifact and managed in source control. You can take advantage of the rich SharePoint design tools to author artifacts upon which your code depends, however you should extract these authored artifacts to a file-based representation and manage it as a solution artifact. Designers can distribute a SharePoint solution package as a convenient way to package and deliver file-based artifacts to developers, who then add the files to the Visual Studio project and version it in source control. Alternatively, you can choose to conduct SharePoint application development entirely within Visual Studio. Using this approach, you can always fully version and reproduce the code logic and related dependencies through the SharePoint solution package.

Note

For more information about development team environments and configuration choices, see Team-Based Development in SharePoint Server 2007.

Including Authored Artifacts in a Visual Studio Solution

Currently, the process of extracting Office SharePoint Server 2007 authored artifacts built by using Office SharePoint Designer 2007, and including them in Visual Studio solutions (and SharePoint solution packages), is a manual process.

Figure 1 and Figure 2 show the procedure to extract authored artifacts from source control.

Figure 1. Publish Selected Files command in Office SharePoint Designer 2007

Publish Selected Files command

Office SharePoint Designer 2007 enables you to export authored artifacts that are stored as part of a SharePoint site's content to the file system. As shown in Figure 1, you highlight the authored artifacts you want and use the Publish Selected Files command to begin the process of placing them on the file system.

Figure 2. Remote Web Site Properties dialog box

Remote Web Site Properties dialog box

The Remote Web Site Properties dialog box, shown in Figure 2, enables you to select a file location in which to place the authored artifacts.

Certain Office SharePoint Server 2007 authored artifacts, such as content types and site columns, are not created by using Office SharePoint Designer 2007, but instead are created from within the Web browser. Exporting these authored artifacts from Office SharePoint Designer 2007 is not possible. For these situations, there are tools available that you can point at a SharePoint site to generate the relevant XML definition files. One such tool is the Windows SharePoint Services Solution Generator (which installs with Windows SharePoint Services 3.0 Tools: Visual Studio 2005 Extensions, Version 1.1). You can point the SharePoint Solution Generator at a SharePoint site to generate the site definition files, and any list definitions and other authored artifacts. Then, you can integrate the generated files into Visual Studio development projects as you need.

The recommended method to include artifacts in a Visual Studio solution and in a SharePoint solution package is to use a module element within a feature, to wrap the artifact and specify the placement location in the target farm. Using this procedure, the authored artifact must be extracted from the SharePoint site and stored in the file system. Figure 3 shows the WSP view in Visual Studio extensions for Windows SharePoint Services of a sample Visual Studio solution that contains solution artifacts and authored artifacts. Specifically, Figure 3 shows how a single master page (CustomBlueBand.master) can be included in a .wsp file.

Figure 3. Visual Studio solution containing solution and authored artifacts

Solution containing artifacts

The following code example demonstrates a way to include the master page module that references that master page (CustomBlueBand.master). The feature (SampleSharePointApplication-Artifacts) contains a single element (SampleArtifacts). This element was created by using the Module template from the Visual Studio extensions for Windows SharePoint Services. This element contains the module specification for the master page (CustomBlueBand.master).

<?xml version="1.0" encoding="utf-8"?>
<Elements Id="90e920be-0f58-4b6e-88ae-a91d6910fb59" xmlns="https://schemas.microsoft.com/sharepoint/">
  <Module Name="SampleArtifacts" Url="_catalogs/masterpage">
    <File Path="CustomBlueBand.master" Url="CustomBlueBand.master" Type="GhostableInLibrary" />
  </Module>
</Elements>

Note

For the preceding example, the GhostableInLibraryType element specification ensures that Office SharePoint Server 2007 creates the corresponding list item in the library for the specified file.

Module Element Specification for CustomBlueBand.master

When the SharePoint solution package is built (for example, by using Visual Studio extensions for Windows SharePoint Services), it contains the module.xml file and the master page itself. The module element specification ensures that, when the solution is installed into a target Office SharePoint Server 2007 environment, the master page (CustomBlueBand.master) is placed into the master page library of the target site.

For more information about the Module feature, see the article How to: Provision a File.

Scenario: Assembly Developer Needs an Artifact from an Artifact Developer's Virtual Development Environment

In this scenario, an assembly developer is constructing a Web Part that is designed to report on the progress of an Office SharePoint Designer 2007 workflow. The workflow is created by an authored artifact developer. The solution artifact developer cannot proceed until a working copy of the workflow is available. Because the environments are separate, the authored artifact developer cannot easily use Team Foundation Server to check in the artifacts for the assembly developer to use. To solve this problem, development teams can use the following strategies.

Option: Prepare Separate Solution Packages for Authored Artifacts

In this scenario, the artifact developer can extract the workflow to the file system and check it into version control. The solution artifact developer can then get the published workflow files from version control and import them as authored artifacts into their own content database. This allows the solution artifact developer to install, upgrade, and uninstall different versions of the workflow via source controls so that development can proceed. Alternatively, other authored artifacts may be accommodated by a module feature and deployed to other developers in that way.

Figure 4. Separate targeted solution packages for authored artifacts

Separate targeted solution packages for artifacts

By using this approach, developers can quickly and easily exchange focused features outside the scope of the team's Visual Studio solution. The designer must also convert the authored artifact to be a solution artifact by extracting it to the file system and including it in the team's Visual Studio solution. This ensures that the authored artifact is included in the application's larger SharePoint solution package for farm deployment, and exposes it to centralized source control. This approach enables clear and simplified artifact installation without the assembly developer needing to understand details such as file placement within a server running Office SharePoint Server 2007.

Option: Including the Extracted Authored Artifact in the Visual Studio Solution

A second strategy calls for the artifact developer to extract the authored artifact and publish it to their file system, just as the previous method did. However, instead of including the artifact in a separate feature inside a SharePoint solution package, the artifact developer includes the item in the shared Visual Studio solution (which is version-controlled by Team Foundation Server).

Figure 5. Extracted authored artifacts in Visual Studio solution in Team Foundation Server

Extracted artifacts in Team Foundation Server

The authored artifact is accessible to solution artifact developers, who can use it for their own development process. This provides you the ability to import it directly into your (virtualized) development SharePoint site without needing to install a .wsp file. Because the team's Visual Studio solution is used to share the artifact, you always have the most recently changed version that the authored artifact developer made available to the solution.

Choosing a Team Model

The following section describes two possible development models for teams: the mixed development team model and the dedicated Visual Studio development team model.

The Mixed Development Team Model

The mixed development team model is the recommended team model for developing custom SharePoint applications. The mixed development team model describes how a development team can organize to take advantage of both authored artifacts and solution artifacts during the development process, while maintaining compliance with organizational and regulatory mandates. The goal of this recommended model is to ensure that compliance with software development life cycle mandates is maintained. In this model, the development team does not rely on Office SharePoint Server 2007 for versioning. Instead, they capture all Office SharePoint Server 2007 solution artifacts and authored artifacts, convert all authored artifacts to file-based definitions, and include the files as part of the solution artifacts maintained within a centralized version control system. Development teams can facilitate the manual task of extracting authored artifacts from Office SharePoint Server and placing them into Visual Studio solutions for check-in into Team Foundation Server version control. Figure 6 shows the process by which authored artifact developers and solution artifact developers can include their Office SharePoint Server 2007 application components into a common Visual Studio solution version control, for compilation and deployment.

Figure 6. Combined mixed team model variation for applications based on Office SharePoint Server 2007

Combined mixed team model variation

As shown in Figure 6, both designers and developers include their artifacts as solution artifacts in a common Visual Studio solution that is under Team Foundation Server version control. Artifact developers must publish the artifacts they author to the file system by using Office SharePoint Designer 2007 and then include them in the Visual Studio solution; however, assembly developers can simply conduct a standard check-in procedure in Visual Studio.

After the components for the application based on Office SharePoint Server 2007 are in a shared and version-controlled Visual Studio solution, they can either be built by team members (developers or release managers) or exposed and built by using Team Foundation Build.

Teams can use several methods to package the solution components into features enclosed in a SharePoint solution package. For example, they can use the Visual Studio extensions for Windows SharePoint Services. The resulting solution package is ready for deployment to a target Office SharePoint Server 2007 environment.

The Dedicated Visual Studio Development Team Model

In the dedicated Visual Studio development team model, Office SharePoint Designer 2007 is not used. Visual Studio is used to develop authored artifacts. Because everything is developed by using Visual Studio, you can easily store all Office SharePoint Server 2007 application items in Team Foundation Server. Visual Studio solutions integrate with the built-in version control provider, which enables any object in the solution to be stored in the version-control system.

Because Office SharePoint Designer 2007 is not used, however, you must make special accommodations for the lack of specific Office SharePoint Server 2007–based functionality in Visual Studio (for example, being able to create user-modifiable workflows by using the Office SharePoint Designer workflow designer). In the case of an Office SharePoint Designer 2007 workflow, you might choose to use Windows Workflow Foundation custom workflows.

Sample Scenarios for Team Models

Choosing which team model to use can be challenging. Many teams might need to alter their team model during the development process. For example, a team that is using the dedicated Visual Studio team model might have requirements that change, and the team might find that they need to develop authored artifacts. This can require the team to transition to the mixed development team model. The opposite scenario can also occur, in which a team using the mixed development team model no longer requires workflows based on Office SharePoint Designer, and moves to Windows Workflow Foundation instead. The following scenarios show the application of a team model based on an Office SharePoint Server 2007 application requirement.

Scenario: Organization Leadership and Management Feedback Site

In this scenario, a business requires a quick-delivery software application to be built that gathers feedback on decisions and policies and on performance, organizational management, and leadership.

The software application is an internal development initiative to gather feedback for management policies and decisions. Because it is an internal application that is not mission-critical and is not used by customers, it is not bound to regulatory compliance rules or procedures. Therefore, project leadership can adjust adherence to centralized version control and ALM policies in favor of rapid development and deployment. The application does not require high availability or extensive disaster recovery accommodations. However, the application must be recoverable in the event of a catastrophe. Following are the business requirements:

  • Use a form-based collection system to gather feedback from users.

  • Track the submission of the form's contents as the form is processed and routed.

  • Manage the content of the form to ensure that feedback is optionally anonymous.

The application architects complete physical design of the application. To meet business requirements, a publishing site template is used. The site has a forms library that contains Microsoft Office InfoPath 2007 form templates and instances for feedback. The application uses a workflow that is based on Office SharePoint Designer 2007 and that updates a custom list that tracks the forms when they are sent out for feedback, and when they are submitted from recipients. The application uses a data connection in the Office InfoPath 2007 form. The data connection sends data to secured libraries that only the managers can access. Also, the data is sent to an embedded Visual Studio Tools for Applications assembly that can optionally mask who sent the feedback.

Scenario: Vendor Purchase Order Application

In this scenario, the business requires an application to enable routed workflow and gated approval for employee purchases.

The purchase order application should provide access to employees and enable them to submit, track, review, and manage purchase orders. The purchase order must follow a customized workflow based on rules supplied by the human resources department. The application must provide the following capabilities:

  • Collect purchase order information by using forms.

  • Enable users to save forms on their local computers, and later submit the forms to begin the purchase order approval process.

  • Archive completed purchase orders.

Using a centralized source control repository, the workflow must track identity to provide the following functionality:

  • Follow specific rules and states required for the complex approval process.

  • Suspend the workflow or update the submitter and the submitter's manager, if necessary.

  • Resume approval after suspension.

To meet these requirements, an application based on Office SharePoint Server 2007 is created. The application implements an Office InfoPath 2007 forms library to take advantage of features already present in Office SharePoint Server 2007. These features include version control, custom content types and columns, and Web Parts for customized and personalized status review. A records center based on Office SharePoint Server 2007 receives the completed purchase order forms.

To accommodate the complex workflow outlined in the specification, the development team creates a SharePoint custom workflow.

In contrast to the previous scenario, this is an example of an application based on Office SharePoint Server 2007 that includes both solution artifacts and authored artifacts. Although the previous scenario used a Visual Studio Tools for Applications code component inside the Office InfoPath 2007 form, this application has assemblies (which are integral components of the application) that are based on Office SharePoint Server 2007. The authored artifacts include content types and the site columns they are based on, the configuration and settings of the forms library, and any other appearance ("look and feel") modifications (such as page layouts for custom Web Part placement). Assembly development involves establishing the custom workflow application. To increase manageability, the development team uses a feature-based development and deployment model.

In this model, solution artifacts and authored artifacts are deployed as itemized features. The application is deployed via a SharePoint solution package to target farms.

Option: Dedicated Visual Studio Development

A dedicated Visual Studio development team model meets the centralized source control requirement. In this team model, the development team can choose to use the Office SharePoint Server 2007 API to create and provision form and document libraries, content types, and other authored artifacts within feature receiver code. In this team model, a prototype site is not used and the feature receiver code can act on an existing or newly provisioned SharePoint site. On feature activation, the team site is modified when the feature activation code runs. Features that install the workflow and bind it to dependent libraries also run. In this way, all development uses only Visual Studio.

Conclusion

Office SharePoint Designer 2007 has powerful features that offer the most productivity for authoring artifacts for a solution, and the resulting artifacts are often converted to solution artifacts and bundled into a solution together with assemblies. The challenge facing development teams is to adhere to ALM policies and procedures that govern existing software development when developing a solution. Because authored artifact development is often done outside of Visual Studio, incorporating authored artifacts into enterprise source control must be planned.

Organizations should select a defined team model before developing applications based on SharePoint Products and Technologies. The team models discussed in this article assist in organizing a development effort that is aligned with regulatory and software development life cycle mandates. The mixed development team model, the dedicated Visual Studio team model, and the variations on these team models provide ways to conduct application development and preserve the interests and policies of your organization.

The guidance for developing applications based on Office SharePoint Server 2007 with enterprise version control is to extract authored artifacts from Office SharePoint Server 2007 and include them in Visual Studio solutions as solution artifacts. After they are combined with the assembly-based projects in the Visual Studio solution, you can check them into enterprise source control. The check-in and check-out process is manually enforced for these authored artifacts because the primary tool for editing them, Office SharePoint Designer 2007, is not directly integrated into Team Foundation Server. Authored artifact designers must control changes by using their own development environment based on Office SharePoint Server 2007, and then extracting the changes and including them in a newer version in the team Visual Studio solution.

Visual Studio extensions for Windows SharePoint Services is an important tool that facilitates team-based SharePoint development. This add-on to Visual Studio provides project templates and item templates for several Office SharePoint Server 2007 pieces and enables one-touch (F5 key) deployment on local development environments. A Visual Studio container consisting of multiple projects that use this add-on can act as a logical container within which to perform team-based development by using Office SharePoint Server 2007, particularly if you write an MSBuild script to allow the centralized packaging and deployment of the solution. To download the extensions and the extensive user guide, see the following links:

Additional Resources

This article is part of a series about using SharePoint Products and Technologies and Team Foundation Server in your SharePoint application development. For more information about incorporating Microsoft best practices and toolsets around ALM and applying them to SharePoint development, see the Application Lifecycle Management Resource Center for SharePoint Server.

For more information about SharePoint Products and Technologies, see the following resources: