TABLE OF CONTENTS


Prerequisites

Overview

  • IIS web server with 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
  • Client: Microsoft .NET Framework 4.5 or later


IIS Server

Role

Web Server and API Web Service

Folder for attachments

Operating System

Windows Server 2012 R2 or later

Web Server

Internet Information Services (IIS) 8 or higher
.NET Framework 4.5.2 or later

.NET Core Windows Server Hosting 

DNSIf you plan to run MigrationStudio and ManagementStudio on the same web server, a new DNS alias should be setup for ManagementStudio.

Port

Client access on 80 or 443 (HTTPS)

CertificateIf using port 443 (HTTPS) a certificate will be required on the IIS server.  Note that only one Server-based certificate can be used at once on each IIS server. If the MigrationStudio website is being hosted on the same server where ManagementStudio will be hosted, this may be a consideration. 

Minimum CPU

Quad-core

RAM

Up to 10k seats

8GB

10k – 50k seats

16GB

50k – 100k seats

32GB

100k - 150k seats64GB

Disk space

500MB for web application in IIS

20GB – 100GB for attachments

 

 

Database Server

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


Role

Database Server. SQL Server can be hosted on the same server as IIS for test/demo and POC ser

Operating System

As required by SQL Server

Database Software

Microsoft SQL Server 2012 SP4 or later

Recovery ModelSimple (Full may impact system performance)

Port

1433, other ports also supported

Minimum CPU

Quad-core

RAM

Up to 10k seats

8GB

10k – 50k seats

16GB

50k – 100k seats

32GB

100k - 150k seats64GB

Database size

Approx. DB 3GB per 1,000 seats  / Logfile x2 DB Size

Collation

Latin1_General_CI_AS (others may be possible)


Service Account

A domain service account is required for running the IIS Application Pool. For test/demo installs a local account or Microsoft account can be used. The service account requires:  

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

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.5 or later


For a local installation:

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

Installation Responsibilities

 

Project Kick-Off

Provide installation mediaManagementStudio

IIS Services

Provision of the ManagementStudio IIS hostCustomer
SSL only: Generate and import web server identity certificateCustomer

DNS

If MigrationStudio and ManagementStudio will both run on the same IIS server, a new DNS alias should be created for ManagementStudioCustomer

SQL Services


Provision SQL services (new server or new database on existing SQL server)Customer
Create the ManagementStudio DBCustomer
Create ManagementStudio AD service accountCustomer
Grant the ManagementStudio AD account DBO access to the SQL database used for ManagementStudioCustomer
Grant the ManagementStudio AD service account read-only access to the inventory DBCustomer
Ensure 'Authenticated Users' has read-permission to all in-scope AD objectsCustomer
Multi-domain only: Verify trusts in place to enable the service account to communicate with other domainsCustomer
Provide a list of NETBIOS and associated FQDN for all domains in useCustomer
Identify OUs for in-scope users and computersCustomer

Network Communications

Verify network connectivity
PowerShell: test-netconnection -computername [HOSTNAME] -port [PORT]

For example, to test connectivity to an SCCM SQL server (named SVR-SCCM-001) on the default ports:
test-netconnection -computername SVR-SCCM-001 -port 1433
Customer
  - ManagementStudio IIS host to AD (port 389)Customer
  - ManagementStudio IIS host to SCCM DB (port 1433)Customer
  - ManagementStudio IIS host to ManagementStudio DB (port 1433)Customer
  - ManagementStudio IIS host to SMTP relay (typically port 25 or 587)Customer
  - Optional: ManagementStudio IIS host to File Share (ports 445, 137, 138, and 139)Customer
  - End-user network to ManagementStudio IIS serverCustomer

Installation

Arrange WebEx for installationManagementStudio
Participate in screen shareManagementStudio & Customer
Add Windows IIS roles and featuresManagementStudio
Install the ManagementStudio websiteManagementStudio
Configure IISManagementStudio
Perform initial setupManagementStudio
Install and configure data connectors (inc. Technical Contact for logs)ManagementStudio
Install ESMManagementStudio
Install custom email module and configureManagementStudio
Setup user accountsManagementStudio
Apply the product licenseManagementStudio
Setup BlueprintsManagementStudio
Configure DashboardsManagementStudio


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. The module creates the reverse-proxy between IIS and the Kestrel server.

  1. Browse to https://dotnet.microsoft.com/download/dotnet/6.0
  2. Locate the latest version of ASP.NET Core Runtime. Pick the version that matches the server architecture. i.e. x64 if it's an x64 server.
  3. Ensure you choose the Hosting Bundle option
  4. Install

 

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

 

