Posted on

Solving Error : BAM deployment failed : The locale identifier (LCID) 8192 is not supported by SQL Server

When trying to deploy a BAM activity on a BizTalk Server 2020 machine, I had the following error: BAM deployment failed : The locale identifier (LCID) 8192 is not supported by SQL Server

Error Description

The following BAM command:

bm deploy-all -DefinitionFile:MyActivity.xml

Returns the following error:

Deploying Activity… ERROR: The BAM deployment failed.
A .NET Framework error occurred during execution of user-defined routine or aggregate "deploy_project_internal":
System.Data.SqlClient.SqlException: The locale identifier (LCID) 8192 is not supported by SQL Server.
System.Data.SqlClient.SqlException:
at System.Data.SqlClient.SqlConnection.OnError(SqlException exception, Boolean breakConnection, Action1 wrapCloseInAction) at System.Data.SqlClient.SqlInternalConnectionSmi.EventSink.DispatchMessages(Boolean ignoreNonFatalMessages) at System.Data.SqlClient.SqlDataReaderSmi.InternalNextResult(Boolean ignoreNonFatalMessages) at System.Data.SqlClient.SqlDataReaderSmi.NextResult() at System.Data.SqlClient.SqlCommand.RunExecuteReaderSmi(CommandBehavior cmdBehavior, RunBehavior runBehavior, Boolean returnStream) at System.Data.SqlClient.SqlCommand.RunExecuteReader(CommandBehavior cmdBehavior, RunBehavior runBehavior, Boolean returnStream, String method, TaskCompletionSource1 completion, Int32 timeout, Task& task, Boolean& usedCache, Boolean asyncWrite, Boolean inRetry)
at System.Data.SqlClient.SqlCommand.RunExecuteReader(CommandBehavior cmdBehavior, RunBehavior runBehavior, Boolean returnStream, String method)
at System.Data.SqlClient.SqlCommand.ExecuteScalar()
at Microsoft.SqlServer.IntegrationServices.Server.ServerConnectionControl.GetServerProperty(String propertyName)
at Microsoft.SqlServer.IntegrationServices.Server.ServerConnectionControl.GetSchemaVersion()
at Microsoft.SqlServer.IntegrationServices.Server.ISServerExecArgumentBuilder.ToString()
at Microsoft.SqlServer.IntegrationServices.Server.ServerApi.DeployProjectInternal(SqlInt64 deployId, SqlInt64 versionId, SqlInt64 projectId, SqlString projectName)

After a little bit of Googling, I found someone having a different issue but with what looked like the same root cause (see Marc van der Wielen blog post here).
I detail the solution here again in case that one day Marc’s blog goes down. All credit goes to him.

Error root cause

The root cause of the problem is that the Service Account running the SQL Server instance is using an (apparently) unsupported locale setting.

In my case, my Windows 10 machine is configured with en-BE (English-Belgium) locale. I installed MS SQL Server with mostly all default options. By doing so, the Service Account created by the installer took the en-BE locale setting.
Once I changed the locale setting of the Service Account to en-US, the error hereabove disappeared.
It looks like while SQL Server did run fine for everything so far, it needs to have the local settings of the Service Account set to en-US for some specific functionalities to work properly (such as publishing a BizTalk BAM Activity in my case).

Resolution Procedure

1. Find what is the Service Account running the MS SQL Server service.
We can find that easily by running services.msc from a prompt.
When we find the SQL Server service, we can just look at its properties to see the name of the Service Account used to run it:

Finding SQL Server Service Account Name

2. Find the SID (Security Identifier) of the Service Account.
One way to do this is through the registry:
– Open the registry by running regedit from a prompt.
– Once in the registry editor, navigate to the following registry node: Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList
– The registry node contains a list of nodes having SIDs as name. Find the node for which the ProfileImagePath‘s entry contains the MSSQLSERVER value. Write down the SID, in my case it is S-1-5-80-3880718306-xxxxx.

Another way to find the SID is to use PowerShell:
The PowerShell command is slightly depending of the type of account running the SQL Service (local account or domain account), see details here.

For local accounts:
>$objUser = New-Object System.Security.Principal.NTAccount("NT Service\MSSQLSERVER")
>$strSID = $objUser.Translate([System.Security.Principal.SecurityIdentifier])
>$strSID.Value

For Domain account we get the NTAccount object in the following way:
>$objUser = New-Object System.Security.Principal.NTAccount(DOMAIN_NAME, USER_NAME)

3. Change the Service Account locale setting.
Navigate to the following registry node folder (using your own SID from the previous step): Computer\HKEY_USERS\S-1-5-80-3880718306-xxx\Control Panel\International.
– Set the Locale entry value to “00000409“
– Set the LocalName entry value to “en-US“
– Restart the SQL Server Service.

