How to: Manually Upgrade Business Data Catalog Application Definitions to Business Data Connectivity Models
Applies to: SharePoint Server 2010
In this article
Manually Upgrading the Business Data Catalog Application Definition File
Next Steps
Special Cases and Conditions When Upgrading Business Data Catalog Application Definition Files
Business Data Connectivity (BDC) service, which is part of Microsoft SharePoint Foundation 2010, is the successor of the Business Data Catalog, which is part of Microsoft Office SharePoint Server 2007. Both BDC and the Business Data Catalog use metadata to describe APIs and semantics of external systems. Applications can use the metadata to invoke operations on an external system through a common interface. This interface is independent of the technology that is used to expose the external system APIs, such as databases or SOAP-based web services. When you perform an in-place upgrade from Office SharePoint Server 2007 to Microsoft SharePoint Server 2010, an automatic upgrade process will start to upgrade your metadata so that it becomes usable with the Business Data Connectivity (BDC) service. However, if you choose other upgrade mechanisms, or if you have metadata that is stored as an XML file instead of in the Business Data Catalog, you have the following two options to be able to use your external data:
Upgrade your metadata files manually.
Rediscover your external systems via Microsoft SharePoint Designer 2010.
If you have simple external systems, you should select the second option. If you have custom properties and other simple modifications, you can upgrade them after creating a model from SharePoint Designer 2010. SharePoint Designer will guide you through the process. However, using SharePoint Designer is not always an option, especially if the existing metadata contains methods that are not supported by SharePoint Designer, or that are built on databases or web services that do not expose schema information that SharePoint Designer requires.
This topic shows how to perform a manual upgrade of your Business Data Catalog application definition XML files to Business Data Connectivity model XML files. Be aware that performing an automatic upgrade through the in-place upgrade option is the recommended option to upgrade the metadata. For more information about the different upgrade scenarios, see Plan to Upgrade to Business Connectivity Services (SharePoint Server 2010). However, the in-place upgrade path may not be an option in some cases, Therefore, this topic provides the steps to manually upgrade XML files. These steps require a basic knowledge of XML and the Business Data Connectivity model schema. For more information about the Business Data Connectivity model schema, see BDCMetadata Schema.
Manually Upgrading the Business Data Catalog Application Definition File
Use the following procedure to perform a manual upgrade.
To manually upgrade the Business Data Catalog application definition file
Obtain a full-featured XML editor, such as Microsoft Visual Studio 2010.
All of the following steps require you to edit XML files. The Business Data Connectivity metadata schema has built-in most of the referential integrity validations that are required. Performing the modifications by using a good XML editor with a schema validator, such as the XML editing capability in Microsoft Visual Studio, provides a smoother upgrade experience. Syntax help (IntelliSense in Visual Studio) and auto completion can also be beneficial.
To show the changes, the following steps contain examples that show the state of the XML before and after the suggested changes are applied to the XML. The parts that have been removed, added, or changed are marked in bold font.
Add the root element, <Model>.
In the Business Data Catalog, application definition files start with the <LobSystem> element, with the namespace of https://schemas.microsoft.com/office/2006/03/BusinessDataCatalog. In Business Data Connectivity, model files start with a <Model> element, with the namespace of https://schemas.microsoft.com/windows/2007/BusinessDataCatalog. The steps to upgrade the application definition file are the following:
Add the <Model> start tag. You can set the name attribute to anything that you want, but the upgrade process will be easier if you name your model the same as <Lobsystem>.
Add the <LobSystems> start tag.
Add the </LobSystems> end tag.
Add the </Model> end tag.
Remove the namespace attributes from the <LobSystem> element.
Example 1. The application definition file before the change
<?xml version="1.0" encoding="utf-8" standalone="yes" ?> <LobSystem xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="https://schemas.microsoft.com/office/2006/03/BusinessDataCatalog BDCMetadata.xsd" Type="Database" Version="1.0.0.0" Name="AdventureWorksSample" xmlns="https://schemas.microsoft.com/office/2006/03/BusinessDataCatalog"> <!-- Omitted --> </LobSystem>Example 2. The following XML example shows how the file will look after you have performed the modifications outlined in step 2
<?xml version="1.0" encoding="utf-8" standalone="yes" ?> <Modelxmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns="https://schemas.microsoft.com/windows/2007/BusinessDataCatalog"xsi:schemaLocation="https://schemas.microsoft.com/windows/2007/BusinessDataCatalog https://schemas.microsoft.com/windows/2007/BusinessDataCatalog/BDCMetadata.xsd"Name="Adventure Works Sample"><LobSystems> <LobSystem Type="Database" Version="1.0.0.0" Name="AdventureWorksSample"> <!-- Omitted --> </LobSystem> </LobSystems></Model>
Update the <LobSystem> element and the <LobSystemInstance> element.
If you are using a capable XML editor, you have probably already been notified about the mismatches of the XML with the schema; for example, the <LobSystem> element no longer has an attribute called Version. Versions are now tracked for entities (external content types) instead. Most of the attributes around LobSystem elements and LobSystemInstance elements are also updated. The steps to upgrade <LobSystem> elements and <LobSystemInstance> elements are as follows:
Remove the Version attribute from the <LobSystem> element.
Check whether you have a SystemUtility attribute on the <LobSystem> element:
If you do not have this attribute, proceed to the next step.
If you do have this attribute, see the Fixing System Type section later in this topic.
Change the types for the properties using the following table.
Table 1. Type names
Type to Find
Replace Type With
Microsoft.Office.Server.ApplicationRegistry.SystemSpecific.WebService.HttpAuthenticationMode
System.String
Microsoft.Office.Server.ApplicationRegistry.SystemSpecific.Db.DbAuthenticationMode
System.String
Microsoft.Office.Server.ApplicationRegistry.SystemSpecific.Db.DbAccessProvider
System.String
If you use SSO, update the SSO provider name Microsoft.SharePoint.Portal.SingleSignon.SpsSsoProvider, Microsoft.SharePoint.Portal.SingleSignon, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c to Microsoft.Office.SecureStoreService.Server.SecureStoreProvider, Microsoft.Office.SecureStoreService, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c.
Example 3. The application definition file before the change
<LobSystem Type="Database" Version="1.0.0.0" Name="AdventureWorksSample"> <Properties> <Property Name="WildcardCharacter" Type="System.String">%</Property> </Properties> <LobSystemInstances> <LobSystemInstance Name="AdventureWorksInstance"> <Properties> <Property Name="AuthenticationMode" Type="Microsoft.Office.Server.ApplicationRegistry.SystemSpecific.Db.DbAuthenticationMode"> WindowsCredentials</Property> <Property Name="DatabaseAccessProvider" Type= "Microsoft.Office.Server.ApplicationRegistry.SystemSpecific.Db.DbAccessProvider"> SqlServer</Property> <Property Name="RdbConnection Data Source" Type="System.String"> EnterYourAdventureWorksDW2005ServerNameHere</Property> <Property Name="RdbConnection Initial Catalog" Type="System.String"> AdventureWorksDW</Property> <Property Name="RdbConnection Integrated Security" Type="System.String"> SSPI</Property> <Property Name="RdbConnection Pooling" Type="System.String"> false</Property> <Property Name="SsoApplicationId" Type="System.String"> AdventureWorks2000</Property> <Property Name="SsoProviderImplementation" Type="System.String"> Microsoft.SharePoint.Portal.SingleSignon.SpsSsoProvider, Microsoft.SharePoint.Portal.SingleSignon,Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c</Property> </Properties> </LobSystemInstance> </LobSystemInstances>Example 4. The following XML example shows how the file will look after you have performed the modifications outlined in step 3
<LobSystem Type="Database" Name="AdventureWorksSample"> <Properties> <Property Name="WildcardCharacter" Type="System.String">%</Property> </Properties> <LobSystemInstances> <LobSystemInstance Name="AdventureWorksDWInstance"> <Properties> <Property Name="AuthenticationMode" Type="System.String"> WindowsCredentials</Property> <Property Name="DatabaseAccessProvider" Type="System.String"> SqlServer</Property> <Property Name="RdbConnection Data Source" Type="System.String"> EnterYourAdventureWorksDW2005ServerNameHere</Property> <Property Name="RdbConnection Initial Catalog" Type="System.String"> AdventureWorksDW</Property> <Property Name="RdbConnection Integrated Security" Type="System.String"> SSPI</Property> <Property Name="RdbConnection Pooling" Type="System.String"> false</Property> <Property Name="SsoApplicationId" Type="System.String"> AdventureWorks2000</Property> <Property Name="SsoProviderImplementation" Type="System.String"> Microsoft.Office.SecureStoreService.Server.SecureStoreProvider,Microsoft.Office.SecureStoreService, Version=14.0.0.0, Culture=neutral,PublicKeyToken=71e9bce111e9429c</Property> </Properties> </LobSystemInstance> </LobSystemInstances>
Update the <Entity> element and the <Identifiers> element.
You must make two important changes to the <Entity> element: Add the namespace and version. The following steps show how to update <Entity> and <Identifiers>:
Add a Namespace attribute to the <Entity> element. You can choose any namespace, based on your needs and categorization.
Add a Version attribute to the <Entity> element. You can use any value for version. However, using the version value from the <LobSystem> element (which was removed in step 2) can simplify maintenance.
Check whether any <Identifier> elements contain an assembly name in their TypeName attributes, such as System.String, mscorlib. If so, remove the assembly names (for example, mscorlib …).
Example 5. The application definition file before the change
<Entity EstimatedInstanceCount="10000" Name="Product"> <Properties> <Property Name="Title" Type="System.String">Name</Property> </Properties> <Identifiers> <Identifier Name="ProductID" TypeName="System.Int32" /> </Identifiers>Example 6. The following XML example shows how the file will look after you have performed the modifications outlined in step 4
<Entity EstimatedInstanceCount="10000" Name="Product" Namespace="AdventureWorks" Version="2.0.0.0"> <Properties> <Property Name="Title" Type="System.String">Name</Property> </Properties> <Identifiers> <Identifier Name="ProductID" TypeName="System.Int32" /> </Identifiers>
Update methods and filters.
Methods and filters in the Business Data Catalog are compatible with Business Data Connectivity. Even though much new functionality is added, and new filter types are introduced, the XML that is used for the Business Data Catalog is valid for Business Data Connectivity. The only exception is FilterDescriptors with type UserProfile. These require adding a property with Name UserProfileProvider, Type System.String, and value Microsoft.Office.SharePoint.ClientExtensions.UserProfileProvider, Microsoft.Office.SharePoint.ClientExtensions, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c.
Example 7. The application definition file before the change
<FilterDescriptor Type="UserProfile" Name="CurrentUser"> <Properties> <Property Name="UserProfilePropertyName" Type="System.String">UserName</Property> </Properties> </FilterDescriptor>Example 8. The following XML example shows how the file will look after you have performed the modifications outlined in step 5
<FilterDescriptor Type="UserProfile" Name="CurrentUser"> <Properties> <Property Name="UserProfilePropertyName" Type="System.String">UserName</Property> <Property Name="UserProfileProvider" Type="System.String">Microsoft.Office.SharePoint.ClientExtensions.UserProfileProvider,Microsoft.Office.SharePoint.ClientExtensions, Version=14.0.0.0,Culture=neutral, PublicKeyToken=71e9bce111e9429c</Property> </Properties> </FilterDescriptor>Update the <MethodInstance> elements.
Unlike the Business Data Catalog, Business Data Connectivity allows multiple SpecificFinder methods and Finder methods. Now, you can specify one of the MethodInstances of a certain type as the default. With this improvement, the ViewAccessor stereotype was no longer necessary and has been removed. The steps to upgrade a <MethodInstance> are:
If there is a <MethodInstance> element with Type attribute value of SpecificFinde, add another attribute with name Default and value true.
If there are <MethodInstance> elements with a Type attribute value of ViewAccessor, change the value of this attribute to SpecificFinder and add another attribute with name Default and value false.
If one or more of the <MethodInstance> elements have a property with name AllowAnonymousExecute, see the Managing Anonymous Access section later in this topic.
For each SpecificFinder, identify the return TypeDescriptor based on the attributes that are present on the MethodInstance element. For more information, see the Identifying the Return TypeDescriptor section.
If the return TypeDescriptor has the IsCollection attribute set to true, the MethodInstance return TypeDescriptor should be updated to be an element of the collection.
Example 9. The application definition file before the change
<Parameter Direction="Return" Name="Products"> <TypeDescriptor TypeName="System.Data.IDataReader" IsCollection="true" Name="ProductDataReader"> <TypeDescriptors> <TypeDescriptor TypeName="System.Data.IDataRecord" Name="ProductDataRecord"> <TypeDescriptors> <TypeDescriptor TypeName="System.Int32" IdentifierName="ProductID" Name="ProductID"> … <MethodInstance Name="ProductViewAccessor" Type="ViewAccessor" ReturnParameterName="Products" /> <MethodInstance Name="ProductSpecificFinderInstance" Type="SpecificFinder" ReturnParameterName="Products" /> <Parameter Direction="Return" Name="Products"> <TypeDescriptor TypeName="System.Data.IDataReader" IsCollection="true" Name="ProductDataReader"> <TypeDescriptors> <TypeDescriptor TypeName="System.Data.IDataRecord" Name="ProductDataRecord"> <TypeDescriptors> <TypeDescriptor TypeName="System.Int32" IdentifierName="ProductID" Name="ProductID"> ... <MethodInstance Name="ProductViewAccessor" Type="ViewAccessor" ReturnParameterName="Products" /> <MethodInstance Name="ProductSpecificFinderInstance" Type="SpecificFinder" ReturnParameterName="Products" />Example 10. The following XML example shows how the file will look after you have performed the modifications outlined in step 6
<Parameter Direction="Return" Name="Products"> <TypeDescriptor TypeName= "System.Data.IDataReader, System.Data, Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" IsCollection="true" Name="ProductDataReader"> <TypeDescriptors> <TypeDescriptor TypeName= "System.Data.IDataRecord, System.Data, Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" Name="ProductDataRecord"> <TypeDescriptors> <TypeDescriptor TypeName="System.Int32" IdentifierName="ProductID" Name="ProductID"> … <MethodInstance Name="ProductViewAccessor" Type="SpecificFinder" ReturnParameterName="Products" Default="false" ReturnTypeDescriptorPath="ProductDataReader[0]"/> <MethodInstance Name="ProductSpecificFinderInstance" Type="SpecificFinder" ReturnParameterName="Products" Default="true"ReturnTypeDescriptorPath="ProductDataReader[0]"/>
Update the <Action> elements and the <ActionParameter> elements.
The ActionParameters in the Business Data Catalog were named after the TypeDescriptor names that stored Identifier values. With the introduction of dot notation in Business Data Connectivity, the action parameters now use dotted paths to the values that are placed in the URL. Identifiers can be explicitly referenced with the use of the IdOrdinal property. The steps to upgrade <Action> and <ActionParameter> are as follows:
For each <ActionParameter> that does not have a Property named IdOrdinal:
Find the TypeDescriptor with the same name that is contained by the return TypeDescriptor of the default SpecificFinder.
Replace the name of the ActionParameter with the dotted path to the TypeDescriptor from the return TypeDescriptor of the default SpecificFinder. For more information about the dotted path, see Using Dot Notation in the Business Data Connectivity (BDC) Service.
If you have a profile action, you should delete it and recreate it after you import the model, by creating a new profile page.
Example 11. The application definition file before the change
<TypeDescriptor TypeName="SampleWebServiceProxy.CustomerAddress, SampleWebService" Name="CustomerAddress" > <TypeDescriptors> <TypeDescriptor TypeName="SampleWebServiceProxy.CustomerStreet, SampleWebService" Name="Street"> <TypeDescriptors> <TypeDescriptor TypeName="System.String" Name="BlockNumber" /> <TypeDescriptor TypeName="System.String" Name="StreetName" /> </TypeDescriptors> </TypeDescriptor> <TypeDescriptor TypeName="System.String" Name="City" /> <TypeDescriptor TypeName="System.String" Name="StateProvince" /> <TypeDescriptor TypeName="System.String" Name="CountryRegion" /> <TypeDescriptor TypeName="System.String" Name="PostalCode" /> </TypeDescriptors> </TypeDescriptor> … <Action Name="Search on Bing" Position="1" IsOpenedInNewWindow="true" Url="https://www.bing.com/search?q={0}+{1},+{2},+{3}" ImageUrl=""> <ActionParameters> <ActionParameter Name="StreetName" Index="0"/> <ActionParameter Name="City" Index="1"/> <ActionParameter Name="StateProvince" Index="2"/> <ActionParameter Name="CountryRegion" Index="3"/> </ActionParameters> </Action>Example 12: The following XML example shows how the file will look after you have performed the modifications outlined in step 7
<TypeDescriptor TypeName="SampleWebServiceProxy.CustomerAddress, SampleWebService" Name="CustomerAddress" > <TypeDescriptors> <TypeDescriptor TypeName="SampleWebServiceProxy.CustomerStreet, SampleWebService" Name="Street"> <TypeDescriptors> <TypeDescriptor TypeName="System.String" Name="BlockNumber" /> <TypeDescriptor TypeName="System.String" Name="StreetName" /> </TypeDescriptors> </TypeDescriptor> <TypeDescriptor TypeName="System.String" Name="City" /> <TypeDescriptor TypeName="System.String" Name="StateProvince" /> <TypeDescriptor TypeName="System.String" Name="CountryRegion" /> <TypeDescriptor TypeName="System.String" Name="PostalCode" /> </TypeDescriptors> </TypeDescriptor> … <Action Name="Search on Bing" Position="1" IsOpenedInNewWindow="true" Url="https://www.bing.com/search?q={0}+{1},+{2},+{3}" ImageUrl=""> <ActionParameters> <ActionParameter Name="Street.StreetName" Index="0"/> <ActionParameter Name="City" Index="1"/> <ActionParameter Name="StateProvince" Index="2"/> <ActionParameter Name="CountryRegion" Index="3"/> </ActionParameters> </Action>
Update the <Association> elements.
The representation and the functionality of associations is one of the areas that present the most difference and mismatch between the Business Data Catalog and Business Data Connectivity. In the Business Data Catalog, the association definitions were outside of <Entity> definitions. However, in Business Data Connectivity, associations are included in the <Entity> definitions with other method instances. Also, association groups are introduced to separate the concept of the relationship from the actual operations that allow traversal and modification of these relationships. The steps to upgrade <Association> elements are as follows:
For each <Association>, find the <Method> whose name is specified in the AssociationMethodName attribute of the <Association> element. In the <Entity> whose name is specified in the AssociationMethodEntityName attribute of the <Association>, do the following:
Move the <Association> element to the end of <MethodInstance> elements of this method.
Remove the AssociationMethodName and AssociationMethodEntityName attributes.
Rename the AssociationMethodReturnParameterName attribute to ReturnParameterName.
Rename the AssociationMethodReturnTypeDescriptorName attribute to ReturnTypeDescriptorName.
Rename the AssociationMethodReturnTypeDescriptorLevel attribute to ReturnTypeDescriptorLevel.
Add the Type attribute with value AssociationNavigator.
Add the Namespace attribute to the <SourceEntity> element and the <DestinationEntity> element and set their values to the namespaces of these entities that you specified earlier.
Remove the <Associations> element and all of its subelements.
Example 13: The application definition file before the change
<Method Name="GetSalesOrdersForCustomer"> <Parameters> <Parameter Direction="In" Name="@IndividualID"> <TypeDescriptor TypeName="System.Int32" IdentifierName="IndividualID" Name="IndividualID" /> </Parameter> <Parameter Direction="Return" Name="SalesOrders"> <TypeDescriptor TypeName="System.Data.IDataReader" IsCollection="true" Name="SalesOrderDataReader"> <TypeDescriptors> <TypeDescriptor TypeName="System.Data.IDataRecord" Name="SalesOrderDataRecord"> <TypeDescriptors> <TypeDescriptor TypeName="System.Int32" IdentifierEntityName="SalesOrder" IdentifierName="SalesOrderID" Name="SalesOrderID"/> <TypeDescriptor TypeName="System.DateTime" Name="OrderDate" /> <TypeDescriptor TypeName="System.Int32" Name="IndividualID" /> <TypeDescriptor TypeName="System.Decimal" Name="SubTotal" /> </TypeDescriptors> </TypeDescriptor> </TypeDescriptors> </TypeDescriptor> </Parameter> </Parameters> </Method> ... <Associations> <Association AssociationMethodEntityName="Customer"AssociationMethodName="GetSalesOrdersForCustomer"AssociationMethodReturnParameterName="SalesOrders" Name="CustomerToSalesOrder" IsCached="true"> <SourceEntity Name="Customer" /> <DestinationEntity Name="SalesOrder" /> </Association> </Associations>Example 14: The following XML example shows how the file will look after you have performed the modifications outlined in step 8
<Method Name="GetSalesOrdersForCustomer"> <Parameters> <Parameter Direction="In" Name="@IndividualID"> <TypeDescriptor TypeName="System.Int32" IdentifierName="IndividualID" Name="IndividualID" /> </Parameter> <Parameter Direction="Return" Name="SalesOrders"> <TypeDescriptor TypeName="System.Data.IDataReader" IsCollection="true" Name="SalesOrderDataReader"> <TypeDescriptors> <TypeDescriptor TypeName="System.Data.IDataRecord" Name="SalesOrderDataRecord"> <TypeDescriptors> <TypeDescriptor TypeName="System.Int32" IdentifierEntityName="SalesOrder" IdentifierName="SalesOrderID" Name="SalesOrderID"/> <TypeDescriptor TypeName="System.DateTime" Name="OrderDate" /> <TypeDescriptor TypeName="System.Int32" Name="IndividualID" /> <TypeDescriptor TypeName="System.Decimal" Name="SubTotal" /> </TypeDescriptors> </TypeDescriptor> </TypeDescriptors> </TypeDescriptor> </Parameter> </Parameters> <MethodInstances> <Association Type="AssociationNavigator" ReturnParameterName="SalesOrders" Name="CustomerToSalesOrder" IsCached="true"> <SourceEntity Name="Customer" Namespace="AdventureWorks" /> <DestinationEntity Name="SalesOrder" Namespace="AdventureWorks" /> </Association> </MethodInstances> </Method>
Update the <Parameter> and <TypeDescriptor> elements.
Parameters and TypeDescriptors in the Business Data Catalog are mostly compatible with the Parameters and TypeDescriptors in Business Data Connectivity. The main incompatibility is the foreign identifier specifications on TypeDescriptors. When a <TypeDescriptor> represents the value for an identifier of an <Entity> that is different from the one that contains the <TypeDescriptor>, the Business Data Catalog requires only the name of the <Entity> to identify the ownership of the identifier. However, Business Data Connectivity requires information about the association that is related to the identifier in addition to the name and namespace of the <Entity> that contains it. The steps to upgrade <Parameter> and <TypeDescriptor> elements are as follows:
For each <TypeDescriptor> that has the IdentifierEntityName attribute:
- Add the IdentifierEntityNamespace attribute.
If the referenced identifier is a foreign identifier, add a reference to the association that is related to the identifier by using the following attributes:
Note
For more information about foreign identifiers, see the Distinguishing Foreign Identifiers section.
ForeignIdentifierAssociationName Name of the association.
ForeignIdentifierAssociationEntityName Name of the entity that contains the association.
ForeignIdentifierAssociationEntityNamespace Namespace of the entity that contains the association, as you have specified earlier.
While optional, we recommend that you add the ReadOnly attribute with value true to all <TypeDescriptor> elements on return parameters and output parameters. This step prevents your autogenerated forms from giving a false impression that the users can modify the values, and it helps you avoid mistakes and potential data corruption if you decide to add an update function later.
Example 15: The application definition file before the change
<Method Name="GetSalesOrdersForCustomer"> <Parameters> <Parameter Direction="In" Name="@IndividualID"> <TypeDescriptor TypeName="System.Int32" IdentifierName="IndividualID" Name="IndividualID" ForeignIdentifierAssociationName="CustomerToSalesOrder" /> </Parameter> <Parameter Direction="Return" Name="SalesOrders"> <TypeDescriptor TypeName="System.Data.IDataReader" IsCollection="true" Name="SalesOrderDataReader" ReadOnly="true"> <TypeDescriptors> <TypeDescriptor TypeName="System.Data.IDataRecord" Name="SalesOrderDataRecord" ReadOnly="true"> <TypeDescriptors> <TypeDescriptor TypeName="System.Int32" ReadOnly="true" IdentifierEntityName="SalesOrder" IdentifierEntityNamespace="AdventureWorks" IdentifierName="SalesOrderID" Name= "SalesOrderID"/> <TypeDescriptor TypeName="System.DateTime" Name="OrderDate" ReadOnly="true"/> <TypeDescriptor TypeName="System.Int32" Name="IndividualID" IdentifierName="IndividualID" ForeignIdentifierAssociationName="CustomerToSalesOrder" ReadOnly="true"/> <TypeDescriptor TypeName="System.Decimal" Name="SubTotal" ReadOnly="true"/> </TypeDescriptors> </TypeDescriptor> </TypeDescriptors> </TypeDescriptor> </Parameter> </Parameters> <MethodInstances> <Association Type="AssociationNavigator" ReturnParameterName="SalesOrders" Name="CustomerToSalesOrder" IsCached="true"> <SourceEntity Name="Customer" Namespace="AdventureWorks" /> <DestinationEntity Name="SalesOrder" Namespace="AdventureWorks" /> </Association> </MethodInstances> </Method>Example 16: The following XML example shows how the file will look after you have performed the modifications outlined in step 9
<Method Name="GetSalesOrdersForCustomer"> <Parameters> <Parameter Direction="In" Name="@IndividualID"> <TypeDescriptor TypeName="System.Int32" IdentifierName="IndividualID" Name="IndividualID" ForeignIdentifierAssociationName="CustomerToSalesOrder" /> </Parameter> <Parameter Direction="Return" Name="SalesOrders"> <TypeDescriptor TypeName="System.Data.IDataReader" IsCollection="true" Name="SalesOrderDataReader" ReadOnly="true"> <TypeDescriptors> <TypeDescriptor TypeName="System.Data.IDataRecord" Name="SalesOrderDataRecord" ReadOnly="true"> <TypeDescriptors> <TypeDescriptor TypeName="System.Int32" ReadOnly="true" IdentifierEntityName="SalesOrder" IdentifierEntityNamespace="AdventureWorks" IdentifierName="SalesOrderID" Name= "SalesOrderID"/> <TypeDescriptor TypeName="System.DateTime" Name="OrderDate" ReadOnly="true"/> <TypeDescriptor TypeName="System.Int32" Name="IndividualID" IdentifierName="IndividualID" ForeignIdentifierAssociationName="CustomerToSalesOrder"ReadOnly="true"/> <TypeDescriptor TypeName="System.Decimal" Name="SubTotal" ReadOnly="true"/> </TypeDescriptors> </TypeDescriptor> </TypeDescriptors> </TypeDescriptor> </Parameter> </Parameters> <MethodInstances> <Association Type="AssociationNavigator" ReturnParameterName= "SalesOrders" Name="CustomerToSalesOrder" IsCached="true"> <SourceEntity Name="Customer" Namespace="AdventureWorks" /> <DestinationEntity Name="SalesOrder" Namespace="AdventureWorks" /> </Association> </MethodInstances> </Method>
Next Steps
If you are using a full-featured XML editor, ensure that the XML does not have any schema errors. The Business Data Connectivity schema has built-in validation rules to catch simple issues. After you fix all the schema issues, your metadata is ready for import. While importing the metadata, the Business Data Connectivity service validates your metadata further and lets you know if there are any problems with it. On the first import, it is likely that you will receive warnings about deprecated attributes and required values filled with defaults. If you export your metadata and continue working on the exported metadata, most of these warnings will disappear. During export, the Business Data Connectivity service will automatically add the missing values and update the style of your metadata.
After you successfully import your metadata, you can create an external list or use Business Data Web Parts to test the functionality. While this topic attempts to address all the basics of the upgrade, it is possible that there will be cases that require additional work. At this point, you can start to look at the new functionality and improvements in Business Data Connectivity and modify your metadata to take advantage of them.
Special Cases and Conditions When Upgrading Business Data Catalog Application Definition Files
The following are some special cases to consider when upgrading your Business Data Catalog application definition XML files to Business Data Connectivity model XML files.
Fixing System Type
Specifying the type of the <LobSystem> via the SystemUtility, ConnectionManager, and EntityInstance attributes is not supported.
If the values of these attributes start with the values in Table 2, you must remove all these attributes and add a Type attribute to the <LobSystem> element with value WebService.
Table 2. LobSystem Attributes to Replace
Attribute |
Value the Attribute Starts With |
|---|---|
SystemUtility |
Microsoft.Office.Server.ApplicationRegistry.SystemSpecific.WebService.WebServiceSystemUtility |
ConnectionManager |
Microsoft.Office.Server.ApplicationRegistry.SystemSpecific.WebService.WebServiceConnectionManager |
EntityInstance |
Microsoft.Office.Server.ApplicationRegistry.SystemSpecific.WebService.WebServiceEntityInstance |
Then you must remove all these attributes and add a Type attribute to the <LobSystem> element with value WebService.
Otherwise, if the values of these attributes start with:
Table 3. Additional LobSystem Attributes to Replace
Attribute |
Value the Attribute Starts With |
|---|---|
SystemUtility |
Microsoft.Office.Server.ApplicationRegistry.SystemSpecific.Db.DbSystemUtility |
ConnectionManager |
Microsoft.Office.Server.ApplicationRegistry.SystemSpecific.Db.DbConnectionManager |
EntityInstance |
Microsoft.Office.Server.ApplicationRegistry.SystemSpecific.Db.DbEntityInstance |
Then you must remove all these attributes and add a Type attribute to the <LobSystem> element with value Database.
If these attributes have other values, then you should contact the author of the application definition to obtain a new version that is compatible with SharePoint 2010.
Managing Anonymous Access
In the Business Data Catalog, it is possible to give anonymous users permission to execute a method instance by adding a property with name AllowAnonymousExecute on the <MethodInstance> element. In Business Data Connectivity, this permission is managed by access control lists (see AccessControlList Element (BDCMetadata Schema)). If you want some or all of your method instances to be executable by anonymous users, you can achieve this in one of the following two ways:
Business Data Connectivity Service administration enables you to give execute rights to anonymous users by specifying NT Authority\Anonymous Logon as the user name. However this option can be used only to give permissions to all method instances in an external content type (entity).
You can create or modify a metadata resource file for the external content type or add the permissions in the metadata directly. However, this option requires you to provide the entire access control list for the metadata. It is not possible to add a new access control entry to the existing access control lists.
Identifying the Return TypeDescriptor
The return TypeDescriptor for a MethodInstance is the TypeDescriptor that identifies the object to be considered as the return value for the MethodInstance, and in the Business Data Catalog application definition it is identified with three attributes: ReturnParameterName, ReturnTypeDescriptorName, and ReturnTypeDescriptorLevel. The return TypeDescriptor is the TypeDescriptor with the name specified in the ReturnTypeDescriptorName attribute on the parameter with the name specified in the ReturnParameterName attribute. In case there is more than one TypeDescriptor with the same name on the parameter, the TypeDescriptor at the level specified in the ReturnTypeDescriptorLevel attribute is used (root TypeDescriptor of the parameter is level 0).
Distinguishing Foreign Identifiers
In application definitions for the Business Data Catalog, an identifier is a foreign identifier if either of the following is true:
The Identifier is on the input parameter of the method that contains an Association in the MethodInstances.
The Identifier is on the output or return parameter of a method and it represents the Identifier of an external item other than the external item whose fields are represented in the same parameter.
Example 1: If the TypeDescriptors in the return parameter represent the fields of an order: OrderId , ShippingAddress, Discount, CustomerId, and two of these fields are Identifiers: OrderId and CustomerId, then the Identifier that does not identify the current external item is a foreign Identifier. In this case, CustomerId is a foreign Identifier, because it identifies a Customer in relationship to the current item: an order.
Example 2: If the TypeDescriptors in the return parameter represent the fields of an Employee: EmployeeId, Name, LastName, Title, ManagerId, and two of these fields are Identifiers: EmployeeId and ManagerId, then the Identifier that does not identify the current external item is a foreign Identifier. In this case, ManagerId is a foreign Identifier, because it represents another Employee in relationship to the current item: an employee.
Please note that this decision requires understanding of what the model does and what the field values represent in the external system.