Friday, the end of the week. Your manager comes over to you at three in the afternoon with a
simple request, "Can you bring up this old windows application on a new machine?"
"Sure", you reply then ask, "I was wondering if you have the install documentation for it?"
He grimaces and sternly states, "I have a word document from 1998 that is woefully out of date.
By the way, we need this up by Monday."
Now your weekend is ruined or is it?
This is an example of how I would approach this problem. The goal here is to:
Automate the install so a new machine can be brought up quickly, or you could install it
in the cloud.
Review the documentation you have. Get the latest distribution to install the software. This is
usually the "setup.exe" or "install-something.msi". Make sure it's the latest one!
First find a machine where the thing is installed and working. If this doesn't exist, the task
will be harder. Go to that machine and see if the most recent install distribution (aka
setup.exe) is around somewhere. Compare the one you think is the latest with what is deployed
already. Basically confirm you have the right installs. If not, find it.
Look at the machine where it is working and note what programs are installed. "Add/Remove
Programs" from the control panel will show you this. Chances are if it's an old machine there
will be tons of stuff. You are going to want to identify the exact pre-requisites for the
install in the next step.
Start documenting everything. Create a text file and take notes there. If you download
something, paste the URL in your notes. If you run something write it down!
Create a new clean machine (instance). I typically bring up an EC2 machine on AWS (t2.micro
windows datacenter). This takes two minutes for the instance to start, and then four minutes to
get the Remote Desktop password to access it. You are going to delete this machine over and over
again during this process. Reducing the time spent when you start over is important. If you go
the physical machine route it may be slower.
Connect to the machine and copy your install over there. If you have pre-requisites copy them
over. If you are downloading the pre-requisite software take note of the URLs. The downloads can
Start installing the software and trying to get things running by hand. You will want to do this
from the command prompt. Take detailed notes about what you are doing and what is or is NOT
Hopefully it goes smooth and works!
When Things Go Sideways
During the install of the prerequisites or even when you try to run the application, things
may fail. That information is going to most likely be in:
A message box in the UI.
The Install Log. These are sometimes in the working path, but usually in the
The Event Viewer Application Log.
Take note of any DLLs or EXEs that are in the error text. Copy and paste the errors into
your notes. Try to fix the errors. Google the errors.
Most likely one stumbling block will be the Microsoft Visual Studio C++ Run Times. Getting
the right version of this is hard for some reason. Usually the documentation is wrong.
Errors from this will complain about dlls typically named:
If you are dealing with a .NET application that uses some C++ code most likely your error
will have SxS in it. This means side by side. Scroll through the error message to find out
what is wrong, there will usually be a file listed like "msxml4r.dll". That dll is usually
what is broken. It didn't get registered or is broke.
Important: It is tempting to just install all of the Visual Studio C++
Runtimes, every single one, in an attempt to get things working. Remember the goal here is
find out the bare minimum of what to install. You can remove things and add things via
Add/Remove programs but keep in mind ancient stuff doesn't always clean itself up during an
uninstall. You may want to start over with a clean instance from time to time. When you go
to automate it, you are going to want to do a final check that your install works on a clean
instance. This is why shortening the length of the cycle from creating a clean instance and
starting is important.
Common Last Chance Workarounds when things go sideways:
If an install fails because a DLL cannot be registered. Can you manually register
the dll? "regsvr32 yourdll.dll"
Can you just copy DLLs to the application path and then it magically works?
Maybe Bill changed a common DLL in 1998 and didn't update the word document. Can you
copy DLLs from where it works and copy and/or register those and get it working.
(This works surprisingly often.)
Replicate by hand what it does and see where it fails. Try to correct it.
It's Working! Congratulations!
Great. Take a break. If you are using EC2 you could create a machine image and call it a
day. What are the chances you won't need to repeat this on a new clean instance not from
that image? Have you improved anything? The only documentation now is your notes and the
original word document.
Automating the Installation
We will automate the installation and the current working documentation will be the script. That
script will even test the installation to make sure it actually works.
We now know the bare minimum steps to install the ancient software and the process. The
process usually is:
Download or copy the software
Install the software
Do strange things like tweaking the registry or updating text files
Clean Up the artifacts from the install
Test the Software
To automate this we will create:
An install.ps1 power shell script to install the software.
An install-check.ps1 power shell script to smoke test the software to make sure it
works. The install script will call this at the end.
For this example we are going to write an install script for an application called
FileConverter. This application takes a binary file and writes an XML file. To call it from
the command line we use:
fileconverter.exe input.bin output.xml
During the manual install the following needs to be installed to get it working
Microsoft Visual C++ 2008 SP1 Redistributable Package (x86)
MSXML 4.0 Service Pack 3 (Microsoft XML Core Services)
Microsoft Access Database Engine 2010 Redistributable
A User DSN called "File-ConverterDSN" using the Microsoft Access Driver
NET Core 2.2 Runtime & Hosting Bundle for Windows (v2.2.6)
The actual application installation is just a folder with an exe in it. We will create
the install.ps1 file in that folder. We can then copy the folder, run install.ps1, and
it will be ready to go.
I cannot share the fileconverter.exe with you. It's a hypothetical example.
Connect to the new clean instance. Create a folder to work from and let's create the
install.ps1 file. Lines starting with "#" are comments.
Now we will create the install-check.ps1. If the software does not work we want to throw an
exception that stops the script. Don't use a return value or something complicated. Just
throw and stop. Most automatic deployment tools that might want to use these scripts are
going to assume an exception means failure not a return code 100 vs return code 1024. Lines
starting with "#" are comments.
After refining your scripts, it is going to work. You are almost there!
Create a new clean instance then remote desktop to it. Copy your folder over then fire up
Power Shell and "./install.ps1"
Hopefully at the end you are greeted with "Healthy" and the deployment is now scripted.
You could bring up several of these things in the cloud. You could containerize the
application using Docker and WindowsServerCore.
In a future blog post I will show you how to use docker and allow access to these
applications over HTTP. Having the install automated will make that task easier.
Positive ideas and tutorials to help you deliver software solutions