Set SQL Server Service Account Locale

Setting the local setting for new user accounts to be of a particular locale

To avoid having this kind of issue, it is possible to tell Windows to set the default locale for new accounts. This option is in the Control Panel -> Regions -> Administrative -> Welcome screen and new user accounts.

This is also scriptable. See : https://docs.microsoft.com/en-US/troubleshoot/windows-client/deployment/automate-regional-language-settings

Posted on

BizTalk WCF Metadata Only MEX Endpoint Error: Root element is missing

In a BizTalk 2016 application, I have a receive location using the WCF-NetTcp adapter. The receive location is using an in-process Receive Handler and so I used the BizTalk WCF Service Publishing Wizard to publish a Service Metadata Endpoint (MEX) hosted in IIS so that clients can retrieve the WSDL of the web service exposed.
Note that typically, a BizTalk isolated host is an IIS Application Pool instance: w3wp.exe.

Endpoint error: Root element is missing

Once the MEX endpoint is deployed in an IIS application, I saw the following error when browsing to the endpoint:

Server Error in ‘xxx’ Application.
Root element is missing. 
Description: An unhandled exception occurred during the execution of the current web request. Please review the stack trace for more information about the error and where it originated in the code. 
Exception Details: System.Xml.XmlException: Root element is missing.
Source Error: 
An unhandled exception was generated during the execution of the current web request. Information regarding the origin and location of the exception can be identified using the exception stack trace below.

Windows Event Log Analysis

When looking at my Windows Event Log, I saw the following error:

Server Error in ‘xxx’ Application.
WebHost failed to process a request.
Sender Information: System.ServiceModel.ServiceHostingEnvironment+HostingManager/4032828
Exception: System.ServiceModel.ServiceActivationException: The service ‘xxx.svc’ cannot be activated due to an exception during compilation. The exception message is: Root element is missing.. —> System.Xml.XmlException: Root element is missing.
at System.Xml.XmlTextReaderImpl.Throw(Exception e)
….
Process Name: w3wp

I looked further down in my event log and saw a series of warnings from the Enterprise SSO service with messages of the likes:

SSO AUDIT
Function: GetConfigInfo ({CB480FD2-902B-4F1E-A2DB-43B3954A341B})
Tracking ID: 1c44a765-61a3-4679-901d-f1853fb2f497
Client Computer: BTS2016 (wmiprvse.exe:8432)
Client User: IIS APPPOOL\BizTalkIsolatedHostAppPool
Application Name: {315B6926-BF0C-462D-A8FD-5512F5E41456}
Error Code: 0x80070005, Access is denied.

And:

Access denied. The client user must be a member of one of the following accounts to perform this function.
SSO Administrators: SSO Administrators
SSO Affiliate Administrators: SSO Affiliate Administrators
Application Administrators: BizTalk Server Administrators
Application Users: –
Additional Data: IIS APPPOOL\BizTalkIsolatedHostAppPool {315B6926-BF0C-462D-A8FD-5512F5E41456} WCF-NetTcp_RL_BizTalkServerApplication_{315B6926-BF0C-462D-A8FD-5512F5E41456}

The first thing I noticed in the SSO warnings here above is that they refer to the user “IIS APPPOOL\BizTalkIsolatedHostAppPool” which in my case is the identity of the Application Pool running my WCF Service metadata endpoint.
In IIS 7.5 and above, each Application Pool is by default assigned it’s own virtual account and it’s named using the following pattern: “IIS AppPool\<ApplicationPoolName>” (i.e. this is the name of the virtual account in Windows). In the Application Pool setting, the virtual account name is simply referenced to by setting the identity property to “ApplicationPoolIdentity“.

I already had this account part of the BizTalk Isolated Host Users Windows Group but it seems to not be enough as Enterprise SSO is complaining.

At this stage I did some research and found a clue here but, for security reason, I was not satisfied with having the App Pool Service Account being part of BizTalk Server Administrators Windows Group.
I dug a little deeper and found this interesting blog post. This made me check the BizTalk documentation and it is indeed now documented that BizTalk Host Instance Accounts and BizTalk Isolated Host Instance Accounts must be part of the SSO Affiliate Administrators Windows Group.

Final Solution

Finally, what I did to solve the issue was to add the Application Pool identity to the SSO Affiliate Administrators Windows Group (as it is actually instructed in the BizTalk’s documentation!) and rebooted my machine.

