Exploring the BCS Metadata Schema

  • Article

When developers are first getting started using BCS, they typically use SharePoint Designer (or perhaps Visual Studio 2010) to put together their BCS model.  Using either of those tools, it is pretty easy to discover an external data source, and follow the appropriate steps to connect BCS to the data source and create an external content type (ECT).  This is great for the most common scenarios.  But sooner or later, you will encounter scenarios where you can’t use SharePoint Designer or Visual Studio to configure your model for you.  In these cases, you need to edit the BCS metadata schema directly as an XML file.  In addition, even if you never leave the confines of SharePoint Designer or Visual Studio for creating ECTs, it is important to understand the BCS metadata schema.  I love using great tooling, but I always want to understand what's going on under the hood.

This blog is inactive.
New blog: EricWhite.com/blog

Blog TOCI’m currently in the process of writing a couple of MSDN articles on creating more advanced associations using BCS, such as creating a one-to-many association where you don’t have a foreign key, and creating many-to-many associations.  In both of these scenarios, you need to edit the BCS model directly.   As I was wrapping my head around the BCS metadata schema, I thought it would be helpful to me to use an outlining tool to explore the schema.  OneNote 2010 has the best outlining tool that I've ever used.  It has the necessary capability of collapsing and expanding nodes, promoting and demoting nodes, and moving nodes around by dragging/dropping.  In addition, you can place tables at any node, and then format those tables as you like.  I put together a OneNote page that contains the elements and attributes of the BCS metadata schema.  Being able to expand and contract the nodes enabled me to see the big picture.  I made links back to the MSDN documentation topics, so it is easy to navigate to the documentation for each element, attribute, and property.

I thought this outline would be useful to others, so I posted the OneNote page to my Live SkyDrive.  You can download it here.  After you download it, open it using OneNote 2010.  If you are doing SharePoint development, you probably are aware of the 2010 Information Worker Demonstration and Evaluation Virtual Machine.  If you don’t have OneNote 2010 on your local machine, you can open this OneNote page using OneNote in that virtual machine.  Note that unless you've configured the VM to allow it (which isn't recommended), you can't navigate back to MSDN from the OneNote page.

Note that this is not official documentation in any shape or form.  It is just another way to navigate to the official docs.

Here is what the BCS Schema looks like in the OneNote file:

 

 

The BCS Metadata schema allows you to supply additional properties for certain elements.  When you supply these additional properties, you use the Properties element, which children Property elements.  Each Property element has a Name and Type attribute.  The value of the property is text content of the Property element.

<LobSystemInstances>
  <LobSystemInstanceName="AdventureWorksWS">
    <Properties>
      <PropertyName="WcfAuthenticationMode"
                Type="System.String">PassThrough</Property>
      <PropertyName="WcfEndpointAddress"
                Type="System.String">https://ericwhit211:8080/WebService.asmx</Property>
      <PropertyName="ShowInSearchUI"
                Type="System.String"></Property>
    </Properties>
  </LobSystemInstance>
</LobSystemInstances>

 

I’ve included those properties in my study notes:

 

 

I took a few shortcuts when putting together these notes.

Some elements (such as AccessControlList, and LocalizedDisplayNames) occur at a variety of places in the document.  I didn’t repeat the attributes and child elements for those elements over and over again in the OneNote page.  They are coded in the same way in every location, and it didn’t add any clarity to the outline to repeat that information.

 

In a few places, a number of attributes are self-explanatory.  For instance, in the example below, it is pretty clear that the Name attribute is the name of the Method, so I didn’t bother writing a description for the attribute.  As I said, these are just study notes that I assembled for myself that provide a convenient way to navigate through the online documentation.

 

There is one issue around the TypeDescriptor element that bears mentioning.  A TypeDescriptor element can contain a child TypeDescriptors element, which then contains one or more TypeDescriptor element.  You will find this when a TypeDescriptor is describing a collection of some type.  I’ll examine this issue further when I write about TypeDescriptor  elements in more detail.  In the outline, I didn't repeat the attributes and properties of the TypeDescriptor that is a descendant of another TypeDescriptor element.

 

I’ve grappled with the issue of documenting XML vocabularies.  The approach taken by the BCS documentation is essentially the same approach as taken by the Open XML specification.  For each element, you list its attributes, its child elements, and its parent element.  This is pretty good for a reference, but it doesn’t help to put the big picture together.  Instead of using OneNote for this purpose, I can imagine putting together a web page with links to documentation of elements and attributes organized in a hierarchical control.  This might be a great way to navigate through XML documentation.