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:

Endpoint=hc://.hybrid.biztalk.windows.net/
;SharedAccessKeyName=defaultListener;
SharedAccessKey=

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://musicamangia.hybrid.biztalk.windows.net/DEVDAN05-SQL;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!)