TABLE OF CONTENTS

• Prerequisites
  • Overview
  • IIS Server
  • Database Server
  • Email
  • Service Account
    • IIS Server Permissions
    • SQL Database Permissions
    • Permissions for Connectors
  • User Accounts and Single Sign-On (SSO)
  • MECM/SCCM Connector
  • ManagementStudio Installation Files
  • Client Prerequisites
• Network Architecture
• Installation Responsibilities
  • Project Kick-Off
  • IIS Services
  • SQL Services
  • AD
  • Network Communications
  • Installation
• Installing the Server Prerequisites
  • Install ASP.NET Core Windows Server Hosting
  • Create the ManagementStudio Database
• Server Installation
  • Install IIS
  • Configure IIS App Pool Recycling Settings
    • Step Summary
  • Install the ManagementStudio Website and Config Files
  • Create a folder for storing ManagementStudio Files
  • Configure the ManagementStudio website settings
    • Test the LocalSiteUrl Setting
  • Test the ManagementStudio Website
  • Enabling the Client Network Installation
  • Using the Client Network Installation
• ManagementStudio Client Installation
  • Initial Configuration
  • Account Creation
• Connector Setup
  • Housekeeping Connector
  • Connectors
• License
• Troubleshooting
  • Error: HTTP Error 500.30 - ASP.NET Core app failed to start
  • Error: HTTP Error 500.37 - ASP.NET Core app failed to start within startup time limit
  • Error: HTTP Error 500.19 - Internal Server Error
  • Error: Connector Logs show "Login Failed. Server not found, check Url."
  • Error: Unexpected character encountered while parsing value: <. Path '', line 1, position 1
  • Error: Network Error (tcp_error)
  • Checking the .Net Core Hosting Bundle version
• Upgrading the ManagementStudio Server
  • Prerequisites
  • Automatic Upgrade
  • Manual Upgrade
• Upgrading the ManagementStudio Client
• Further Support

Prerequisites

Overview

• IIS web server with a folder for file attachments
• Separate SQL database server
• SMTP relay
• Domain service account with read access to Active Directory and inventory system such as SCCM/MECM
• Installation files (download links will be supplied by the ManagementStudio consultant)
• Admin Client: Microsoft .NET Framework 4.8 or later

IIS Server

Database Server

Note that the SQL database should be hosted on a separate server from IIS, except for test/demo and POC setups.

Email

ManagementStudio uses email for several administrative functions, including sending details of new accounts to users, and password resets.  Without it, ManagementStudio users will be unable to log in to the platform.

The following information is required:

• SMTP Server Address
• Port
• SSL Options
• Optional authentication method, either:
  • The ManagementStudio IIS server is whitelisted
  • Or, a username and password is required

Service Account

A domain service account is required for running the IIS Application Pool, connecting to SQL and running the connectors. For test/demo installs a local account or Microsoft account can be used. 

IIS Server Permissions

The service account requires:  

• Local admin rights on the IIS server
• “Logon as a batch job” rights on the IIS server
• “Logon as a service” rights on the IIS server

SQL Database Permissions

The service account requires:

• db_owner on the ManagementStudio database

Permissions for Connectors

• A minimum of read access to Active Directory for the domain(s) where users and devices will be imported from. Multiple domains are supported as long as trusts are in place so that the service account can access the other domains. ManagementStudio can optionally automate tasks in AD (such as adding users to groups). If this is required, change permissions will be needed in AD
• The MECM/SCCM and Lakeside SysTrack connectors can run as either the service account or an SQL account. The account requires read access to the MECM/SCCM/SysTrack SQL database

User Accounts and Single Sign-On (SSO)

It's recommended that Single Sign-On is used to provide access to the ManagementStudio console. One of the requirements is that a number of groups are created in on-prem Active Directory or Azure/Entra ID.

Further information on SSO can be found here.

MECM/SCCM Connector

This connector depends on the software metering feature being on (the default setting) in MECM/SCCM. From experience, it's been found that this is generally the case, but in some organisations, the feature has been disabled.

Note that it is NOT necessary to explicitly enable metering for each executable file for each application where usage is required. 

To confirm that the feature is on, and collecting data, run the SQL query below against the MECM/SCCM database. 

Expected results:

SQL Query:

--Number Of Machines
select count(distinct resourceID) from
v_GS_CCM_RECENTLY_USED_APPS
--Number of Users
select count(distinct lastusername0) from
v_GS_CCM_RECENTLY_USED_APPS
--Number of EXE Files
select count(distinct filepropertieshash0) from
v_GS_CCM_RECENTLY_USED_APPS 

