Building Upgradable Solutions for Duet Enterprise

Building upgradable Duet Enterprise for Microsoft SharePoint and SAP solutions requires you to do some planning in advance. Best practice is to create artifacts instead of modifying existing artifacts.

Applies to: Duet Enterprise for Microsoft SharePoint and SAP Server 2.0 | Office 2010 | SharePoint Server 2010

In this article
Creating Upgradable Site Definitions for Duet Enterprise
Upgrading Originally Installed Files for Duet Enterprise
Using Features in Solutions to Simplify Upgrading for Duet Enterprise
Upgrading Artifacts in a Feature for Duet Enterprise
Conclusion

Building upgradable Duet Enterprise for Microsoft SharePoint and SAP solutions requires you to do some planning in advance, especially for site definitions and the architecture of your solutions. In general, the best practice is to create new artifacts instead of modifying existing artifacts. If you must modify existing artifacts, you should carefully document the customizations that you made so that you can re-create them after the upgrade.

Creating Upgradable Site Definitions for Duet Enterprise

Always work from a custom site definition, instead of from an originally installed site definition, to make changes. If you work from files within a copied, uniquely named site definition directory, your customizations will not be overwritten when software updates, upgrades, or security updates are applied to the deployment, and your custom code will remain reusable. However, if you make changes to a default site definition, your changes will be overwritten by the new site definition installed through software updates, upgrades, or security updates.

For more information, see the following:

Upgrading Originally Installed Files for Duet Enterprise

To perform certain programming tasks described in the SharePoint 2010 SDK such as updating the docicon.xml and web.config files, you have to modify original files in the setup directory. (For more information about these kinds of customizations, see Understanding DocIcon.xml Files (https://msdn.microsoft.com/en-us/library/ms463701.aspx) and Working with Web.config Files (https://msdn.microsoft.com/en-us/library/ms460914.aspx)). Originally installed files are overwritten during an upgrade, so customizations you make to these files are lost. However, if you always save copies of original files that you customized, you can transfer your code into the copied files after the update or upgrade is complete. Depending on the specific changes implemented in an update, you might not be able to simply replace the originally installed files; you might have to merge your changes into the updated product files. Therefore, the best practice is to keep detailed notes about specific changes you make to these files, so that, if they are replaced during an update, you can more easily merge changes.

Using Features in Solutions to Simplify Upgrading for Duet Enterprise

You can make your solutions easier to upgrade by using SharePoint Features. Features provide versioning capabilities and a public object model that enable you to upgrade Features that you have customized through declarative upgrade actions.

For more information, see the following:

Upgrading Artifacts in a Feature for Duet Enterprise

Features can contain various artifacts, such as site columns, content types, Web Parts, custom actions, and list definitions. This section describes best practices for upgrading these feature artifacts in Duet Enterprise for Microsoft SharePoint and SAP solutions. For a summary of upgrade actions that you can add to a feature.xml file, see Feature.xml Changes (https://msdn.microsoft.com/en-us/library/ee537575.aspx).

Upgrading Site Columns for Duet Enterprise

When you install a Feature for the first time, provision new site columns by adding new field definitions to the Feature's manifest file. When you upgrade a Feature, add a new site column by using the <AddContentTypeField> section in the <UpgradeActions> section of the feature.xml file. Do not remove site columns from a Feature's manifest file because this can cause list items that use the site columns to break. For an example of an <AddContentTypeField> section, see Feature.xml Changes (https://msdn.microsoft.com/en-us/library/ee537575.aspx).

Upgrading Content Types for Duet Enterprise

Use the object model to add new fields to a content type, because this can help lessen the risk of inadvertently removing customizations to the content type that are stored in the content database.

Do not remove fields or update field types. Use the following recommended alternatives:

  • Instead of removing fields, hide them.

  • Instead of updating a field type, create a new field and hide the existing field that the new field will replace.

For more information about customizing content types, see Updating Content Types (https://msdn.microsoft.com/en-us/library/aa543504.aspx) and Updating Child Content Types (https://msdn.microsoft.com/en-us/library/ms442695.aspx).

Upgrading Web Parts for Duet Enterprise

When you upgrade a Web Part by upgrading the assembly that contains the Web Part code, it is best not to increase the version number of that assembly. When you increase the version number of the assembly, older provisioned Web Parts will not work after you upgrade your solution unless your solution contains a policy redirection assembly. The new assembly that contains the Web Part code must also be backward-compatible so that it can handle calls from older provisioned Web Parts.

For more information, see the following:

Upgrading Custom Actions for Duet Enterprise

When you upgrade an existing custom action, do not change the Id attribute of the CustomAction element. To remove a custom action, add a HideCustomAction element to the Feature's element manifest file. For more information about working with CustomAction elements, see the Custom Action Definition Schema (https://msdn.microsoft.com/en-us/library/ms465980.aspx).

Upgrading List Definitions for Duet Enterprise

You can include new fields and other upgrades to a list definition by changing the schema.xml file in the Feature that contains the list definition. Removing fields or modifying fields in the schema.xml file is not recommended. Best practice is to create new fields to replace the fields that you want to remove or modify.

For more information, see the following:

Conclusion

You can help ensure that your upgrades will work with little difficulty if you take full advantage of Features. The upgrade actions and versioning capabilities of Features provide elegant ways to replace artifacts and to update the functionality in solutions. You can more easily upgrade Web Parts either by updating the code in the assembly that contains the Web Part code and not changing the assembly version number, or by implementing assembly redirects with publisher policies. You can make your solution upgrades work well if you plan your solution architecture with upgrades in mind and follow the best practices for upgrading Features that are described in this topic.

See Also

Other Resources

Best Practices with SharePoint Foundation (https://msdn.microsoft.com/en-us/library/ee556427(office.14).aspx)

Best Practices with SharePoint Server (https://msdn.microsoft.com/en-us/library/ee705809.aspx)

Microsoft Business Connectivity Services (https://msdn.microsoft.com/en-us/library/ee556826.aspx)