---
title: "Walkthrough: Configuring the Message Bus role to use Azure Service Bus"
slug: "walkthrough--configuring-the-message-bus-role-to-use-azure-service-bus"
abstract: "How to configure the Sitecore Message Bus role to use Azure Service Bus."
---
# Walkthrough: Configuring the Message Bus role to use Azure Service Bus

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](https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-create-namespace-portal) documentation for details.

This walkthrough describes how to:

- [Change the messaging connection strings](https://doc.sitecore.com/xp/en/developers/92/platform-administration-and-architecture/walkthrough--configuring-the-message-bus-role-to-use-azure-service-bus.html#UUID-0f18655b-0928-974b-225f-38be2fb5c4ca_section-idm4525572914964831621252233593 "Change the messaging connection strings")
- [Change the messagingTransport keys](https://doc.sitecore.com/xp/en/developers/92/platform-administration-and-architecture/walkthrough--configuring-the-message-bus-role-to-use-azure-service-bus.html#UUID-0f18655b-0928-974b-225f-38be2fb5c4ca_section-idm4623774698768031621283559501 "Change the messagingTransport keys")
- [Switch the messaging configuration files](https://doc.sitecore.com/xp/en/developers/92/platform-administration-and-architecture/walkthrough--configuring-the-message-bus-role-to-use-azure-service-bus.html#UUID-0f18655b-0928-974b-225f-38be2fb5c4ca_section-idm4616737386337631621297462216 "Switch the messaging configuration files")
- [Configure the Message Bus role for use with containers](https://doc.sitecore.com/xp/en/developers/92/platform-administration-and-architecture/walkthrough--configuring-the-message-bus-role-to-use-azure-service-bus.html#UUID-0f18655b-0928-974b-225f-38be2fb5c4ca_section-idm23206209965709 "Configure the Message Bus role for use with containers")

<details>
<summary><h2>Change the messaging connection strings</h2></summary>

You must change the `messaging` connection string from Microsoft SQL Server to Azure Service Bus on all [roles that references the Message Bus role](https://doc.sitecore.com/xp/en/developers/92/platform-administration-and-architecture/message-bus.html "Message Bus").

To change the `messaging` connection string:

1. In the `<wwwroot>\App_Config\` folder, open the `ConnectionStrings.config` file.
2. Locate the `add name="messaging"` property and change the `connectionString` attribute to the Azure Service Bus connection string.

    ```xml
    <add
      name="messaging"
      connectionString="<your Azure Service Bus connection string>" />
    ```

3. Save the `ConnectionStrings.config` file.
4. Repeat the procedure for all relevant roles.

</details>

<details>
<summary><h2>Change the messagingTransport keys</h2></summary>

You must change the `messagingTransport` key from Microsoft SQL Server to Azure Message Bus on all [Core roles](https://doc.sitecore.com/xp/en/developers/92/platform-administration-and-architecture/roles-overview.html "Roles overview") that references the Message Bus role.

To change the `messagingTransport` key:

1. In the `<wwwroot>\` folder, open the `Web.config` file.
2. Locate the `add key="messagingTransport:define` property and change the `value` attribute from `SQL` to `AzureServiceBus`.

    ```text
    <add key="messagingTransport:define" value="AzureServiceBus" />
    ```

3. Save the `Web.config` file.
4. Repeat the procedure for all relevant roles.

</details>

<details>
<summary><h2>Switch the messaging configuration files</h2></summary>

You must switch all messaging configuration files from Microsoft SQL Server to Azure on all [XP service roles](https://doc.sitecore.com/xp/en/developers/92/platform-administration-and-architecture/roles-overview.html "Roles overview") 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:

1. Add the `.disabled` extension to all files matching `*Messaging.SqlServer.xml`.

    ```text
    *Messaging.SqlServer.xml -> *Messaging.SqlServer.xml.disabled
    ```

2. Remove the `.disabled` extension from all files matching `*Messaging.Azure.xml.disabled`.

    ```text
    *Messaging.Azure.xml.disabled -> *Messaging.Azure.xml
    ```

3. Repeat the procedure for all relevant roles.

</details>

<details>
<summary><h2>Configure the Message Bus role for use with containers</h2></summary>

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:

1. [Prepare Sitecore to be deployed to containers](https://containers.doc.sitecore.com/) through a shared `docker-compose.yml` file.
2. 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`.
3. 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>`).
4. Create a file named `enable-messaging-asb.ps1` and paste in the following *example* PowerShell script:

    ```csharp
    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"
    ```

5. Run the following [Docker file](https://docs.docker.com/engine/reference/builder/#arg):

    ```

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

6. Deploy your images.

</details>