If Software Metering needs enabling please refer to this article: Enable Software Usage in SCCM/MECM

ManagementStudio Installation Files

Two files are required. Download links will be provided by the ManagementStudio consultant.

• Main installer: MS_v20ww.xx.yy.zz.zip
• Config files: MS appsettings json config x.y.zip

Client Prerequisites

The ManagementStudio client has been developed on WPF (Windows Presentation Foundation for .NET 6). The client application can be run in one of two ways:

• Local install: The client can be installed and run in most environments without the necessity for local admin privileges. 
• Network Install:  The client can be installed into a network share (or DFS), and the main executable run from the share directly. 

In both these scenarios, the client version is automatically checked and updated as required using a technology called Squirrel. This is the same installation technology used by Microsoft Teams and provides a secure and trusted ClickOnce environment.

It is very important that the client and server versions are synched automatically so that data corruption does not occur through the use of an older version of the client. This is the main reason we DO NOT support packaging the ManagementStudio client as a static set of files using MSI, App-V, or other packaging toolsets.

However, it is possible to package a shortcut to the main client executable when a network installation is in use.

Both a local install and network install require that the client has:

• Microsoft .NET Framework 4.8 or later

For a local installation:

• Ensure no Group Policies are in place on the clients which prevent applications from running from %appdata%

Network Architecture

Installation Responsibilities

Installing the Server Prerequisites

Install ASP.NET Core Windows Server Hosting

The bundle will install the .NET Core Runtime, .NET Core Library, and the ASP.NET Core Module required by ManagementStudio.

1. Browse to https://dotnet.microsoft.com/en-us/download/dotnet/8.0
2. Locate the highest 8.0.x version of ASP.NET Core Runtime
3. Download the Windows Hosting Bundle
4. Install the runtime

Create the ManagementStudio Database

ManagementStudio requires that an empty SQL database has been created. The name of this

1. Create an empty database. This is typically called ManagementStudio but other names are supported
2. Set the Recovery Model to Simple. Choosing Full may impact system performance and is not recommended
3. Give the ManagementStudio service account db_owner rights on the new database as shown below:
   
   

Database permissions setup for a Microsoft account

Server Installation

Install IIS

1. Add the Internet Information Services (IIS) feature to the web server using the default options. This can be added in Windows Features on Windows 10 or Server Manager on the server operating system.
   
   
   
   
2. Create a folder called ManagementStudio to store the web server files. Typically, this is under C:\inetpub but other locations are supported.
   
3. Give the ManagementStudio service account (or the account which will be used to run the IIS website) Modify NTFS permissions on this folder.
   
   
4. Open Internet Information Services Manager
5. Create a new website by right-clicking on the Sites node and clicking Add Website
   
   
   
   
6. Site name: ManagementStudio
7. Application Pool: A new Application Pool will automatically be created with the same name as the site
8. Physical path: The path where the new folder was created to host the website files
9. Type: In most cases, this should be set to HTTPS, but HTTP is also supported 
10. Port: For HTTPS leave the port at 443. If using HTTP you can leave the port at 80. However, if the Default Website uses port 80 you should either:
    1. Change the port of the Default Website, or
    2. Add a hostname – this is the DNS name which will be used by clients for connecting to the ManagementStudio server
       
       
11. Click OK
12. In IIS Manager, click on the Application Pools node, then select the new Application Pool, and then click on Advanced Settings
    
    
13. Under Process Model select Identity then click the button to set the Identity
    
    
    
    
14. Select Custom Account, click Set
15. Add the details of the service account in the format <domain>\<account name>
16. Add the password and confirm the password
17. Click OK, OK, OK

IIS is now configured as required.

Configure IIS App Pool Recycling Settings

Apply these settings to the ManagementStudio IIS App Pool: Recommended IIS Settings

Step Summary

1. Install the Application Initialization Module
2. Ensure the Application Pool is set to start immediately 
3. Set as Always Running and Idle Timeout = 0
4. Set the Recycling Time to 2 am
5. Set Preload Enabled to true

Install the ManagementStudio Website and Config Files

1. Download the following files:
   1. Main installer: MS_v20ww.xx.yy.zz.zip
   2. Configuration files: MS appsettings json config x.y.zip
