Migrating Business Connectivity Services External Content Types in SharePoint 2010

Article
10/20/2016

Summary: Learn how to migrate Business Connectivity Services external content types from a development environment to testing environments and production environments in Microsoft SharePoint 2010. Techniques are presented for migrating external content types that are created by using Microsoft SharePoint Designer 2010 and Microsoft Visual Studio 2010.

Provided by: Scot Hillier, Microsoft SharePoint MVP, Scot Hillier Technical Solutions, LLC | About the Author

Contents

Introduction to External Content Types in Business Connectivity Services
Migrating External Content Types Created Using SharePoint Designer 2010
Migrating External Content Types Created Using Visual Studio 2010
Conclusion
Additional Resources
About the Author

Introduction to External Content Types in Business Connectivity Services

Microsoft Business Connectivity Services (BCS) is a set of technologies that brings data from external systems into Microsoft SharePoint Foundation 2010, Microsoft SharePoint Server 2010, and Microsoft Office 2010. The operations and schema for the data that is returned from an external system is defined by an external content type. An external content type contains an entity definition that specifies the fields that should be returned from an external system, such as CustomerID, FirstName, and LastName fields from a Customer Relationship Management (CRM) system. Additionally, an external content type defines the operations that can be performed on a system, such as create, read, update, delete, and query. Defining external content types is one of the primary activities involved in creating a Business Connectivity Services solution, and it can be performed in either Microsoft SharePoint Designer 2010 or Microsoft Visual Studio 2010. After external content types are created, they can be used as the basis for displaying data in external lists, external data Web Parts, enterprise search results, external data columns, Microsoft Office client applications, and custom solutions.

External content types are defined through XML files known as BDC metadata models. Both SharePoint Designer 2010 and Visual Studio 2010 have tools for creating BDC metadata models. BDC metadata models define a set of elements that include not only the external content type, but also the external system. After they are created, BDC metadata models are stored in the Metadata Store that is associated with a Business Data Connectivity (BDC) service application. BDC service application administration is done through the Central Administration site. The following code shows the general structure of the BDC metadata model with the external system defined in the LobSystemInstance element and the external content type defined in the Entity element.

<Model xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="https://schemas.microsoft.com/.../BDCMetadata.xsd"
 xmlns="https://schemas.microsoft.com/windows/2007/BusinessDataCatalog"
 Name="My Model">
  <LobSystems>
    <LobSystem>
      <LobSystemInstances>
        <LobSystemInstance/>
      </LobSystemInstances>
      <Entities>
        <Entity Name="MyEntity" 
                DefaultDisplayName="My Entity" 
                Namespace="http://mynamespace"
                Version="1.0.0.0"
                EstimatedInstanceCount="10000" >
          <Methods>
          </Methods>
        </Entity>
      </Entities>
    </LobSystem>
  </LobSystems>
</Model>

External content types are generally designed and created in controlled development environments. This enables you to test the external content type before you deploy a Business Connectivity Services solution to production. As part of their development life cycle, external content types must be migrated from the development environment to a testing environment or production environment. This article presents techniques for migrating external content types between environments and managing environmental settings.

Migrating External Content Types Created Using SharePoint Designer 2010

SharePoint Designer 2010 simplifies creating external content types and associated solutions. By using SharePoint Designer 2010, developers can connect to external systems, specify data to return, and define operations to perform. The BDC metadata models that are created in SharePoint Designer 2010 are stored in the Metadata Store of the associated BDC service application, but they are also shown in the SharePoint Designer 2010 user interface when the external content types object is selected. Figure 1 shows external content types displayed in SharePoint Designer 2010.

Figure 1. External content types in SharePoint Designer 2010

External content types in SharePoint Designer

When external content types are defined against external systems in SharePoint Designer 2010, different authentication mechanisms may be defined for connections made on the server running SharePoint Server 2010 and connections made through an Office 2010 client application. For example, the server running SharePoint Server may use credential mapping with the Secure Store Service, whereas Microsoft Outlook 2010 uses the credentials of the current user. You can specify these settings in connection dialog boxes that are associated with the external system, as shown in Figure 2.

Figure 2. Specifying connection properties

Specifying connection properties

Manually Migrating External Content Types Created Using SharePoint Designer 2010

The basic strategy for manually migrating external content types that are created in SharePoint Designer 2010 is to export the BDC metadata model from one environment and import it into another environment, while allowing for changes in configuration settings, such as connection strings, Secure Store Service settings, and permissions. This approach initially appears straightforward, but external content types that are created in SharePoint Designer 2010 present some special challenges.

