SPD (WCF connection) - Cannot find any matching endpoint

When adding a WCF connection to SPD 2010, you will hit "Cannot find any matching endpoint configuration" error, if you did not know the service endpoint URL (see figure 2).

Figure 1: Cannot find any matching endpoint.

Figure 2: WCF connection properties

If you look into the SharePoint ULS logs, you will see a corresponding error message "Could not initialize the endpoint components".

If you are connecting to ASMX based web service, the "Service Endpoint URL" is the ASMX service url. For example, if the ASMX service is hosted at http://myserver/service.asmx then the values for "Service Metadata URL" and "Service Endpoint URL" are as follows -

Service Metadata URL - http://myserver/service.asmx?wsdl
Service Endpoint URL - http://myserver/service.asmx

If you are connecting to WCF service, these values can get interesting. Now with WCF service, the service may not expose metadata endpoint, can expose WSDL endpoint or can expose MEX endpoint.

a) Metadata endpoint not exposed

When the metadata endpoint is not exposed by the WCF service, SPD (BCS) cannot consume that WCF service.

b) Metadata endpoint exposed as WSDL

When the WCF service exposes metadata as WSDL, its "Service Endpoint URL" can be determined by looking in the WSDL. Simply load the WSDL in the web browser ( http://myserver/service.svc?wsdl) and search for soap12:address in the WSDL. Typically it will appear in the end of the WSDL (see figure 3).

<wsdl:service name="Service">
<wsdl:port name="WSHttpBinding_IService" binding="tns:WSHttpBinding_Service">
<soap12:address location="http://myserver/Service.svc" /> 
<wsa10:EndpointReference>
<wsa10:Address>http://myserver/Service.svc</wsa10:Address> 
<Identity xmlns="http://schemas.xmlsoap.org/ws/2006/02/addressingidentity">
<Spn>host/myserver.com</Spn> 
</Identity>
</wsa10:EndpointReference>
</wsdl:port>
</wsdl:service>

Figure 3: Service Endpoint URL in WSDL

There can be more than one soap address in the WSDL, if the service exposes different bindings for these addresses. Depending on your requirement you can choose one of the service address.

c) Metadata endpoint exposed as MEX

