First published on MSDN on Jun 30, 2017
Using a Hybrid Connection with your Web App allows you to easily connect to on-premise resources. We recently improved the experience with Hybrid Connections by moving from BizTalk Services to Azure Relay. In this post, I'll address some of the things you should be aware of so that you can avoid problems.
In this post:
Don't Use an IP Address for Your Endpoint, and Be Careful with Fully-Qualified Names
Azure Relay Hybrid Connections Don't Work in Windows Server 2008 R2
Hybrid Connection User Logging Doesn't Work with Azure Relay Hybrid Connections
Make Sure that the Date and Time are Correct
If Whitelisting, Ensure You Whitelist the Service Bus Gateways
When Using SQL Express, Don't Use Names Instances and Enable TCP/IP
When Using SQL Server, Configure it for a Static Port
Use the Correct Connection String
If your status is "Connected" but the connection isn't working, check connectivity to Service Bus
Update your Hybrid Connection Manager
Classic Hybrid Connections are End of Life on May 31, 2018
Don't Use an IP Address for Your Endpoint, and Be Careful with Fully-Qualified Names
When you configure your Hybrid Connection, it's a bad idea to use an IP address for the endpoint because it can prevent the Hybrid Connection from working. When your Web App connects to a resource whose DNS name maps to a Hybrid Connection endpoint, it will send that traffic through the Hybrid Connection. However, if you use an IP address, the Web App won't be able to detect that this is a connection that should go through the Hybrid Connection. The result is that your Hybrid Connection simply doesn't work.
Instead of using an IP address for your endpoint, you should typically use the hostname of the server hosting the resource you are trying to connect to. That means that it's often a bad idea to use a fully-qualified name as well. See this post for more information.
Back to Top
Azure Relay Hybrid Connections Don't Work in Windows Server 2008 R2
There are currently two "flavors" of Hybrid Connections; Hybrid Connections that use Azure Relay (the new Hybrid Connections) and Classic Hybrid Connections that use BizTalk Services. (Classic Hybrid Connections are being deprecated, but if you have any existing ones, you can still use them.) You can install the Hybrid Connection Manager on Windows Server 2008 R2 for use with a Classic Hybrid Connection, but you can't use new Hybrid Connections on Windows Server 2008 R2. That's because Azure Relay Hybrid Connections use Web Sockets, and Web Sockets are only supported in Windows 8/Windows Server 2012 and later.
If you run the Hybrid Connection Manager (version 0.7.3 and later) on a machine running Windows Server 2008 R2, you'll see a warning telling you that only Classic Hybrid Connections will work. Pay attention to that warning! You can still add an Azure Relay Hybrid Connection, and it will still show "Connected" in the Hybrid Connection Manager, but it won't work because Windows Server 2008 R2 does not support Web Sockets.
Back to Top
Hybrid Connection User Logging Doesn't Work with Azure Relay Hybrid Connections
When you have problems with your Hybrid Connection, there are a few options available for logging. On the machine running the Hybrid Connection Manager, you can use System.Net tracing or you can view the Service Bus entries in Event Viewer. See this post for more information.
You can also enable Hybrid Connection User Logging in your Web App by setting an App Setting of HYBRIDCONNECTIVITY_LOGGING_ENABLED with a value of 1. This will add a Hybrid Connection log into your LogFiles folder. However, it's important to note that, as of now, User Logging doesn't work with the new Azure Relay Hybrid Connections because of the new architecture involving Service Bus. We're investigating the possibility of enabling this, but we have no ETA and it may not be possible.
Back to Top
Make Sure that the Date and Time are Correct
The Hybrid Connection Manager connects to Azure Relay using Secure Sockets Layer (SSL) on port 443. If there's a problem with your SSL handshake or connection, it will break your Hybrid Connection. If you find that your Hybrid Connection works initially, and then it stops working after about 10 minutes, that's a sign that you need to check the date and time on the machine running the Hybrid Connection Manager. Make sure they are correct because if they're not, your SSL connection may not work.
Back to Top
If Whitelisting, Ensure You Whitelist the Service Bus Gateways
Some network environments require that outbound communicates are whitelisted. If you're in one of those environments, you need to whitelist both the Service Bus endpoint URL and the Service Bus gateways that service your Hybrid Connection.
You can find the Service Bus endpoint URL by clicking on your Hybrid Connection in the Hybrid Connection Manager. In the Details dialog, you'll see the Service Bus endpoint URL as shown in the figure below.
[caption id="attachment_2915" align="alignnone" width="480"] 
You also need to whitelist the Service Bus gateways. (These are the resources that actually accept the request into the Hybrid Connection and pass it through the Azure Relay system. Here's some architectural info .) The address of the Service Bus gateway is in the following format.
G#-prod-[stamp]-sb.servicebus.windows.net
"#" is a number between 0 and 127. Service Bus gateways are load balanced as load increases, so more are added dynamically up to a total of 128. (Going up to 128 gateways is extremely rare, but to be safe, you want to ensure you whitelist all of them.)
"[stamp]" is the name of the instance within your Azure data center where your Service Bus endpoint exists. You can find out the stamp using nslookup on the Service Bus endpoint. In the figure below, you can see the output of nslookup for the Service Bus endpoint shown in the figure above.
[caption id="attachment_2925" align="alignnone" width="580"] 
In this case, my stamp is sn3-010 . Therefore, to whitelist my Service Bus namespaces, I would want to whitelist URLs like this:
G0-prod-sn3-010-sb.servicebus.windows.net
G1-prod-sn3-010-sb.servicebus.windows.net
G2-prod-sn3-010-sb.servicebus.windows.net
G3-prod-sn3-010-sb.servicebus.windows.net
. . .
G126-prod-sn3-010-sb.servicebus.windows.net
G127-prod-sn3-010-sb.servicebus.windows.net
If you're lucky, you can whitelist using a wildcard, but if not, whitelist them all.
Back to Top
When Using SQL Express, Don't Use Named Instances and Enable TCP/IP
If you're using your Hybrid Connection to connect to SQL Server Express Edition, make sure that you use the Default instance and not a named instance. (More information here .)
You also want to ensure that you've enabled TCP/IP so that SQL Server Express can accept remote connections. Find out more about that here .
Back to Top
When Using SQL Server, Configure it for a Static Port
If you're using your Hybrid Connection to connect to SQL Server, make sure that you configure SQL Server to listen on a static port. Find out more about that here .
Back to Top
Use the Correct Connection String
Make sure that your connection string is using the correct server name. Just as when you created your Hybrid Connection endpoint, when you are configuring the connection string in your app, you typically want to use just the hostname of the machine running the resource your connecting to. In other words, use the same connection string that you would use in your Web App if it were being hosted on-premise. In fact, that's one of the great things about Hybrid Connections; you don't have to change your connection string when you move from development on-premise to staging and production in the cloud.
Back to Top
If your status is "Connected" but the connection isn't working, check connectivity to Service Bus
Assuming you aren't using a Classic Hybrid Connection, if your status shows "Connected" but your Hybrid Connection isn't working, it might be because you don't have connectivity to Service Bus from the machine where the Hybrid Connection Manager is running. This could be because of problems in your network, or it could be because of a transient problem in Azure. To check Service Bus connectivity, you can use Telnet or PowerShell.
To test using Telnet, open a command prompt on the machine where the Hybrid Connection Manager is running (you'll need to do this as an administrator) and run the following command, replacing ServiceBusNamespace with your Service Bus namespace's name.
telnet
ServiceBusNamespace
.servicebus.windows.net 443
To test using PowerShell, open PowerShell as an administrator and run the following command, replacing ServiceBusNamespace with your Service Bus namespace's name.
Test-NetConnection -computer
ServiceBusNamespace
.servicebus.windows.net -Port 443
If this test fails, it's possible that your network is blocking the outbound traffic. Check with your network administrator. It's also possible that there is an issue in Azure. You can check the Azure Status Page for any current issues.
Back to Top
Update your Hybrid Connection Manager
If you are running a version of the Hybrid Connection Manager earlier than Version 0.7.5, you should update. As of Version 0.7.5, we have added a feature that will notify you if there is an update. Prior to Version 0.7.5, there was no update notification.
Keeping the Hybrid Connection Manager updated is important in order to avoid any problems. You can click the "Download Hybrid Connection Manager" link in the Azure portal to update. You can also browse to https://go.microsoft.com/fwlink/?linkid=841308 to download the latest version.
Back to Top
Classic Hybrid Connections are End of Life on May 31, 2018
If any of your existing Hybrid Connections are Classic Hybrid Connections (the ones that were based on BizTalk), you'll want to make plans to update them to Azure Relay Hybrid Connections as soon as possible. As of May 31, 2018, Classic Hybrid Connections will no longer be supported.
You can read about this change and how you can migrate your BizTalk Hybrid Connections to Azure Relay in Christina Compy's blog post .
Back to Top