When you export external content types, the ideal approach is to export the entire BDC metadata model from the BDC service application. To support this approach, the BDC service application has an export facility. A BDC metadata model can be selected and exported, as shown in Figure 3. Notice that it is not possible to export an external content type directly from the BDC service application; you can export only complete BDC metadata models.

Figure 3. Exporting a BDC metadata model from the BDC service application

Exporting a BDC metadata model

Although exporting from the BDC service application works in many situations, models that are created through SharePoint Designer cannot be exported through the BDC service application. The challenge with exporting external content types that are created in SharePoint Designer 2010 is that the tooling in SharePoint Designer 2010 does not create complete BDC metadata models. Instead, it saves the external content type definition in the BDC service application without an associated BDC metadata model. This can be proven by examining an external content type created by SharePoint Designer 2010 in the BDC service application. Figure 4 shows the definition of such an external content type, and the information about the associated model is clearly missing.

Figure 4. External content types created in SharePoint Designer have no associated BDC metadata model

No associated BDC metadata model

Because the external content types that are created by SharePoint Designer 2010 do not have an associated BDC metadata model, they cannot be exported from the BDC service application. Instead, they must be exported directly from SharePoint Designer 2010. To export external content types from SharePoint Designer 2010, select one or more in the list of external content types, and then click Export BDC Model on the Server ribbon. When the external content type is exported, you can choose to include either the default (server) or client connection information, and SharePoint Designer 2010 exports a complete BDC metadata model as a file that has a .bdcm extension. If you are migrating external content types, you should export only the default model because the client will be configured after import.

After the default BDC metadata model is exported, you can import it into the target environment by using the BDC service application. Because the export process from SharePoint Designer 2010 creates a complete BDC metadata model, you can import this file without modification by clicking Import in the BDC service application for the target environment.

When importing the BDC metadata model, you have the option of importing Localized Names, Properties, and Permissions. By default, Localized Names and Properties are selected. This is the correct setting if the target environment will have different permissions from the development environment. After successfully importing the BDC metadata model, you can set the permissions for the model in the target BDC service application.

After setting permissions, you can modify the connection settings by opening the external content type in SharePoint Designer 2010. Opening the Connection Properties dialog box in SharePoint Designer 2010 enables you to set the connection properties for the default and client models. Initially, both sets of settings will reflect the values of the development environment from which the model was exported. However, you can easily change these settings to match the new environment. After you modify the settings, you can create external lists against the external content types.

Improving the Migration Process for External Content Types by Using Resource Files

An interesting benefit of migrating external content types manually is that the process results in a complete BDC metadata model being deployed to the target BDC service application. When a complete model is available in the BDC service application, it can be split into a resource file and a model file. Resource files enable you to separate model information from configuration information, which makes it simpler to migrate external content types.

When exporting from the BDC service application, you can select to export a model file or a resource file. You can then select which file to include localized names, properties, and permissions for. If you want more granular control over the contents of the model and resource files, you can manually edit them in Visual Studio 2010.

After creating a resource file, you can edit the file for a new target environment. This enables you to have configuration settings specific to an environment. When you import resource and model files, they are merged to form the complete BDC metadata model. Subsequent versions of external content types do not have to contain the configuration information found in the resource files, which makes it easier to migrate changes between environments.

Scripting External Content Type Migration

Whenever you are using complete BDC metadata models, you can use Windows PowerShell commands to script the export and import process. You can also set values for the configuration properties in the model stored in the BDC service application. Table 1 details the available Windows PowerShell commands.

Table 1. Windows PowerShell commands for migrating external content types

Command	Description
Copy-SPBusinessDataCatalogAclToChildren	Copies a set of permissions from a BDC metadata object to its child objects.
Set-SPBusinessDataCatalogMetadataObject	Sets the value of a property or attribute of a BDC metadata object.
Grant-SPBusinessDataCatalogMetadataObject	Grants a right for the specified BDC metadata object.
Revoke-SPBusinessDataCatalogMetadataObject	Revokes a right for the specified BDC metadata object.
Export-SPBusinessDataCatalogModel	Exports a BDC metadata model from the BDC service application.
Import-SPBusinessDataCatalogModel	Imports a BDC metadata model into the BDC service application.
Remove-SPBusinessDataCatalogModel	Deletes a BDC metadata model from the BDC service application.

