Installing Exago on Azure

Microsoft Azure is a cloud infrastructure for hosting files, databases, virtual machines, and web applications. Exago supports various forms of integration with Azure.

App Service: The Exago BI web app, web service API, and .NET API host apps can be installed as Azure app services.

Virtual Machine: Exago BI can be installed on a Windows virtual machine on Azure.

File Storage: Exago BI data can be stored and accessed from Azure storage containers.

These methods can be implemented independent of each other. However, Web App integration and VM integration are usually redundant with each other, and most Web App solutions should also implement Azure file storage. This guide will walk through how to set up each of these solutions.

Which solution should I use?

The primary limitation to Azure App Services is that the Exago Scheduler and Monitoring services are not supported. If scheduling is a requirement then virtual machines must be used, either in addition to using an App Service for the web application and web service API, or to host the full application stack.

If scheduling is not a requirement, then App Service and File Storage are recommended. This is a more integrated solution that may deliver better performance with less overhead than a Windows Server VM. And it can be easier to scale up this solution into a web farm environment.

App Service

Exago can run as a Azure App Service. This is necessary in order to run a .NET API based host application in Azure.

The following Azure resources are required:

 App Service plan

 App Service

Note: You may require a Storage Account to run Exago as a scalable app. See File Storage for details.

This section is divided into two parts: Hosting Exago in an App Service and Using the .NET API with Azure. If your host application is not hosted on Azure, you can skip the second part.

Hosting Exago BI in an App Service

Note: This walkthrough requires a local Exago installation. See the Exago Installation Guide for details.

In your Azure Dashboard, create a new App Service container or navigating to an existing one.

In the App Service, navigate to Deployment Credentials. Add a username and password. This will allow you to FTP into your web app to transfer files.

Next, you'll need an FTP application. Open a connection using the deployment credentials you just created.

Copy your local Exago BI web app installation directory to the app service container.

In the App Service, navigate to Application Settings. Set the following:

  • .NET Framework version: v4.0 or Later
  • Managed Pipeline Version: Integrated

Under Virtual applications and directories create a virtual directory path to the installation directory and select the Application check box.

Click Save to save your settings.

Test your installation and by navigating to the WebAppUrl\Exago\Admin.aspx page (Admin Console).

If you will use Azure Blob Storage to store the config file, follow the File Storage instructions before setting the base config.

Using the .NET API with Azure

Exago .NET API based host applications must be compiled locally before being uploaded to the Azure app container. References to the WebReports .dll libraries should be updated manually, and the program recompiled, when upgrading to a new Exago version.

Set your API constructor to use the previously set Exago virtual path:

Api api = new Api(@"/exago/virtual/path");
Note: .NET host apps can only access virtual paths (and not URL paths). Therefore they must be located in the same App Service container as the Exago web app.

Exago utilizes the virtual directory passed in the first argument of this constructor to locate the required .dll libraries to load Exago. In cases where the virtual directory is not specified within the API constructor (e.g., if Exago is installed on the root of the .NET host application), then a reference to the Microsoft.WindowsAzure.Storage.dll library will need to be added manually to the host application.


File Storage

Exago can be integrated with Azure cloud storage for storage and live access to reports, templates, config, and other data files.

The following Azure resources are required:

 Storage account

 Blob storage

The following Azure resource is optional:

 Files storage

Blob storage is a "flat" file system, which stores every file at the root level. To make use of this system, Exago emulates a directory structure using file names.

File storage is a directory-based system. Files are placed into directories, which can have sub-directories.

Reports can be stored in File storage or Blob storage. Config files, templates, themes, and temp files must be stored in blob storage.

In your Azure Dashboard, begin by creating a new Storage account or navigating to an existing one.

This section is divided into three parts: Config file storage, Reports storage, and Temporary files storage (which includes themes and templates). If you are implementing Exago as a scalable app, you must set all three to static locations.

Config File

An Exago installation contains a configuration file, usually called WebReports.xml, which tells the application where to store Reports and Temp files.

First, in the Storage account, navigate to Access Keys. Record of the two connection strings.

Azure Connection String

An Azure Connection String is a formatted string which contains your Azure account name and a unique alphanumeric key. It is used to give applications access to your storage account. The string uses the following format:


Next, there are two places which you need to specify the location of the configuration file:

  1. The appSettings.config file in the web app install directory.
  2. If you're using the .NET API, a parameter in the API constructor method.


Exago BI contains a file called appSettings.config in the root folder of the install directory. This file is used for custom app settings which are automatically imported into Web.config during runtime.

Note: Do not edit Web.config file. It is automatically generated by Exago, and any changes will be overridden.

To set the config file location, add the following key to the appSettings.config file:

<add key="ExagoConfigPath" value="pathtype=azure;credentials='Azure Connection String';storagekey=config"/>
  • credentials: Your Azure Credentials Connection String.
  • storagekey: The prefix of a blob container used to store the config file.
Caution: When both the REST API and cloud config storage are being used, the ExagoConfigPath entry must be placed in both the WebServiceAPI and web application copies of appSettings.config.