Nevertheless, my personal opinion is that while it is the supported solution documented by Microsoft, the root of the problem lies in the implementation of ISSOConfigStore::GetConfigInfo and that Microsoft should fix that or change the way MEX endpoints retrieve data. Indeed, to me, it does not really make sense that an IIS App Pool should run under an account being an SSO Afiliate Administrator.

Note: I did not have to modify the web.config of the WCF Service MEX endpoint web service generated by the BizTalk WCF Service Publishing Wizard as was mentioned in one of the blog I referenced to:
<system.web>
    <trust level=”Full” originUrl=”” />
</system.web>

Posted on

Testing firewall rules on Windows for TCP ports with Telnet

Often times we need to test connectivity on environments to prove that firewall rules have been implemented correctly and it often has to happen before software is installed and configured on the servers.
Firewall rules are implemented by network engineers to let network traffic go through between different computers. The rules have a direction, which means that a rule is setup to allow traffic originating from a computer A (client) to a destination computer B (server) on a certain port of the destination machine. To allow traffic originating from the computer B to computer A, another rule would need to be created.

We will be testing firewall rules to prove that there is TCP connectivity across two machines separated by a firewall. To do that on a Windows OS for the TCP protocol, we can use the Telnet client tool. From the Windows Command Prompt, the command is the following:
telnet <DestinationIpAddress> <DestinationPortNumber>
The Telnet Client tool is not installed by default on Windows and if the command is not recognized on the computer you are on, you can install the Telnet Client tool following the steps defined in the following Technet article: Install Telnet Client. Telnet Client is a Server Feature on Server OS and a Windows Feature on Client OS (Windows 7, 8, 10…).

The problem is that if we use the Telnet command to a port on which no process runs, the Telnet command will fail and we won’t know if Telnet failed due to either:

  • The firewall blocking the connection.
  • The firewall letting the traffic through but there is no process listening on the specified port at the destination server.

The error message is the same in both case and looks like the following:
Connecting To x.x.x.x...Could not open connection to the host, on port xxx: Connect failed
Telnet command failing Telnet command failing

So the obvious resolution is to have a process listening on the specified port and it is where a tool like the Port Listener tool comes in handy. This tool can be configured to listen to TCP or UDP network traffic on any port.
All we need to do is to run Port Listener on the destination computer we want to test connectivity to, configure it to listen on a particular port and then run Telnet from the client server machine.

In the example hereunder we want to test if the TCP port 636 (used for LDAPS protocol) is open.

1. Start Port Listener to listen on TCP port 636 on the destination server:
The screenshot hereunder is an old version of Port Listener which supports only TCP, so make sure to download the latest version which also supports listening for UDP traffic.
Start Port Listener
Port Listener v 1.02 offers the choice to listen to either TCP or UDP traffic:
Start Port Listener

2. Execute the Telnet command from the client server:
Telnet Client Tool

… which now succeeds as Port Listener is running on the server:
Telnet Client Tool succeeds

Posted on

Cloning (getting) code from Git repository to Visual Studio.

Cloning (getting) code from Git repository to Visual Studio.

There are lots of open source projects hosted on Git repositories as well as bloggers and authors publishing demos, patterns and code samples on web-hosted Git repositories such as GitHub, Bitbucket, Codeplex (Note: Codeplex has several source control options and Git is just one of them)….
It is a very convenient way to distribute code samples so that developers can browse the code through Visual Studio and eventually run it and toy with it.

Nevertheless, I often see people getting code from Git repositories by downloading a zip file, unzipping it and then opening it up in Visual Studio. This is fine but there is actually a better way to grab code from Git repositories through Visual Studio.
The technical term to get code from a Git repository for the first time is to clone the repository. I will here under demonstrate how to get code hosted on a Git repository for the first time (aka clone the repository).
If you have never used Git repositories, you can check previous articles I wrote on the topic and notably where I detail Git support for various versions of Visual Studio: Git TFS Visual Studio Integration.

The sample hereunder shows how to clone a Git repository from GitHub but the principle is the same for every Git repositories:

1. Getting the clone link from the Git repository:

GitHub Clone Link

2. Cloning the repository from Visual Studio:

In Visual Studio 2012 or above, open Team Explorer and click on the Connection button:
VisualStudio Team Explorer Connect
Under the Local Git Repositories section, click the Clone link and paste the link copied in the previous step. Choose a folder on your local machine to copy the code to. Finally, click the Clone button located under.
VisualStudio Clone Git Repositories

3. Opening the Visual studio solution from the cloned repository:

Once the Git repository is cloned, it means it has been downloaded on the local machine and Visual Studio’s Team Explorer window will display the message “The repository was cloned successfully”.
In Visual Studio 2012, there is no direct way to open the cloned Visual Studio solution so we have to right-click the cloned repository and click the option Open in File Explorer to find the Visual Studio solution from the file system:
Visual Studio 2012 Open File Explorer
In Visual Studio 2013, Visual Studio integration with Git is better and we can open the solution directly from Visual Studio. To do so, first open the cloned repository by double clicking on it:
VisualStudio 2013 Open Git Repository
Once in the local Git repository, Visual Studio’s Team Explorer will display the Visual Studio solution and we can double click on it to open it:
VisualStudio 2013 Open VS Solution from Local Repository

Posted on

Getting started with Azure BizTalk Services

In this article I will explain on getting started with Azure BizTalk Services.
There are quite a few tutorials on the internet but many are outdated since the February 2014 release of Azure BizTalk Services. Moreover, many are not detailed enough for the beginner or do not cover all the necessary aspects to have a complete system ready for development. My aim is to fill this gap and provide a complete, beginner-friendly guide to getting started with Azure BizTalk Services.
Consequently, this tutorial will cover both:
– How to provision a BizTalk Service in the Azure Portal.
– How to install and configure the necessary bits for the development machine so that we can develop Azure BizTalk Services.

I will also focus on some specific aspects related with a playground or development environment and thus considering cost aspects, which are also important for a personal playground environment. We indeed do want to optimize the spending of our hard-earned cash!

Azure BizTalk Services dependencies

First of all it is important to know that BizTalk Services has dependencies on other Azure Services, some of which also have a cost:

  • Azure SQL Database: This is where the Tracking data is stored. See SQL Database Pricing Details
  • Azure Storage: Archived messages are stored in Azure Blobs and Monitoring data is stored in Azure Tables. See Storage Pricing Details
  • Azure Access Control Namespace: The Access Control Namespace is automatically created when provisioning a BizTalk Service instance (deployment). This namespace is used by Visual Studio to deploy a BizTalk Service project to the BizTalk Service deployment.

Cost considerations

<UPDATE>
Update: there is now a Free Edition of Azure BizTalk Services in Preview!
This tutorial can nevertheless still be used for all editions. The only consequence of the Free Edition on this tutorial is that the actual provisioning of the BizTalk Service is simplified. I cover Azure provisioning in paragraphs 1.1, 1.2 and 1.3 in this article and so only these 3 paragraphs are affected (and simplified). For playground environment it is obviously advisable to first use the Free Edition and go for a Developer Edition when you need some features not covered in the Free Edition. Indeed, at time of writing, the Free Edition is still missing many features. See the BizTalk Services Editions Chart.
</UPDATE>

Azure BizTalk Services is a PaaS service and as with all cloud services, the pricing is on a per-usage basis.

Azure BizTalk Services comes in several editions (Developer, Basic, Standard, and Premium), see BizTalk Services Editions Chart. Each edition has a different pricing, see BizTalk Services Pricing Details.

Azure BizTalk Services is pricey for a playground environment as, at time of writing, the cheapest subscription (the Developer edition) costs 0.097 EUR / hour, which is about 2.328 EUR / day and amounts to close to 73 EUR / month. So, once we are done with the playground it is advisable to take the BizTalk Service down.
A Backup and Restore functionality exist for BizTalk Services but it is not available for BizTalk Service Developer Edition, it is only available for other editions. This feature would come in handy to avoid paying for the BizTalk Service when we don’t use it so I wish it would also be available for the Developer edition.
<UPDATE>
Update: A Backup/Restore feature is now available for the Developer edition!
At this time, only the free Edition does not cover Backup and Restore. Moreover, a lot of the MSDN documentation still mentions that the Developer edition cannot do backup/restore but I have had a look and it seems to work.
</UPDATE>

On top of the cost of the BizTalk Service, 2 other dependencies incur cost as well: Azure SQL Databases and Azure Storage.
While, at time of writing, the smallest SQL Azure Database edition is quite cheap (3,72 EUR / month for a 100 Mb Web Edition SQL Database), it is possible to have an Azure SQL Database for free which is even better for people who neither have their own MSDN account (which comes with free Azure credit) nor have access to one at the office.
So, if all you want to do is to experiment a little with BizTalk Services, the free database will be enough. It is unfortunately not possible to create a free SQL Database from the SQL Database section of the Azure Portal. At time of writing, the only way I know of is to create it from the from the Web Sites section of the Azure Portal.

The SQL Database section of the Azure Portal does not allow for free Database creation:
SQL Database section of Azure portal does not allow for free Database creationThe Web Sites section of the Azure Portal allows for free SQL Database creation:
Web Sites section of Azure portal allows for free SQL Database creation

With this information in hand, you can choose to either go for the free (but extra small) SQL database or go for a paid one.

I will now explain how to provision a BizTalk Service instance through the Azure management portal and how to get the development environment ready. Note that a BizTalk Service instance is also referenced to as a BizTalk Service deployment in the documentation.

1. Provisioning an Azure BizTalk Service Deployment

1.1. Create a SQL Database.

The first step is to create a SQL Database, especially if we choose to go for a free SQL Database. This is because as I have explained earlier, at time of writing, the only way to create one through the portal is by creating a free Web Site.

1.2. Create a Storage.

The second step is to create an Azure Storage. We can also optionally choose to create it later as the BizTalk Service creation wizard offers the possibility to create one with default settings (notably, the replication model is “geo redundant” but that can be changed afterwards). The level of redundancy drives the price, the cheapest being “locally redundant”.

For obvious cost and performance reasons, we should create SQL Database and Storage deployments in the same region as the BizTalk Service.

Note that on a production environment, we would want to create Storage and SQL Database exclusively to be used by BizTalk Services. Nevertheless, for a playground environment, we can re-use existing SQL Database and Storage so that we lower cost to as little as possible.

1.3. Create a BizTalk Service deployment.

The third step is to create the BizTalk Service deployment (instance).

  • In the Azure Management portal, click on BizTalk Services on the left panel and then click either on the New or Create a Biztalk Service link. This will prompt the Create BizTalk Service wizard to pop up.Azure Portal BizTalk Services section
  • In the Create BizTalk Service wizard first page we define:
      • A (unique) Name for the BizTalk Service deployment.
      • The BizTalk Service edition. At time of writing, there are 4 editions: Developer, Basic, Standard and Premium. In the scenario of a playground deployment, the Developer edition will be enough.
      • The region we want to create the BizTalk Service in.
      • Create or re-use and existing SQL Database instance to hold the Tracking database. If we use an existing SQL Database instance, make sure that it is in the same region as the BizTalk Service we are currently creating. In my playground deployment, I have chosen to use an existing SQL Database instance (a free 20 Mb SQL Database instance).

    Create BizTalk Service wizard first page

  • In the second page of the wizard, Database Settings, we set the necessary credentials to connect to the SQL Database instance which will hold the Tracking Database.Create BizTalk Service wizard Database Settings
  • In the third and last page of the wizard, we set the storage account used to store monitoring data and archived messages. We can either choose and existing storage account (which should be in the same region as the BizTalk Service instance we are creating) or create a new one.Create BizTalk Service wizard Archiving Storage Settings

Once we click the final button, the deployment takes about 30 minutes to complete.

1.4. Get BizTalk Service credentials (ACS).

Once the BizTalk Service is provisioned, we want to write down the ACS ( Access Control Service) credentials. To do so, when the BizTalk Service is selected, click on the Connection Information button at the bottom of the Azure Portal:
BizTalk Service Connection Information
The Access Connection Information panel opens, take note of the Default Issuer and Default Key values. We will use them later to configure the BizTalk Service portal.BizTalk Service Access Connection Information

1.5. Registration of the BizTalk Service to the Azure BizTalk Services portal.

The Azure BizTalk Services Portal is a specific management portal for BizTalk Services where we can:
– Manage the various artifacts deployed to the BizTalk Service subscription (schemas, transforms,…).
– Manage B2B operations (EDI and X12): Manage Partners (called Party in BizTalk Server) and Agreement (also called Agreement in BizTalk Server).
See Using the BizTalk Services Portal for more information on the Azure BizTalk Services portal.

To register the BizTalk Service deployment to the portal:

  • In the Azure Portal, select the concerned BizTalk Service and click on the Manage link at the bottom of the screen.BizTalk Service Manage
  • The Azure BizTalk Services Management portal opens where we will put in the ACS Issuer name and ACS Issuer secret. These are the values we copied from the Connection Information screen the previous step 1.4 (there, the fields are called Default Issuer and Default Key). Once issuer and key values are copied, click Register.BizTalk Services Portal Registration

Once we have registered The BizTalk Service Deployment, we have access to the Azure BizTalk Services portal for BizTalk Service we have just created:BizTalk Services Portal

2. Setting up the Development environment: installing the Azure BizTalk Services SDK.

In this section I will cover the procedure to do a complete installation of the Azure BizTalk Services SDK on a development environment.

2.1. Download the SSL certificate of the BizTalk Service Depoyment.

Once you have created a BizTalk Service, the endpoint of the BizTalk Service is a URL in the following format: <BiztalkServiceName>.biztalk.windows.net. For clients to be able to connect to the BizTalk Service deployment, a secure SSL connection must be established. As for playground/development environments, we can use the self-signed certificate which is automatically generated when creating an Azure BizTalk Service, we need to install it in the trusted Trusted Root Certification Authorities Store on every client/developer machine that needs connectivity to the BizTalk Service deployment. That way, the local machine(s) will accept the server certificate of the BizTalk Service deployment and the SSL connection will be possible. For production environment, we should request a certificate provided by a certificate authority (CA).

  • Download the self-signed public certificate (.cer) from the dashboard of the BizTalk Service. This certificate was automatically created when we provisioned the BizTalk Service deployment in the first part of this tutorial. In the BizTalk Service Dashboard, click on Download SSL Certificate:Azure Portal BizTalk Services Dashboard Certificate
  • Once the certificate is saved on disk, run the mmc command and add the Certificates snap-in for the Computer account:MMC Add Certificates Snap-In
  • We select the Local computer as this is the computer that will run the SDK and will need a secured connection (SSL) with the BizTalk Services deployment running in Azure Cloud:MMC Add Certificates Snap-In Select Local Computer
  • The final step is to add the certificate in the Trusted Root Certification Authorities certificate store:BizTalk Service Certificate Trusted Root Certification Authorities

2.2 Create a self-signed certificate for securing the BizTalk Adapter Service Runtime.

On the development machine, when installing the Runtime part of the Azure BizTalk Services SDK, an on-premise web service running in IIS is installed. It is called the BizTalk Adapter Service. The BizTalk Adapter Service is sometimes reference to by its acronym (BAS). Note that it is the same acronym as the retired BizTalk Server Business Activity Services (BAS) but of course not related.
The BAS web service needs to be secured and for that we need a self-signed certificate for which we have a private key (by contrast, the certificate downloaded from the portal is the certificate belonging to the BizTalk Service deployment and so contains only the public key). On a production environment we would want to use a certificate issued by a certificate authority to secure the BAS on-premise web service.

We will create a self-signed certificate for the machine where we will install the BAS web service runtime, which, for a typical development environment, is the development machine where we install the Azure BizTalk Services SDK.
So, as the development machine will run the BAS runtime, we will create a self-signed certificate for that development machine name:

  • Create the self-signed certificate that will be used secure the BAS Web service that will be created in IIS when installing BizTalk Adapter Service (which is part of the Azure BizTalk Services SDK runtime feature). The following line creates a certificate in the Trusted Root Certification Authorities of the Local Computer certificate store (parameter -sr LocalMachine and -ss root). Note that with Visual Studio 2012, makecert is located at: C:\Program Files (x86)\Windows Kits\8.0\bin\x64
    makecert -pe -r -n "CN=yourlocalmachinenamehere" -e "10/05/2018" -sr LocalMachine -ss root
  • Export the private key of the self-signed certificate from the certificate store. In the sample hereunder, the password of the private key is “Password”:
    certutil -exportPFX -p "Password" root yourlocalmachinenamehere yourlocalmachinenamehere.pfx
  • Import the certificate in IIS:
    • Open IIS Manager and double click on the Server Certificates icon:IIS Manager Server Features View
    • Right-click on the screen and select Import. In the Import Certificate pop-up Windows, select the private key (.pfx file) we exported in the previous step and enter the password. Leave the other default options as they are (Certificate Store “Personal” and checkbox “Allow this certificate to exported” ticked):IIS Import Certificate
    • The certificate is now visible in the Server Certificates section of IIS and in the Local Computer Personal Certificate Store:IIS Server CertificateLocal Computer Personal Certificates Store

2.3. Installing the Azure BizTalk Services SDK.

The Azure BizTalk Services SDK contains the necessary bits to create BizTalk Services project in Visual Studio as well as other necessary binaries .
The SDK contains 3 main features:
– The developer SDK which is used to develop BizTalk Services applications. It contains Visual Studio BizTalk Services project template (bridges) and BizTalk Services Artifacts project template (transforms and schemas). This feature is installed on development machines only.
– The Runtime which manages connectivity between Azure BizTalk Services applications and the on-premise Line-Of-Business (LOB) application. If the Azure BizTalk Services application does not need to connect to an on-premise application, this component does not need to be installed. This feature is installed wherever we need the runtime, typically production and development machines.
– The Tools which includes Windows PowerShell cmdlets to manage both the BizTalk Adapter Service Runtime components and the deployed BizTalk Services applications. This feature is installed on both production and development machines.

The requirements to install the Azure BizTalk Services SDK are:

  • Windows 7 and up or Windows 2008 R2 and up.
  • The .Net Framework 3.5.1 and 4.5. To check if you are running .Net 4.0 or 4.5, which is not that straightforward as they both show up as runtime v4.0.30319 in IIS and in C:\Windows\Microsoft.NET\Framework (the reason being that 4.5 is an in-place upgrade from 4.0, not a side-by-side install with 4.0), we can either:
    • Look in the Registry:Framework .Net 4.5 Registry
    • Check Windows Server Roles and Features (or the Windows Features on client versions of Windows):Windows Features Framework 4.5Windows Client Features Framework 4.5
  • Windows PowerShell 3.0 or above(run the $PSVersionTable command in PowerShell to check which version you are running).
  • Visual Studio 2012. Visual Studio 2013 is not supported.
  • Make sure that Windows Authentication is Enabled in IIS (it was disabled by default on my machine)

Once we are sure we have all prerequisites, we can go ahead and install the Azure BizTalk Services SDK with the following procedure:

  • Download the Azure BizTalk Services SDK here. In the pop-up window. choose either WindowsAzureBizTalkServicesSetup-x64.exe or WindowsAzureBizTalkServicesSetup-x86.exe depending on the version of Windows installed (64 or 32 bit).
  • After having downloaded the adequate executable, run it as Administrator.
  • In the License Term screen, tick the checkbox “I accept the terms in the License Agreement” and click Next:Azure BizTalk Services Setup License Term
  • In the Features screen we choose which features we want to install. On a development machine we want all of them: The Developer SDK, the Runtime and the Tools. On a Production environment we would typically install only Tools and Runtime. Once the necessary features are selected, click Next.Azure BizTalk Services Setup Features
  • The Summary screen displays the components to install for the features selected in the previous screen. We can see that the components that are already installed on the machine have their Action set to None and the ones that still need to be installed have their Action set to Install. As I am installing the SDK on a machine where I have already installed BizTalk Server 2013 and the Adapter Pack, these components do not need to be installed anymore. Click Install:Azure BizTalk Services Summary
  • At some point, the BizTalk Adapter Service (BAS) setup procedure will start. This is a separate msi which is launched as part of the overall BizTalk Adapter Services Setup. The BizTalk Adapter Service is part of the on-premise Runtime feature of Azure BizTalk Services and is used for communication between Azure BizTalk Services and on-premise Line-Of-Business (LOB) applications. On the welcome screen, click Next:BizTalk Adapter Service Setup Welcome
  • In the End-User License Agreement screen, tick the checkbox “I accept the terms in the License Agreement” and click Next:BizTalk Adapter Service Setup License Agreement
  • In the Management Service Application Pool screen, we need to provide a service account which will run the Biztalk Adapter Service (BAS) IIS application pool (named BizTalk Adapter AppPool). The service account needs to have the Administrator role on the local machine and have access to the Internet. On my lab machine, I am using my own local account. A better practice is to create a service account and add it to the local Administrators Group instead of using a user account. Leave the Domain field blank if using a local account. After having entered the service account and password, click Next:BizTalk Adapter Service Setup Management Service Application Pool
  • In the Azure BizTalk Services Deployment Details screen, we need to input the URL of the BizTalk Services deployment instance we have created through the Azure Portal in the first part of this tutorial. The URL is in the form of: https://<deployment name>.biztalk.windows.net. The reason we need to give the BizTalk Service deployment URL is that the BizTalk Service solutions created in Visual Studio will use the BizTalk Service artifact store to keep the configuration settings of the BizTalk Adapter Service components (LOB Relays, LOB Targets,…). Click Next after having input the BizTalk Services deployment URL:BizTalk Adapter Service Setup BizTalk Services Deployment URL
  • In the Management Service Site Binding screen:
      • Tick the Use SSL to secure the management service checkbox to encrypt HTTP communication with the on-premise BAS Management Web Service with SSL.
      • Specify the SSL certificate that we created and imported in IIS in the previous step: Create a self-signed certificate for securing the BizTalk Adapter Service Runtime. Remember that for production environment we should use a certificate provided by a trusted certificate authority.
      • Specify the port number the BizTalk Adapter Service web service will be running on (this web service is installed in the local machine’s IIS). The default value is 8080. I chose a different port as I already had an IIS Website running on port 8080.
      • Click Next.

    BizTalk Adapter Service Setup Management Service

  • In the final screen, click Install:BizTalk Adapter Service Setup Install Ready
  • Once the BizTalk Adapter Service installation has completed, click Finish:BizTalk Adapter Service Setup Install Finish
  • We are now back on the Windows Azure BizTalk Services Setup screen, click Finish:Azure BizTalk Services Setup Finish

Note on BAS:
We can see that a Web site called BizTalk Adapter Service has been created in IIS and that it contains a single web service application called BASService, itself containing a single web service which is the Management Service of BAS (BizTalk Adapter Service) which is used for runtime connectivity with the Azure cloud. See BizTalk Adapter Service on MSDN for more information.
BizTalk Adapter Service IIS Web AppWe can also see the BizTalk Adapter AppPool application pool created to run BAS management service.BizTalk Adapter Service IIS AppPool

2.4 Configuring the BizTalk Adapter Service.

As creating LOB Targets to access from the cloud is done through Server Explorer in Visual Studio and as Visual Studio is doing this task through the BAS Management Service installed in IIS, we must configure Visual Studio with the management service accordingly.

  • Launch Visual Studio 2012 and open Server Explorer.
  • Expend the BizTalk Adapter Services node and see the BAS management service installed in the previous step. It was automatically added for me but if it is not, you can add it manually.Visual Studio Server Explorer BizTalk Adapter Services
  • Click on the service and you will be prompted for the ACS credentials of the Azure BizTalk Services deployment instance. We get these from the Azure Portal as I explained in the previous step (1.4). Once the ACS credentials are copied, click Ok.Visual Studio Server Explorer BizTalk Adapter Services ACS
  • Once the credentials are set, we can expend the BAS management service node to see the various LOB Types:Visual Studio Server Explorer BizTalk Adapter Services LOB Types

3. Final Notes.

3.1. Installing BizTalk Adapter Service failure.

Installing BAS fails with the following error when the BAS certificate is not created or installed properly as explained in the installation step Create a self-signed certificate for securing the BizTalk Adapter Service Runtime.

The Windows Application Event Log shows the following message:

Windows Installer installed the product. Product Name: Microsoft BizTalk Adapter Service. Product Version: 2.0.40214.0. Product Language: 1033. Manufacturer: Microsoft Corporation. Installation success or error status: 1603.

Note that the event is not written in the Application Event Log as an Error but as an Information level event.

In the log file created by the Azure BizTalk Services setup, the following error is written:

SBConnectCA: ERROR: System.Runtime.InteropServices.COMException (0x80070520): A specified logon session does not exist. It may already have been terminated. (Exception from HRESULT: 0x80070520)
at Microsoft.Web.Administration.Interop.IAppHostMethodInstance.Execute()
at Microsoft.Web.Administration.Binding.AddSslCertificate(Byte certificateHash, String certificateStoreName)
at Microsoft.Web.Administration.BindingManager.Save()
at Microsoft.Web.Administration.ServerManager.CommitChanges()
at Microsoft.ApplicationServer.Integration.AFConnect.IISHelper.CreateWebsite(String websiteName, String physicalPath, String appPoolName, String certificateThumbprint, Int32 port)
at Microsoft.ApplicationServer.Integration.AFConnect.Program.Configure(Session session)

3.2. SQL Server dependency removed.

Some of the documentation / internet resources still mention about a dependency on SQL Server:
– A software requirement to have SQL Server installed on-premise.
– The service account running the BizTalk Adapter AppPool IIS application pool to have sysadmin role on the on-premise SQL Server.
Since the release of Azure BizTalk Services February 2014 Update, LOB artifacts are not stored on an on-premise instance of SQL Server anymore but on Azure SQL Databases instead. Consequently, the SQL Server dependency has disappeared.

3.3. Error when browsing to the BAS Management Service.

If you try to browse to the BAS Management web service and there is a certificate error, that is because either:
– You browse through localhost instead of the machine name.
– The certificate you created does not correspond to the machine name. When creating the certificate in step Create a self-signed certificate for securing the BizTalk Adapter Service Runtime, makecert.exe takes the parameter -n “CN=yourlocalmachinenamehere”, CN is the acronym for Common Name. The CN for a website is the host + the domain name (such as www.microsoft.com). For a single machine on an internal network, the CN can just be the machine name.
Azure BizTalk Services Management Service Certificate Error
When browsing through to the machine name which corresponds to the CN of the certificate, there is no certificate error:
Azure BizTalk Services Management Service Request Error
The Request Error is normal as the BAS management service is not browsable, it can only be accessed when presenting the ACS credentials which is not possible through a browser.

Further documentation and references:

Provisioning BizTalk Service
Install Azure BizTalk Services SDK
BizTalk Adapter Service Installation
Azure BizTalk Services Resources on the TechNet Wiki (Lots of resources here!)
Official MSDN BizTalk Services documentation
BizTalk Services on the Microsoft Azure Site: BizTalk Services