Using Dot Notation in the Business Data Connectivity (BDC) Service

SharePoint 2010

Last modified: April 19, 2010

Applies to: SharePoint Server 2010

In this article
Example1: Refer to a field of a complex type
Example2: Access collections
Example3: Refer to fields that have special characters

A data structure returned by an external system can contain complex structures with multiple levels of data elements. In Business Data Connectivity (BDC) service, each level of data elements can be accessed by using the dot notation. Dot notation is a representation of the data elements similar to accessing data elements in C#. Each data element is accessed by providing their parent data element and the name of the data element if the containing data element is a structure, or the index of the data element, if the containing element is a collection. Following are some examples of how to use dot notation.

Consider a Customer structure is an external item with the following fields:

  • CustomerID

  • Name

  • PhoneNumber

  • Address

    • Street

    • City

    • State

    • Zip

The Address field is a complex type. Let's assume that you want to display the following fields from the Customer external item:

  • Name

  • PhoneNumber

  • City

  • State

In this case, you can get these fields by using the indexer in the IEntityInstance interface as shown in the following code.

IEntityInstance customerItem = customerEntity.FindSpecific (...);

customerItem["Name"]
customerItem["PhoneNumber"]
customerItem["Address.City"]
customerItem["Address.State"]

You can also refer to members inside of collections by using BDC. Consider a Customer structure with the following fields:

  • CustomerID

  • Name

  • PhoneNumber

  • Addresses (this is a collection of Address elements)

    • Address

      • Street

      • City

      • State

      • Zip

The customer structure in this example contains an Address collection. Let's assume that the first address in the collection is the primary address and that you want to display the following fields from the Customer external item:

  • CustomerID

  • Name

  • PhoneNumber

  • PrimaryAddressCity

  • PrimaryAddressState

In this case, in the return parameter of the SpecificFinder method instance, you can refer to the City and State subfields of the Customer structure as shown in the following code.

Customer.Addresses[0].City
Customer.Addresses[0].State

If the name contains one of the following special characters: backslash ("\"), period ("."), or bracket ("["), you must escape the special character with "\".

Consider a Customer structure with the following fields:

  • CustomerID

  • Name

  • PhoneNumber

  • Address

    • Street

    • House\PropertyNo

    • City

    • State

    • Zip

The field "House\PropertyNo" contains the following special character: "\". Let's assume that you want to display the following fields from the Customer external item:

  • CustomerID

  • Name

  • PhoneNumber

  • House\PropertyNo

  • City

  • State

In this case, in the return parameter of the SpecificFinder method instance, you can refer to House\PropertyNo subfield of the Customer structure as shown in the following code:

Customer.Address.House\\PropertyNo
Show: