How to use the BDLC API with PowerShell

In this article, how to make use of the BDLC API with PowerShell to automate operations or BDLC configurations and maintain your BDLC environment.

Requirements and test environment

• SharePoint 2013 and up
• PowerShell version 4.0+
• .Net Version 4.0+
• PowerShell PSSnap-In Microsoft.SharePoint.PowerShell needed
• You'll need to reference against the BDLC assembly Layer2.SharePoint.BusinessDataListConnector.dll

Setting up the project environment

Before starting with the coding, two additional libraries have to be loaded:

Microsoft.SharePoint.PowerShell PSSnapin

To access useful Cmdlets that help us to manipulate SharePoint Objects from PowerShell it is necessary to add the Microsoft.SharePoint.PowerShell Snapin into our Script. This Snapin can be added as follow:

Add-PSSnapin "Microsoft.SharePoint.PowerShell" 

Once added and the script is executed the Snapin will be loaded into the current PowerShell session.   

Layer2.SharePoint.BusinessDataListConnector.dll

We need this library in order to use the BusinessDataListConnector API. To load it into the script it is necessary to use the Add-Type Cmdlet (this Cmdlet adds a Microsoft .NET Framework Type to the current PowerShell session).

The library can be added as follow:

[string]$currentScriptDirectory = [System.IO.Path]::GetDirectoryName($myInvocation.MyCommand.Definition)

Add-Type -Path (Join-Path $currentScriptDirectory "Layer2.SharePoint.BusinessDataListConnector.dll")

The Layer2.SharePoint.BusinessDataListConnector.dll DLL has to be placed in the same directory as the current script.

Getting the SharePoint Web & List

Since we are using the Microsoft.SharePoint.PowerShell Snapin we will work with the SharePoint SSOM. Through SSOM we can get the List and the Web where the list is located as follow:

$site = Get-SPSite -Identity "https://site.sp2013"
$web = $site.RootWeb
$list = $web.Lists.TryGetList("BDLC_TestList") 

Once this is done we can proceed to start using the API.

Using the BDLC API

Enabling BDLC on a List

To enable the BDLC on a SharePoint Lists we can invoke the EnableBDLCOnList($web, $list, …) function, this function will initialize two objects: 

$listSettings = New-Object Layer2.SharePoint.UI.Administration.Lists.ListSettings 
$businessDataListConnectorLogic = New-Object Layer2.SharePoint.UI.Administration.Lists.BusinessDataListConnectorLogic 

We use the New-Object Cmdlet to create two different BDLC API objects. In this case the full namespace must be specified when creating the objects (please note the namespace is not equal to the assembly name).

Once we call the function with the Web, List and the other required parameters, the function will enable the BDLC in the given list, creating a new configuration item in the BDLC configuration list and assigning the needed event receivers. 

Updating All Lists

To update all lists in a site collection that are connected via BDLC you have to invoke the UpdateAllListsInSiteCollection() function. This function will get the BDLC Configuration List by calling the Get-BdlcConfigList() function, after that a ForEach loop will go through all items in this list and get the lists that have to be updated. After this the function will call the UpdateThisList() function and proceed to update the lists where the BDLC is configured.

Update Sensitive Data in the BDLC Configuration List

Some parameters in the BDLC Configuration list are encrypted to provide its sensitive data. If you want to write directly into the configuration list, you have to use the BDLC encryption provided by the API. Invoke the UpdateBdlcListConnectionItem() function to update encoded values directly in the BDLC configuration List. 

Disabling BDLC on List

To disable the BDLC on a list the DisableBdlcInThisList() function must be called. This function calls the nested function Get-ConfigItem() to get the item from the BDLC configuration list which is the list where BDLC is installed.


These are just four examples of how to use the BDLC API through PowerShell. Check also the BDLC Programming Guide to learn about all possibilities you have with using the BDLC API. 

Download BDLC API PowerShell

Possible Issues

PowerShell Not Trusted DLLs from the Internet

When you get a DLL from the internet (in this case the BDLC API DLL), PowerShell by default might not load it as assembly in your PowerShell script session. 

You could get an error like this one: 

If that is the case, you can try one of the two solutions below:

1. Unblock the content (recommended).

You need to right-click on the downloaded file, select Properties, and click 'Unblock' in the general tab. This can also be done by PowerShell through the Unlock-File Cmdlet.

For more information, please check the Microsoft official documentation Exception from HRESULT: 0x80131515

2. Set the PowerShell Execution Policy 

Microsoft's instructions About Execution Policies. 

NOTE: This method could allow malicious scripts from the internet to be executed without restrictions, so be careful!

READY TO GO NEXT STEPS?