Issue with Hybrid Connections and the PowerShell API

While recently playing around with the PowerShell API Azure Hybrid Connections, I stumbled across an interesting “feature” when managing registrations within the on-premises Connection Manager.

As outlined in the MSDN documentation, there are five cmdlets that are included with the Hybrid Connection Manager that you download and install from the Azure portal:

  • Add-HybridConnection
  • Update-HybridConnection
  • Delete-HybridConnection
  • Get-HybridConnection
  • Set-HybridConnectionManagerConfiguration

The first three require a connection string as a parameter, which you can copy from the Hybrid Connection itself in the Azure Portal by clicking the “Manage Connection” button:


Note that only the “On-Premises” connection strings apply to the local Connection Manager. Clicking the button shown in the above screenshot will copy the primary connection string to your clipboard (if you allow your browser to do this).

The format of the on-premises connection string is always like this:


The anomaly I found was when executing the Update command with the connection string I had just copied, it resulted in the following error:

Update-HybridConnection : Could not find configuration Endpoint=hc://;SharedAccessKeyName=defaultListener;SharedAccessKey=

Which was indeed very strange, since not only did I copy the connection string from the active Hybrid Connection in Azure (which showed a status of “connected”), but the prior “Get” command showed the very same connection name:


Or did it??  Look very closely at these again and you’ll notice a subtle difference:


See it now? When I created the Hybrid Connection in Azure, I named it “DEVDAN05-SQL” in all uppercase letters. Naturally, this is the way it was presented in the connection string copied from the portal. However, the connection registered with the local agent as reported by the PowerShell API has been converted to all lowercase letters, evident in the Get command output.

And guess what? PowerShell obviously performs a case-sensitive comparison between the two when searching for registered connections – which means it fails to find the Hybrid Connection that the connection string parameter refers to.

Changing the Hybrid Connection name in the parameter to lowercase letters produces a successful result straightaway:


I’m convinced that the conversion to lowercase occurs when the Hybrid Connection Manager is installed on premises via the “On-Premises Setup” download from the portal, rather than when the PowerShell API retrieves the current registrations. How do I know this? Because when I removed the connection and restored it manually using Add PowerShell cmdlet, the original case was retained:


Is this a bug? Well, it certainly seems like an inconvenient feature. However, it’s not without workarounds. You can either:

  • Always name your Hybrid Connections in lowercase characters, or
  • Always register (or re-register) your connections locally using the manual PowerShell API process, instead of relying on the convenient “On-Premises Listener Setup” feature from the portal.

Despite the inconvenience, it is good that Microsoft has made all of the CRUD operations on these connections scriptable, as this certainly would come in handy when deploying and managing the Hybrid Connection Manager on multiple servers in the corporate network. (Did you know that a Hybrid Connection will automatically load balance between all Connection Managers that it is registered with? Nice!)

About Dan Toomey
Enterprise integration geek, Microsoft Azure MVP, Pluralsight author, public speaker, MCSE, MCT, MCTS & former professional musician.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

John Glisson - Geek of the Cloth

Thoughts on integration, technology and what-not...

Prashant BizTalk And Azure Integration Blogs

My Integration Experiences - BizTalk And Azure Integration


THINK: It's not illegal....yet.....

Abdul Rafay's BizTalk Blog

My experiences with BizTalk related to architecture, development and performance in my enterprise.

BizTalk musings

Issues, patterns and useful tips for BizTalk development


Enterprise Applicaiton Integration and SOA 2.0

Connected Pawns

Mainly BizTalk & Little Chess

Adventures inside the Message Box

BizTalk, Azure, and other tools in the Microsoft stack - Johann Cooper


Talk, talk and more talk about BizTalk

Richard Seroter's Architecture Musings

Blog Featuring Code, Thoughts, and Experiences with Software and Services

Sandro Pereira BizTalk Blog

My notes about BizTalk Server 2004, 2006, 2006 R2, 2009, 2010, 2013 and now also Windows Azure BizTalk Services.

BizTalk Events

Calendar of BizTalk events all over the world!

Mind Over Messaging

Musings on BizTalk, Azure, and Enterprise Integration News

The latest news on and the WordPress community.

%d bloggers like this: