Walkthrough: Configuring the Message Bus role to use Azure Service Bus

Version: 10.4

Before you can configure the Message Bus role to use Azure Service Bus, you must provision Azure Service Bus and get the primary connection string. See the Microsoft Create a Service Bus namespace using the Azure portal documentation for details.

This walkthrough describes how to:

Change the messaging connection strings

You must change the messaging connection string from Microsoft SQL Server to Azure Service Bus on all roles that references the Message Bus role.

To change the messaging connection string:

In the <wwwroot>\App_Config\ folder, open the ConnectionStrings.config file.
Locate the add name="messaging" property and change the connectionString attribute to the Azure Service Bus connection string.
RequestResponse
```
<add
  name="messaging"
  connectionString="<your Azure Service Bus connection string>" />
```
Save the ConnectionStrings.config file.
Repeat the procedure for all relevant roles.

Change the messagingTransport keys

You must change the messagingTransport key from Microsoft SQL Server to Azure Message Bus on all Core roles that references the Message Bus role.

To change the messagingTransport key:

In the <wwwroot>\ folder, open the Web.config file.
Locate the add key="messagingTransport:define property and change the value attribute from SQL to AzureServiceBus.
RequestResponse
```
<add key="messagingTransport:define" value="AzureServiceBus" />
```
Save the Web.config file.
Repeat the procedure for all relevant roles.

Switch the messaging configuration files

You must switch all messaging configuration files from Microsoft SQL Server to Azure on all XP service roles that references the Message Bus role. The configuration files are in the following folders:

<wwwroot>\App_Data\Config\Sitecore\ and its subfolders
<wwwroot>\App_Data\jobs\continuous\*\App_Data\Config\sitecore\ and its subfolders

To switch messaging configuration files:

Add the .disabled extension to all files matching *Messaging.SqlServer.xml.
RequestResponse
```
*Messaging.SqlServer.xml -> *Messaging.SqlServer.xml.disabled
```
Remove the .disabled extension from all files matching *Messaging.Azure.xml.disabled.
RequestResponse
```
*Messaging.Azure.xml.disabled -> *Messaging.Azure.xml
```
Repeat the procedure for all relevant roles.

Configure the Message Bus role for use with containers

If you are using containers to deploy Sitecore, you must perform this additional procedure.

Important

The procedure and scripts provided here are examples that you can edit and adjust to your Sitecore installation. They are not supported and only meant for your inspiration.

To configure the Message Bus role for use with containers:

Prepare Sitecore to be deployed to containers through a shared docker-compose.yml file.
For each role that uses Messaging:
- In the folder that contains your *.ps1 and Docker files, build a new Docker image for the role by running this command: docker build --tag sitecore-<VERSION>-<ROLE NAME>-asb <PATH TO YOUR FOLDER>.
- In the docker-compose.yml file, change the image setting from ${SITECORE_DOCKER_REGISTRY}sitecore-<VERSION>-XX:${SITECORE_VERSION} to sitecore-<VERSION>-<ROLE NAME>-asb.
In the docker-compose.yml file, change Sitecore_ConnectionStrings_Messaging to the primary connection string of your Azure Message Bus (Endpoint=<XXX>;SharedAccessKeyName=<XXX>;SharedAccessKey=<XXX>).

Create a file named enable-messaging-asb.ps1 and paste in the following example PowerShell script:

RequestResponse

Function Set-XmlAttribute(
  [string]$XmlFilePath,
  [string]$Xpath,
  [string]$AttributeName,
  [string]$Value)
{
  Write-Host"Setting XML attribute [$AttributeName] with value [$Value] from [$XmlFilePath] using xPath [$XPath]"
  [xml]$XmlFile = Get-Content $XmlFilePath
  $Item = Select-XML -Xml $XmlFile -XPath $XPath
  if($Item -ne $null) {
    $node = $Item.node
    $Item | %{$_.node.$AttributeName = $Value}
    $XmlFile.Save($XmlFilePath)
  } else {
    Write-Host "Node is not exist in $XmlFilePath, XPath: $XPath" -Level "Warning"
  }
}

Write-Host "Disabling *Messaging.SqlServer.xml ..."
Get-ChildItem -Path "." -Filter "*Messaging.SqlServer.xml"  -Recurse | ForEach-Object {
  $newName = "$($_.FullName).disabled";
  Write-Host $newName
  Move-Item -Path $_.FullName -Destination $newName -Force
}
Write-Host "Disabling *Messaging.SqlServer.xml done"

Write-Host "Enabling *Messaging.Azure.xml.disabled ..."
Get-ChildItem -Path "." -Filter "*Messaging.Azure.xml.disabled"  -Recurse | ForEach-Object {
  $newName = $_.FullName.Substring(0, $_.FullName.LastIndexOf(".disabled"));
  Write-Host $newName
  Move-Item -Path $_.FullName -Destination $newName -Force
}
Write-Host "Enabling *Messaging.Azure.config.disabled done"

Write-Host "Updating Web.config"
$currentFolder = Get-Location
Set-XmlAttribute -XmlFilePath "$currentFolder\Web.config" -xpath "//configuration/appSettings/add[@key='messagingTransport:define']" -AttributeName "value" -Value "AzureServiceBus"
Write-Host "Web.config is updated"

Run the following Docker file:

RequestResponse

FROM ${BASE_IMAGE}
COPY ./enable-messaging-asb.ps1 ./
RUN .\enable-messaging-asb.ps1

Deploy your images.

Do you have some feedback for us?

If you have suggestions for improving this article,