When the metadata is exposed as MEX, you will need to read the endpoint addresses using svcutil.exe (http://msdn.microsoft.com/en-us/library/aa347733.aspx). When you execute svcutil.exe against the MEX endpoint, it will generate a config file. In the config file, search for "client" tag (it appears at the end of config file). Look at the addresses for the endpoint.

<client>
  <endpoint address="http://myserver/service.svc/basicHttpBinding"
                binding="basicHttpBinding" bindingConfiguration="MyService"
                contract="IServiceInterface" name="ConsoleService" />
</client>

Figure 4: Service Endpoint URL through MEX endpoint

The addresses mentioned in the config file are the "Service Endpoint URL" that SPD will understand.

Writing Custom Connector for BCS

BCS in SharePoint 2010 provides following connectors - Database, WebService, WCF, .NET and custom connector. This blog explains how you can write and deploy your own custom connector, if one of the BCS connectors do not meet your requirements.

This documentation (http://msdn.microsoft.com/en-us/library/ee554911(office.14).aspx) explains when to use .NET assembly connector and when to write your own custom connector.

Assuming that you are required to write your own custom connector, lets look at the steps to achieve the goal.

The steps for custom connectors are

• Write code for custom connector
• Deploy custom connector in SharePoint
• Write model for custom connector

Writing Custom Connector

Writing custom connector requires implementing ISystemUtility (http://msdn.microsoft.com/en-us/library/microsoft.businessdata.runtime.isystemutility(office.14).aspx) interface. The simple most custom connector requires implementing ExecuteStatic method in the interface. Other methods/properties can be boiler plate code.

Here is the simple most custom connector. Although the connector does not do anything, technically it can be deployed in SharePoint 2010.

using System;
using System.Collections;
using System.Collections.Generic;

using Microsoft.BusinessData.MetadataModel;
using Microsoft.BusinessData.Runtime;
using Microsoft.BusinessData.Infrastructure;

namespace SharePointConnector
{
    public class Connector : ISystemUtility
    {

        #region ISystemUtility Members

        public IEnumerator CreateEntityInstanceDataEnumerator(object rawStream, 
            ISharedEntityState sharedEntityState)
        {
            // implement your enumerator
        }

        public IConnectionManager DefaultConnectionManager
        {
            get { return null; }
        }

        public ITypeReflector DefaultTypeReflector
        {
            get { return null; }
        }

        public void ExecuteStatic(IMethodInstance mi, 
            ILobSystemInstance si, 
            object[] args, 
            IExecutionContext context)
        {
            // implement your logic
        }

        #endregion
    }
}

Figure 1: Simple most custom connector

Let's take a look at the various methods and properties in the ISystemUtility interface.

CreateEntityInstanceDataEnumerator

This method converts line-of-business data stream into an enumerator of raw AdapterObjects. Implementing this method is necessary. If your connector gets IEnumerable as raw stream, you can just return the corresponding enumerator from the method.

DefaultConnectionManager 

This property allows you to manage connections for your external system. You can return null if you don't want connection management. BDC (Business Data Connectivity) will use its own default connection manager.

DefaultTypeReflector 

This property allows you manage the type reflection for your objects. For example, if your external system returns stream, BDC will unable to do a meaningful type reflection and you will have to write your own type reflection. If your external system returns .NET types than you don't need to provide any type reflection. For default implementation this property should return null.

ExecuteStatic

This method is the most important method in the interface. In the method, you should implement CRUDQ (create, read, update, delete and query) stereotypes for the connector.

public void ExecuteStatic(IMethodInstance mi, 
            ILobSystemInstance si, 
            object[] args, 
            IExecutionContext context)

Lets take a look at the method parameters

mi : This parameter represents the MethodInstance that is being executed by BDC. This parameter corresponds to the

<MethodInstance>

element with the LobSystem/Entity/Method in the BDC metadata model.

si : This parameter represents the LobSystemInstance the method instance is being executed against. This parameter corresponds to the

<LobSystemInstance>

element with the LobSystem in the BDC metadata model.

args : This parameter is the Parameters of the MethodInstance that is being executed. The last item in the array is reserved for the return parameter for the method instance.

context : This parameter sets the execution context of BDC. For all practical purposes this parameter can be ignored because External List in SharePoint does not set the execution context and you or BDC will not control this variable. The context can be different for BDC running under Office client.

Ok, now that we understand ISystemUtility interface, lets do some fun stuff.

Sample
In this sample, I will create a custom connector that will return "Movie" entity from an external system. For simplicity, the connector will support only "Finder" and "SpecificFinder" stereotypes. This sample will use in-memory data (external system).

Since the external system returns .NET types, implementation of the custom connector is simple.

public IEnumerator CreateEntityInstanceDataEnumerator(object rawStream, 
    ISharedEntityState sharedEntityState)
{
    IEnumerable enumerableStream = rawStream as IEnumerable;
    if (enumerableStream != null)
    {
        return enumerableStream.GetEnumerator();
    }

    throw new InvalidOperationException("not valid stream returned");
}

Figure 2: CreateEntityInstanceDataEnumerator implementation

In the method CreateEntityInstanceDataEnumerator, the base Enumerator is returned. Off course, for a real external system you may have to write an enumerator.

ExecuteStatic method will check what kind of stereotype is being executed and will execute corresponding methods on the external system. As said before, this connector just supports Finder/SpecificFinder stereotype, so it will throw for other stereotypes.

public void ExecuteStatic(IMethodInstance mi, 
    ILobSystemInstance si, 
    object[] args, 
    IExecutionContext context)
{
    // provide only read functionality
    switch(mi.MethodInstanceType)
    {
        case MethodInstanceType.SpecificFinder:

            IParameterCollection parameters = mi.GetMethod().GetParameters();

            // make sure there is only one input parameter for the method
            // and one return parameter.
            if (parameters.Count != 2 )
            {
                string message = "Method " + mi.GetMethod().Name +" must have one input and one return parameter";
                throw new InvalidMetadataObjectException(message);
            }

            // check if the input parameter is integer type
            // and the return parameter is "Movie" type
            Type param1Type = Type.GetType(parameters[0].GetRootTypeDescriptor().TypeName, false);
            Type param2Type = Type.GetType(parameters[1].GetRootTypeDescriptor().TypeName, false);

            if ( param1Type == null || param1Type != typeof(Int32))
            {
                string message = "Method " + mi.GetMethod().Name +" must contain input of type System.Int32";
                throw new InvalidMetadataObjectException(message);
            }

            if ( param2Type == null || param2Type != typeof(Movie))
            {
                string message = "Method " + mi.GetMethod().Name +" must contain input of type " + typeof(Movie).ToString();
                throw new InvalidMetadataObjectException(message);
            }

            int id = (int)args[0];
            args[1] = MovieData.GetMovie(id);

            break;

        case MethodInstanceType.Finder:
            args[args.Length-1] = MovieData.GetMovies();
            break;

        default:
            throw new NotImplementedException();
    }
}

Figure 3: ExecuteStatic implementation

The method verifies the Finder/SpecificFinder signature in metadata model. This way the connector can ensure that the metadata model is not invalid. Finally it executes the external system and sets the return value in args parameter.

I have attached complete source code at the end of this post.

Deploying Custom Connector in SharePoint

Deploying custom connector in SharePoint 2010 is pretty straight forward. All you need is to GAC the assembly in all  the SharePoint machines. This includes web-front ends as well as application servers in the farm. If you have the requirement to execute custom connectors on Office client ( take External List to Outlook or Workspaces ) you will need to GAC the assembly in client machines as well.

Writing Models for Custom Connector

Now that you have written the custom connector and have already deployed in the SharePoint, lets get a sample external list for the custom connector.

The LobSystem Type for custom connector must specify  "Custom". When custom connectors are used, the model must contain the SystemUtilityTypeName property for LobSystem.

<LobSystems>
    <LobSystem Type="Custom" Name="CustomLobSystem">
      <Properties>
        <Property Type="System.String" Name="SystemUtilityTypeName">SharePointConnector.Connector, SharePointConnector, Version=1.0.0.0, Culture=neutral, PublicKeyToken=dc97b363e814985e</Property>
      </Properties>

Figure 4: LobSystem properties for custom connector

SystemUtilityTypeName is the fully qualified name for custom connector type. The following figure shows snippet of the metadata model.

 

Figure 5: Metadata model snippet for custom connector

The sample metadata model is also attached in the source code (see end of post).

Custom connector in action

Now that we have our metadata model for custom connector, lets fire it up in the SharePoint. The following screen shots show the external list running against custom connector.

 

Figure 6: Choosing external content type

Figure 6 shows the external content type displayed for custom connector. At this point the custom connector is not being executed.

Figure 7: Finder stereotype executed in custom connector (via External list)

Figure 8: SpecificFinder stereotype executed in custom connector

Figure 7 and Figure 8 shows Finder and SpecificFinder stereotyped operations running in custom connector. Our custom connector executes the external system methods and returns appropriate data.

Source Code

Sample with complete source code can be downloaded from here.

As-is
The source code/software is provided "as-is". No claim of suitability, guarantee, or any warranty whatsoever is provided. Source Code and executable files can not be used in commercial applications.

Reading BDC model properties in .NET Assembly Connector

Introduction

BDC in SharePoint 2010 support connectors for "Web Service", "Wcf Service", "Database", ".NET Assembly" and "Custom". ( BDC in MOSS 2007 has support for "Web Service" and "Database" only ).

.NET Assembly Connector basically allows to host a virtual LobSystem. The concept for .NET assembly connector is very similar to my suggestions of hosting .NET assembly in MOSS 2007 - BDC : Beyond Web-Service and Database.  Since .NET assembly is natively supported in SharePoint 2010, it has way more capabilities than my suggested approach. The following article (http://msdn.microsoft.com/en-us/library/aa868997.aspx) explains how to create a .NET Assembly Connector in BDC.

This blog explains how you can use BDC model properties within your .NET assembly code.

IContextProperty Interface

To use the BDC model in the .NET assembly, lets first take a look at the IContextProperty interface [r1]. IContextProperty interface is defined in Microsoft.BusinessData.SystemSpecific namespace ( in Microsoft.BusinessData.dll )

namespace Microsoft.BusinessData.SystemSpecific
{
    public interface IContextProperty
    {
        IExecutionContext ExecutionContext { get; set; }
        ILobSystemInstance LobSystemInstance { get; set; }
        IMethodInstance MethodInstance { get; set; }
    }
}

Figure 1: IContextProperty interface

.NET assembly connector in BDC uses IContextProperty interface to communicate the context in which BDC is executing the method in the class. If your class implements IContextProperty interface, BDC will initialize the three properties of the interface. Here is an example how you can write your class to implement the interface.

using Microsoft.BusinessData.SystemSpecific;

namespace MyNamespace
{
    public class MyClass : IContextProperty
    {
        private IExecutionContext context;
        private ILobSystemInstance lobSystemInstance;
        private IMethodInstance methodInstance;

        #region Implementing IContextProperty interface

        public IExecutionContext ExecutionContext 
        { 
            get { return this.context; } 
            set { this.context = value; }
        }

        public ILobSystemInstance LobSystemInstance
        { 
            get { return this.lobSystemInstance; } 
            set { this.lobSystemInstance = value; }
        }

        public IMethodInstance MethodInstance
        { 
            get { return this.methodInstance; } 
            set { this.methodInstance= value; }
        }

        #endregion
    }
}

Figure 2: IContextProperty implementation

At this time "MyClass" class is ready to get the context from BDC.


Defining properties in BDC Model

Depending on what kind of information you need in the .NET code, you can define your property at appropriate element in the BDC model. For example, if your class needs to connect to different server for different region, LobSystemInstance would be a good place to define your property. In the case method needs to know which Locale is preferred by the user, it can look into the properties of Method or MethodInstance.

In this example, the class connects to a different database server based on which region the code is getting executed.

private string GetDbConnectionString(string region)
{
    string dbConnectionStringFormat = "Data Source={0};Initial Catalog=myDataBase;Integrated Security=SSPI;";
 
    // default DB Server
    string regionDbServer = "northamericaDBServer"; 

    if (region == "emea")
    {
        regionDbServer = "emeaDbServer";
    }
    else if (region == "asia")
    {
        regionDbServer = "asiaDbServer";
    }

    return string.Format(dbConnectionStringFormat, region);
}

Figure 3: Customize connection string

The above code relies on the region information to format DB connection string. Unfortunately, when the code gets executed in SharePoint, the method has no idea where it is being executed and would default to using north america db server.

To solve this issue, you can define a property in the BDC model which tells the code which DB server to use. Lets say the property name is "Region" and is defined within the LobSystemInstance.

<LobSystemInstances>
  <LobSystemInstance Name="NorthAmerica">
    <Properties>
      <Property Name="Region" Type="System.String">northamerica</Property>
    </Properties>
  </LobSystemInstance>
  <LobSystemInstance Name="Default">
    <Properties>
      <Property Name="Region" Type="System.String">northamerica</Property>
    </Properties>
  </LobSystemInstance>
  <LobSystemInstance Name="EMEA">
    <Properties>
      <Property Name="Region" Type="System.String">emea</Property>
    </Properties>
  </LobSystemInstance>
  <LobSystemInstance Name="Asia">
    <Properties>
      <Property Name="Region" Type="System.String">asia</Property>
    </Properties>
  </LobSystemInstance>
</LobSystemInstances>

Figure 4: BDC model properties

In this example, different LobSystemInstances are used for each region, where the "Region" property is defined in LobSystemInstance. This is particularly useful when the user creates an external list. The user can choose the appropriate LobSystemInstance depending on its region.

Reading properties in the method

So now that the properties are defined in the model, its time to read the property in the code. The class "MyClass" exposes a method ReadAllItems for Finder stereotype. In this method, LobSystemInstance property returns the LobSystemInstance (BDC context).  LobSystemInstance.GetProperties() method returns all the properties defined for the LobSystemInstance.

public MyItems ReadAllItems()
{
   // get the LobSystemInstance properties via context from BDC
   INamedPropertyDictionary properties = this.LobSystemInstance.GetProperties();

   string region = null;

   // search for "Region" property in model
   if (properties.ContainsKey("Region"))
   {
        region = properties["Region"] as string;
   }

   //get the db connection string
   string dbConnectionString = GetDbConnectionString(region);

   //do normal db processing
   //return the items for method

}

Figure 5: Use the BDC model property

Once we have all the properties, the code checks if the "Region" property has been defined or not and reads the "Region" property accordingly. Once the Region property is read, it is used to create the DB connection string and the DB query is executed against that particular DB server.

Conclusion

BDC model is the right place to define custom properties. These properties should be used in .NET assembly connector code to customize solutions.

References

r1: IContextProperty interface: http://msdn.microsoft.com/en-us/library/microsoft.businessdata.systemspecific.icontextproperty(office.14).aspx

Business Connectivity Services (BCS) - Profile Pages

Profile Page

A profile page in BCS (Business Connectivity Services) allows to display all the information for an external content (entity instance). For example, a profile page can display all the fields in a record for a specific customer. It can also display all the orders associated with the customer.

NOTE: A profile page is different from user profile. User profile is a SharePoint feature where as profile page is specific to BDC (Business Data Connectivity).

Profile page has a unique url, as each entity (External Content Type) has its own profile page. Profile page in SharePoint 2010 is not created automatically anymore (it was created automatically in MOSS 2007).

If the profile page is not enabled for the entity, clicking on the entity instance will load the view items page.

Figure 1: View item for External Content Type

Figure 2: View Item Page

To create a profile page for an entity, you will need to configure where the profile page will be hosted. To configure, click on the configure button in the BDC administration page/ribbon (figure 3).

Figure 3: Configure profile page button

This loads a wizard where you can enter the host location for the profile page. Profile page can only be hosted on SharePoint sites.

Figure 4: Profile page host

At this time, you can enable your entity to have a profile page. To do so, click on the External content type and click "Create/Upgrade Profile Page".

Figure 5: Create/Upgrade Profile Page

Figure 6: Profile page confirmation

Once the profile page has been created you will notice there is an default action associated with the external content type (figure 7).

Figure 7: Default action

Unfortunately, external list does not allow to go the profile page from the list (hopefully it gets fixed in RTM). To view the profile page load the default action URL in browser and set the ContactID.

Profile page is particularly useful to view entity associations. Figure 8 shows a Contact profile page, where sales order from the contact is displayed along with the contact information.

Figure 8: Contact and its sales order

Links

Adding associations - http://msdn.microsoft.com/en-us/library/ee558417(office.14).aspx
Associations Support in SPD - http://blogs.msdn.com/bcs/archive/2010/01/15/tooling-associations-in-sharepoint-designer-2010.aspx