.NET API host apps cannot access the appSettings.config file. Instead, you must use one of the following two methods to specify a config file location:

  1. Place the config key within the host application's web.config or app.config.
  2. Or pass the connection string in the API constructor method:
Api api = new Api("/exago/virtual/path", "configFn.xml", "pathtype=azure;credentials='Azure Connection String';storagekey=config");
  • storagekey: The prefix of the blob container used to store the config file.
  • configFn: The name of the config file.
Caution: When both the REST API and cloud config storage are being used, the ExagoConfigPath entry must be placed in both the WebServiceAPI and web application copies of appSettings.config.

Reports Storage

To use an Azure storage resource for report and folder management, enter a formatted connection string in the Report Path field in your config file.

Note: This is different from (but contains) an Azure Connection String.

The connection string uses the following format:

pathtype=azure;credentials='Azure Connection String';storagekey='reports';usefilestorage=false
  • credentials: Your Azure Connection String.
  • storagekey: The prefix of the container used to store report files. Reports are stored in "storagekey-reports", templates in "storagekey-templates", and themes in "storagekey-themes". This key is optional and defaults to "wrreports".
  • usefilestorage: If true, Reports are stored in File storage. If false, Blob storage is used. Templates and themes always use blob storage. This key is optional and defaults to false.
Note: Templates are automatically stored in blobs when the template upload button is used in Exago. Themes need to be manually uploaded to blob storage.

Migrating from local storage to Azure blob storage

Exago emulates a directory structure within a "flat" file system like Azure blob storage by placing a "placeholder.dir" block blob in each directory. This directory file serves as a reference to a folder within the blob container and is automatically added to new folders when the Report Path is set to an Azure blob storage container. If this file is not present, Exago will not be able to recognize that the virtual directory exists within a blob.

When migrating from local storage to Azure blob storage, this file will need to be manually added to pre-existing report folders as it will not exist in folders that were created when the report path was set to a local directory. In order to manually add this file to these folders, please follow these steps after the Report Path is set to an Azure blob storage container:

  1. Add a new folder to the Exago report tree.
  2. Navigate to this folder via the Azure Storage Explorer.
  3. Copy the "placeholder.dir" blob within this folder and paste it into folders where it does not already exist.

Temporary Files Storage

Azure allows a Web app to be scaled up to multiple instances on separate servers. If you are implementing this configuration, you must take the following safeguards in order to prevent loss of user data.

Each instance of Exago BI has its own local temp directory, whose path you can (optionally) specify in the Temp Path setting in the config file (defaults to %INSTALLDIR%\Temp).

This is Exago's working directory — setup data for most user activity is stored and queried from here.

In a scalable configuration, initial user calls will reach one instance, storing temp files on that server, but subsequent calls may reach a separate instance, which will not have those temp files in its local directory. There are two solutions to resolve this issue: Temp Cloud Service and Azure Affinity Cookie.

Temp Cloud Service

This is Exago's built-in solution for handling multiple instances. Specifying a Temp Cloud Service causes each instance to push its temp files a shared Blob container whenever necessary. Then if a subsequent user call reaches a separate instance, that instance will pull the relevant files from the blob to its local temp directory.

To set up an Azure storage resource for temporary files, input a formatted connection string in the Temp Cloud Service field in your config file.

Note: This is different from a Report Path string. This is different from (but contains) an Azure Connection String.

The connection string uses the following format:

type=azure;credentials='Azure Connection String'

The Temp files container name defaults to "wrtemp". Currently this cannot be changed. Temp files can only be stored in blob storage.

Azure Affinity Cookie

Azure supports setting Affinity Cookies, which track which server instance each user is connected to and cause all calls within the session to reach the same instance.

In your app service, navigate to Application Settings. Set ARR Affinity to On.


Virtual Machine

Exago can be hosted on a Windows-based Azure Virtual Machine. Installing Exago on a VM differs only marginally from installing it on a local machine. Therefore, this guide will not go into depth on this method. For a full installation and setup guide, see the Exago Installation Guide.

You can interact with a VM using either a remote desktop application or a command shell application.

Using a Remote Desktop application:

  1. Using Remote Desktop Connection or another remote desktop application, view your VM as a desktop environment.
  2. Use a Web Browser to download the Exago Installer from our support site.
  3. Run the installer as Administrator and install Exago.
  4. Configure Exago (see Install and Configure).

Using a command shell:

  1. On a local machine, use the above steps 2-4 to create a temporary Exago installation.
  2. Remote into your VM using Windows PowerShell or another command shell application.
  3. Copy the Exago directory to a directory on your VM.
  4. Configure Windows and IIS (see Manual Application Installation).

After configuring IIS, open up the Exago port using a Windows Firewall inbound exception rule. You can then access Exago through the VM's IP address. Set up DNS and data security as desired.

Hidden Article Information

Article Author
Exago Development
created 2016-06-14 18:40:26 UTC
updated 2019-07-09 20:36:31 UTC

cloud, service, file, container, microsoft, vm, storage, blob, install, app, connection, string, ftp,
Have more questions? Submit a request