How to use the BDLC API with PowerShell

In this article, we describe how to make use of the BDLC API with PowerShell scripts to automate deployments or provisioning BDLC configurations to SharePoint project rooms or just oto maintain your BDLC environment. 

 

Requirements and test environment

 

  • SharePoint 2013 
  • 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

Here are some examples what you can do with PowerShell and your BDLC lists. The example code is available as download here: LINK

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. 


BDLC Enable List with PowerShell Screenshot

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 all BDLC lists with PowerShell Screenshot

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. 

update the BDLC config list with PowerShell Screenshot

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.

disable a list in BDLC with PowerShell Screenshot
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 PowerShell API Sample

Download BDLC Programming Guide

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: 

 

possible issue in powershell with BDLC screenshot

 

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 this Exception from HRESULT: 0x80131515 documentation from Microsoft about it. (LINK)

2. Change your Execution Policy 

 

Follow the instructions on this site: LINK

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

     

READY TO GO NEXT STEPS?

Ifoc for free trial product regsitration - Layer2 leading solutions

Register for free download.

Keep your Sharepoint in sync. Download and try today.
Contact Us Icon for Layer2 leading solutions

Questions? Contact us.

We are here to help. Contact us and our consulting will be happy to answer your questions.