2. Right-click on each of the downloaded zip files and click Properties
3. Under the General tab, check Unblock, then click Apply, OK
4. Extract the main installer files from MS_v20ww.xx.yy.zz.zip into the IIS website folder (e.g. C:\inetpub\ManagementStudio\). Note. Extract them directly into this folder, not into a subfolder.
5. Open the Configuration files zip file. There are two folders:
   1. Create New Project - New Installs: For new sites use this appsettings.json. On first launch, it will create a new project and fill in the default config of fields, processes, dropdowns etc.
   2. Create Empty Project - For migrations from MigrationStudio v7 to ManagementStudio.  This file will create an empty shell default project that is ready for importing into from MigrationStudio v7.
6. Browse to the required folder.
7. Two further subfolders will be available:
   1. DB Access - Sql Account - For setups using an SQL account for database authentication
   2. DB Access - Windows Service Account - For setups using a Windows service account for database authentication
8. Browse to the required folder
9. Extract the files appsettings.json and web.config into the ManagementStudio IIS website folder

Create a folder for storing ManagementStudio Files

1. Create a folder for ManagementStudio to store file attachments and other system files (e.g. C:\ManagementStudioFiles)

2. Apply permissions to this folder so that the service account has modify NTFS rights.
   

Configure the ManagementStudio website settings

1. Launch Notepad using the 'Run as administrator' feature (found by right-clicking the Notepad icon in the Start menu).
2. Open the file [IIS Website Folder]\appsettings.json.
3. Apply the settings from the table below to the "Settings:" section.
4. Save and close the appsettings.json file.
5. Please refer to this solution article for more information on connecting to a database within an Always On availability group listener.

Example appsettings.json file:

Test the LocalSiteUrl Setting

On the web server open a web browser and enter the URL used in the LocalSiteUrl setting. This should load up the client install page. If it fails you may have a DNS issue on the server and may need to specify a different URL in the LocalSiteUrl setting.

Some Organisations might use a specific port to connect to their SQL Server.

To use a specific port, update the 'DatabaseConnection' property in the appsettings.json file.  For example, to force svrappsql001 to us port 5177, the following Database Connection string would be used:

"DatabaseConnection":"Server=svrappsql001,5177;Database=ManagementStudio;Trusted_Connection=True;ConnectRetryCount=0;TrustServerCertificate=True;",

Test the ManagementStudio Website