Packaging External Content Types for Migration

Although the process for migrating external content types that are created in SharePoint Designer 2010 is mostly manual, you can make the process simpler by packaging the external content types in a SharePoint Feature. You can do this by creating an empty SharePoint project in Visual Studio 2010 and adding a complete BDC metadata model to the project. However, to take this approach, you must merge all the external content types into a complete BDC metadata model.

Although creating a SharePoint Feature can make model deployment simpler, there are still some challenges with this approach. First, the Visual Studio 2010 tooling does not function for external content types that are created in SharePoint Designer 2010. Generally, this is not a problem because the feature is being used only to deploy the model. Second, there are environmental-specific settings in Visual Studio that must be adjusted before deployment. This second challenge is outlined in the next section.

Migrating External Content Types Created Using Visual Studio 2010

Visual Studio 2010 provides advanced tools for creating external content types as part of a BDC metadata model. Generally when external content types are created in Visual Studio 2010, they are created as part of a Business Data Connectivity Model project. This project type provides tools, packaging, and deployment as a SharePoint Feature. Figure 5 shows a sample project in Visual Studio 2010 with the design tools visible in windows.

Figure 5. Visual Studio tools for creating BDC metadata models

Tools for creating BDC metadata models

BDC metadata models that are created as part of a Business Data Connectivity Model project are packaged into solution (.wsp) files and may be deployed directly to a SharePoint environment. However, this process is bound to a specific environment through the values in the BDC metadata model and the SharePoint Feature that contains the model.

The first challenge in migrating a Business Data Connectivity Model project is that the project makes no allowance for separating the configuration properties into resource files. This means that configuration values, such as connection strings, are generally placed directly in the BDC metadata model. To overcome this problem, you can either create a separate resource file or change the configuration values after deployment.

You can create a separate resource file in the development environment by exporting it from the BDC service application. Unlike external content types that are created in SharePoint Designer 2010, the Business Data Connectivity Model project always creates a complete BDC metadata model. This means that you can easily export resource files from the BDC service application. You can then update these resource files for the target environment and import them separately from the feature installation.

Or, you can install the Business Data Connectivity Model feature into the target environment and change the configuration values. For example, you can edit the connection properties for the model in the BDC service application, as shown in Figure 6.

Figure 6. Editing connection properties in the BDC service application

Editing connection properties

The bigger challenge with the Business Data Connectivity Model project is that it uses a SiteUrl property in the Feature.xml file to help establish a connection to the target BDC service application. The SiteUrl property is used to identify the BDC service application where the BDC metadata model should be deployed. The SiteUrl property is not present by default in the Business Data Connectivity Model project. When the property is not present, the deployment assumes a value for the property of https://localhost:80. This means that the BDC metadata model will be deployed to the BDC service application associated with the site that is located at https://localhost:80. However, if no site exists at https://localhost:80, the deployment will fail. In this case, you must explicitly set the SiteUrl value to reference a site that is associated with the correct BDC service application. If the SiteUrl property must be explicitly set in the Feature, you must create an environment-specific package to successfully deploy the solution.

You can review and modify the Feature properties directly in Visual Studio 2010. First, in Solution Explorer, select the BDC metadata model project. Then, in the Properties window, select Feature Properties, which opens a dialog box. Set the property values in the Feature Properties dialog box, as shown in Figure 7.

Figure 7. Setting the SiteUrl property

Setting the SiteURL property

Conclusion

Migrating external content types from a development environment to a testing environment or production environment is done differently depending on whether the external content types were created in SharePoint Designer 2010 or in Visual Studio 2010. As described in this article, you must perform several manual steps to support the migration. The requirement for manual steps prevents you from creating a single deployment package that works in all environments.

Additional Resources

For more information, see the following resources:

About the Author

Scot Hillier is an independent consultant and Microsoft SharePoint Most Valuable Professional (MVP) focused on creating solutions for Information Workers with SharePoint, Office, and related .NET Framework technologies. He is the author/coauthor of 15 books and DVDs on Microsoft technologies, including Inside Microsoft SharePoint 2010 and Professional Business Connectivity Services. Scot splits his time between consulting on SharePoint projects, speaking at SharePoint events like Tech-Ed, and delivering training for SharePoint developers. Scot is a former U.S. Navy submarine officer and graduate of the Virginia Military Institute. Scot can be reached at scot@shillier.com.