Note for ManagementStudio v7 users: ManagementStudio v10 does not have a SQL script for creating the database. It will attempt to create its own from the database name specified in the connection string of the 'appsettings.json' file in the root of the website. 


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 account which will be used to run the IIS web site) 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. Port: If the Default Website uses port 0 you should either:
    1. Set a different port for the ManagementStudio website, or
    2. Add a host name – This is the DNS name which will be used by clients for connecting to the ManagementStudio server

  10. Click OK
  11. In IIS Manager Click on the Application Pools node, then select the new Application Pool, then click on Advanced Settings

  12. Under Process Model select Identity then click the button to set the Identity



  13. Select Custom Account, click Set
  14. Add the details of the service account in the format <domain>\<account name>
  15. Add the password and confirm the password
  16. 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. Installer - MS_v10_Update_X.Y.Z.zip
    2. ManagementStudio_vX.Y4_Config.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

  1. Extract the files ManagementStudio_vX.X_Install.zip into the IIS website folder (e.g. C:\inetpub\ManagementStudio\). Note. Extract them directly into this folder, not into a subfolder.
  2. 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: It will create an empty shell default project that is ready for importing into from MigrationStudio v7

  3. Browse to the required folder

  4. 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

  5. Browse to the required folder

  6. 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. Using a text editor such as Notepad, open the file [IIS Website Folder]\appsettings.json
  2. Apply the settings from the table below to the "Settings:" section
  3. Save and close the appsettings.json file.
  4. Please refer to this solution article for more information on connecting to a database within an Always On availability group listener.


Setting with exampleDescription
Server=sqlserv03SQL server hostname
Server=sqlserv03\\ms_instanceSQL server hostname and instance name (default instance is not in use). Note the use of a double backslash.
Database=MigrationStudioEnter the database name
Trusted_Connection=TrueWhere an AD service account is being used to authenticate to SQL
User Id=myUsername;Password=myPasswordWhere an SQL account is in use for database authentication.
More info on connection strings: https://www.connectionstrings.com/sql-server/

"LocalSiteUrl":"http://server1"


It's best practice not to use a DNS alias (if configured) as the webserver may not have DNS configured. Instead, it's suggested to use the server hostname (fully qualified if needed).

This setting is used internally by PowerShell (e.g. it's the server address that Connectors use to talk back to the server). If this value is changed, the App Pool should be restarted in IIS or by using the Soft Restart IIS button found in Administration > Global Settings > Troubleshooting.
"FileStoragePath":
“D:\\Data\\ManagementStudioFiles" 
Add a path where all uploaded files, logs, PowerShell scripts reports etc will be saved. For a single server, a local folder path is fine. Note the use of double backslashes.
"FileStoragePath":
“\\\\server\\share1\\ManagementSudioFiles"
Add path where all uploaded files, logs, PowerShell scripts reports etc will be saved, UNC path needed where IIS and database are hosted on separate servers. Note the use of double backslashes.
"JwtKey":"<Generate 32-bit GUID>"Example:
"JwtKey":"32b0c35f-8e7e-4db3-91c6-56f6bbc23fec"

Use this URL to generate a 32-bit GUID:
https://www.guidgenerator.com/online-guid-generator.aspx

If Internet access is not available, PowerShell should be used to generate the GUID and copy it to the clipboard:
[system.guid]::NewGuid().guid | set-clipboard


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.


Here's how to specify this within the appsettings.json file:


"DatabaseConnection":"Server=ben-spectre,5177\\SQL2017;Database=ManagementStudio;Trusted_Connection=True;ConnectRetryCount=0;",




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) 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 both local clients 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

See here for further information on why this is the case: https://support.managementstudio.com/a/solutions/articles/14000128840#Client

  1. Open a web browser from the client machine
  2. Browse to the URL http://<IIS Web Server hostname>/0 such as http://managementstudio/0. Make sure you append “/0” to the end of the URL
  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: IIS website address (with port if not 80 or 443) such as http://managementstudio (Note – Don’t put the “/0” on the end) 

  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


Client Settings

  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. 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 logon 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


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

The Application category in Event Viewer will contain more detailed information that should be used to troubleshoot the issue.


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

  1. Ensure .NET Core hosting software is installed
  2. Add TrustServerCertificate=True; to the DatabaseConnection string in AppSettings.json
  3. Check DatabaseConnection and FileStoragePath in AppSettings.json to ensure double backslashes are used



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: 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/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. Download the ManagementStudio upgrade ZIP file into a folder which can be accessed
  2. Right-click on the ZIP file -> Properties -> check Unblock -> OK
  3. Logon to ManagementStudio with an account which has administrative privileges
  4. Navigate to Administration -> (Scroll down) Licence
  5. Click Update ManagementStudio
  6. Browse to the ManagementStudio ZIP file

  7. Click Apply Update Now


  8. Once the above prompt appears, click Restart; the client will be restarted
  9. 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 auto-update once the server has been upgraded.



Further Support

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