1. Open IIS Manager
2. In Application Pools -> Restart the Application Pool
3. Expand the Sites node
4. Select the ManagementStudio website
5. Click Browse Website link – If you see an error in the web browser this is normal
6. This should take a few minutes to open - ignore any errors at this point
7. In the web browser open the URL (e.g. http://managementstudio.local) and press return, the following page should be displayed:
   

This confirms that the base install is complete.

The default admin account and password will have been created. Details of this are stored in a file named Accounts.txt which will be in the ManagementStudio file location folder, such as C:\ManagementStudioFiles\Accounts.txt

It is strongly recommended that this file is moved to a secure location.

Enabling the Client Network Installation

For scenarios where the client should be run from the network for specific devices (avoiding a local installation), the following steps are required. Note that it is possible to use the local client and network client concurrently:

• Create a network share on a Windows server
• Setup the share so that the ManagementStudio service account has Modify NTFS permissions and Change share level permissions
• Make a note of the Network Path in the Sharing tab on the Folder Properties - Copy this to the clipboard

• In the Security tab for the folder, click Advanced and ensure inheritance is enabled (indicated by the button displaying Disable Inheritance)
• Click OK, OK
• Add the Network Path to the appsettings.json file on the web server (this should be placed after the FileStoragePath line) ensuring double backslashes are used

"ClientNetworkRunPath": "\\\\server\\share",

or

"ClientNetworkRunPath": "\\\\server\\share\\Folder",

• If a subfolder has been specified, ensure this exists
• Restart IIS
• The client network installation will be created in the specified folder
• Make a note of the UNC path such as \\server\share\MS Client\ManagementStudio.exe 

Using the Client Network Installation

• Create a shortcut to the UNC path noted above 
• Give this shortcut to the users who require the client network installation
• The users can use this shortcut to access ManagementStudio

ManagementStudio Client Installation

Important: Packaging the ManagementStudio client as a set of static files is NOT SUPPORTED

For further information on why this is the case, please refer to: https://support.managementstudio.com/support/solutions/articles/14000128840-managementstudio-installation-guide#Client-Prerequisites

1. Open a web browser from the client machine
2. Browse to the URL http://<IIS Web Server hostname>/ such as http://managementstudio.local/
   
3. Click the Download and Install... link
4. Once downloaded, run the EXE
5. Enter the following details: 
   1. Username: ManagementStudio
   2. Password: Enter the password from Accounts.txt (this file is created in the ManagementStudio
   3. ManagementStudio Url: The URL of the IIS website address such as http://managementstudio.local 

1. Optional: Check the Remember Me and Auto Login checkboxes
2. Click Sign In
3. The client should load with a seven-day Proof of Concept license

Initial Configuration

1. Click on the Administration button at the bottom-left
   
2. Scroll down and click on Global Settings
3. Add the following settings
   1. Public URL: This is the URL that all users will need to access for testing links, surveys etc and should be accessible by everyone. For example, http://managementstudio.public.corp
   2. Email Settings. Add SMTP Server Address and other SMTP settings. Note that it’s not possible to setup user accounts or reset passwords without a working SMTP server
   3. To authenticate to the SMTP server with the service account, tick Trusted Connection. Otherwise enter a username and password.
   4. If using Office 365 for SMTP, make sure the Per Minute Send Limit is set to 30
4. Click Save Changes, Save, then Cancel as we don’t need to restart the client at this point
5. Now click on Project Settings in Administration
6. Change to the Email and Keywords tab, change the Email From Address as required, internal email address recommended
7. Change the Email From Display Name as required
8. Click Save Changes, Save, Restart Client

Account Creation

1. Log in to ManagementStudio client
2. Click on Administration, MS User Accounts
3. Click New Account
   
   
   
   
4. Add the following
   1. User name – This will be used to login to ManagementStudio 
   2. Domain - Optional, and will assist with SSO in the future
   3. Email – This must be a valid email address
   4. First name, Last Name, Note (optional)
5. Note that the user name and email fields must be unique
6. If you would like to send the user a welcome email ensure Send the ManagementStudio Welcome Email  is ticked
7. Click Create User
8. An email will be sent to the user within a few minutes
9. By default the new user will be a member of one role group called Project Member
10. To add the user to further Role Group, right-click the user, Add Role
    
    
    
    
11. Select the required Roles and click Add Roles

Connector Setup

Housekeeping Connector

It's important to install the Housekeeping Connector next. This helps maintain User Migrations and Devices by providing options to archive (or delete) them from ManagementStudio if/when their associated Active Directory account is disabled or deleted.

1. Log in to ManagementStudio client (the Project Admin role is required)
2. Click Administration -> Extensions -> Connectors
3. Click Add New Connector -> Housekeeping -> OK
4. Add a Schedule to run the connector daily
5. Review the default settings and amend if necessary
6. Click Save Changes

Connectors

Information on the Connectors can be found here: https://support.managementstudio.com/support/solutions/articles/14000119218-connectors

For the installation of the these connectors please speak to a ManagementStudio Consultant. 

License

1. A licence will be created by the ManagementStudio consultant
2. This typically auto-syncs with the ManagementStudio server so that manually adding the licence is not required
3. Alternatively, if you have been supplied with a licence key this can be added manually by clicking Manually Add Key

   
   

   
   
   
4. Paste the key into the window and click OK
5. The Licence Type and Universal Ticket count can be viewed in Administration -> Licence

Troubleshooting

Reviewing the Application log in the Event Viewer will often provide detailed information regarding the issues and is an invaluable resource when troubleshooting.

Error: HTTP Error 500.30 - ASP.NET Core app failed to start

• Check the Event Viewer for entries regarding IIS AspNetCore Module V2
• Ensure the collation of the ManagementStudio database is set to 'default'
• Add TrustServerCertificate=True; to the DatabaseConnection string in AppSettings.json
  
• Check DatabaseConnection and FileStoragePath in AppSettings.json to ensure double backslashes are used
• Verify that .NET Core hosting software is installed

Error: HTTP Error 500.37 - ASP.NET Core app failed to start within startup time limit

Solution: This is resolved by increasing the startupTimeLimit in the web.config file:

• Browse to where the install files are located. Typically C:\inetpub\ManagementStudio.
• Locate and open the Web.config file in an editor.
• Add in the configuration as shown in the screenshot below. NB: You can specify a higher startuptimelimit. 

• Save the config file.
• Restart IIS Service.
• Launch ManagementStudio.

Error: HTTP Error 500.19 - Internal Server Error

Solution: Install .NET Core hosting software

If this is already installed, try repairing the installation.

Error: Connector Logs show "Login Failed. Server not found, check Url."

Cause: There is an issue with how ManagementStudio references itself using DNS.  Typically this happens when DNS isn't set up on the server and the FQDN can't be resolved.

Solution: Add the correct reference to LocalSiteUrl in appsettings.json:

• Open appsettings.json and make a note of the value LocalSiteUrl.

• Open a browser on the server and enter the value of LocalSiteUrl into the address bar with /0 appended.  For example, http://managementstudio.local/0
• The browser will return HTTP Error 404.0 - Not Found if DNS resolution is the cause. Enter the hostname - http://managementstudio.local/0 - into the browser's address bar and try again. This time, the client installation page should appear.
• Update LocalSiteUrl so that it uses the correct DNS name, in this example, the hostname.  
• The AppPool will need to be restarted, either from within IIS or using the ManagementStudio client: Administration > Global Settings > Troubleshooting and click the Soft Restart IIS button.

Error: Unexpected character encountered while parsing value: <. Path '', line 1, position 1

If this error is encountered when logging on via the client for the first time, load the site through a browser to determine if any other error messages are present.

Error: Network Error (tcp_error)

The following error is displayed when connecting to the site through a browser using the DNS name:

Network Error (tcp_error)

A communication error occurred: ""

The Web Server may be down, too busy, or experiencing other problems preventing it from responding to requests. You may wish to try again at a later time.

For assistance, contact your network support team.

If the site resolves using LocalHost, a proxy might be blocking the client.

Checking the .Net Core Hosting Bundle version

Run the below PowerShell on the target server to check the installed versions of .Net Core. Check that the target architecture matches the server. i.e. .Net Core x64 has been installed on an x64 version of Windows. 

$NotInstalled = $True
$DotNetCoreItems = Get-Item -ErrorAction ignore -Path "Registry::HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Updates\.NET Core"

if($null -ne $DotNetCoreItems)
{
    $DotNetCoreItems.GetSubKeyNames() | Where { $_ -Match "Microsoft .NET Core.*Windows Server Hosting" } | ForEach-Object {
        $NotInstalled = $False
        Write-Host "The host has installed $_"
    }
}

if ($NotInstalled) {
    Write-Host "Can not find ASP.NET Core installed on the host"
}

Upgrading the ManagementStudio Server

To check the current version of the ManagementStudio server

Prerequisites

• The installation file (in ZIP format) will be supplied to you by a ManagementStudio consultant as a download link
• You have the ManagementStudio client installed
• A ManagementStudio logon with admin privileges is available

Automatic Upgrade

1. It's recommended that the database is backed up before the upgrade is applied
2. Download the ManagementStudio upgrade ZIP file into a folder which can be accessed
3. Right-click on the ZIP file -> Properties -> check Unblock -> OK
4. Logon to ManagementStudio with an account which has administrative privileges
5. Navigate to Administration -> (Scroll down) Licence
   
6. Click Update ManagementStudio
7. Browse to the ManagementStudio ZIP file
   
8. Click Apply Update Now
   
   
9. Once the above prompt appears, click Restart; the client will be restarted

10. If you experience issues there is a log file in the specified file location folder, in a subfolder called Updates, then a subfolder with the current date and time. Please raise a support ticket and include this log file.

Manual Upgrade

If the automated upgrade fails, you may need to manually upgrade ManagementStudio. This can be achieved as follows:

1. Download the ManagementStudio zip file. The link will be provided by a member of the ManagementStudio team.
2. Unblock ZIP file
   1. Right-click the zip file, click Properties
      
   2. Tick Unblock
   3. Click Apply
   4. Click OK
3. Stop the ManagementStudio IIS App Pool
   1. Open IIS Manager and open the Application Pools node
   2. Select the Application Pool which is running the ManagementStudio web server
   3. Click Stop
4. Backup the IIS website folder to a safe location. To locate this folder:
   1. Open IIS Manager, expand the Sites node and select the ManagementStudio website
   2. Click Explore to show the IIS website folder
      
5. Open the downloaded ZIP file
6. Extract the contents of the ZIP file into the IIS web folder, ensuring all files are over-written
7. Start ManagementStudio App Pool
   
8. Run the ManagementStudio client and logon
9. You should be prompted to restart the client to apply the update if the server upgrade was successful

Upgrading the ManagementStudio Client

The client will automatically update the first time it connects to a server that is running a higher version.

Further Support

If you require further support, please visit ManagementStudio's Service Desk to search the knowledge base or create a new support ticket