Deploy Probistica

Probistica installs per user. Run the install in the context of each user, not as the system account and not as an administrator account. The install writes to %APPDATA%, %LOCALAPPDATA%, %TEMP%, and HKCU of the account that runs it. In a software deployment tool, select the user context.

The release package installs the add-in with:

  • Probistica-setup.exe, the setup program of the release package. It also adds an entry to Settings > Apps, copies itself for the uninstall, and copies the pages of the folder docs to %LOCALAPPDATA%\Programs\Probistica\docs for the Help button.

The release package also holds Probistica.Xdk.dll and Probistica.Xdk.xml, the .NET client for developers. The setup does not install them. Give them only to developers who write .NET code that controls Probistica inside Excel.

Commands of the setup program

The setup takes Probistica64.xll from its own folder, unless /xll gives another file. Without /quiet, it opens its window.

TaskCommand
Install, silentProbistica-setup.exe /install /quiet /log "%TEMP%\Probistica-setup.log"
Install another XLL fileProbistica-setup.exe /install /quiet /xll "<path>\Probistica64.xll" /log "<file>"
Report only (changes nothing)Probistica-setup.exe /report /quiet /log "<file>"
Uninstall, silent"%LOCALAPPDATA%\Programs\Probistica\Probistica-setup.exe" /uninstall /quiet /log "<file>"

The silent uninstall command is also the value QuietUninstallString of the entry HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\{6F85C95A-7B98-4DCA-BD2B-19159EB7CBBD}. The setup appends its lines to the log file and also writes them to the standard output. /report is the default mode.

Probistica-setup.exe is a Windows program, not a console program. A software deployment tool waits for it and reads its exit code. An interactive cmd prompt and PowerShell do not wait for it, and a console window does not show its lines. The standard output gets the lines only when the caller redirects it. Thus always give /log.

A refused command line ends with exit code 2. The setup shows the reason in a message box only when it runs in a session with a desktop (not session 0), without /quiet, without a /log file that it can write, and without a standard output. A silent switch of other installers (/s, /silent, /verysilent, /q, /qn, /qb, /passive) is an unknown option, so the setup refuses it, but it shows no message box.

To wait for the setup by hand and read its exit code:

  • At a cmd prompt: start "" /wait Probistica-setup.exe /install /quiet /log "<file>", then echo %ERRORLEVEL%.
  • In PowerShell: $p = Start-Process -FilePath .\Probistica-setup.exe -ArgumentList '/install /quiet /log "<file>"' -Wait -PassThru, then $p.ExitCode.

Exit codes

CodeMeaning
0Done, or nothing to do: the add-in is registered already, nothing was installed before an uninstall, or the report ended.
1Failure. Nothing was changed when the message ends with "Nothing was changed."
2Refusal. Nothing was changed.

The causes of exit code 1:

  • The XLL file does not exist.
  • The folder %APPDATA%\Microsoft\AddIns does not exist.
  • The name of the Options copy in %TEMP% exists already.
  • The export of the Options key with reg.exe failed.
  • The setup only: the XLL is the installed copy itself; the key HKCU\Software\Microsoft\Office\16.0\Excel\Options does not exist; APPDATA, LOCALAPPDATA, or TEMP is not a full path; the setup cannot read the current state; a step failed after the first change; the helper that deletes the installed setup did not start.

The causes of exit code 2:

  • An Excel process runs. The check counts every EXCEL process on the computer, also in the sessions of other users.
  • /install when Office is 32-bit: the value Platform of HKLM\SOFTWARE\Microsoft\Office\ClickToRun\Configuration (64-bit registry view) is x86. The message is "This Excel is 32-bit (the Click-to-Run value Platform is x86). Probistica needs 64-bit Excel. Nothing was changed." The uninstall still works.
  • /install when another Probistica64.xll is registered, that is, an OPEN value names a file Probistica64.xll in another folder.
  • /install when an OPEN value names a file atRISK64.xll in any folder. atRISK is the old working name of the add-in. Remove the old atRISK add-in first. When another Probistica64.xll is also registered, the same message names both.
  • /install when the file %APPDATA%\Microsoft\AddIns\atRISK64.xll exists, also without an OPEN value. The setup also refuses when the entry HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\{6F85C95A-7B98-4DCA-BD2B-19159EB7CBBD} has the DisplayName atRISK: the old atRISK setup used the same key. The uninstall of Probistica keeps that entry.
  • /install and /uninstall together.
  • The setup only: an unknown option, an option twice, an option without its value, /report with /install or /uninstall, or a log file that cannot be written.

Preconditions

  • Excel is closed. Close Excel in all sessions of the computer. On a terminal server, deploy when no user has Excel open.
  • 64-bit Excel. Probistica has no add-in for 32-bit Excel. For a Click-to-Run install of Office, the setup program reads the value Platform (see the causes of exit code 2) and refuses x86. An MSI install of Office has no such value. The setup program then does not check the bitness, so make sure that the Office of the computer is 64-bit.
  • The add-ins folder exists. %APPDATA%\Microsoft\AddIns must exist. A new profile can be without it. Create it before the install, for example with cmd /c mkdir "%APPDATA%\Microsoft\AddIns" in the user context.
  • The Excel options key exists (setup). The setup needs HKCU\Software\Microsoft\Office\16.0\Excel\Options. Excel makes the key at its first start. Without the key, the setup refuses with exit code 1.
  • The download mark. The setup writes new files, so the installed copies have no Mark of the Web.
  • The signatures of the package. A release package can be signed or unsigned. Its file manifest.txt tells you, for each program file (Probistica64.xll, Probistica-setup.exe, Probistica.Xdk.dll). An unsigned file has the line signature: unsigned. A signed file has a line signature: <status>, <subject of the certificate>, thumbprint <thumbprint> and a line timestamp: .... Read these lines before you make a rule. Get-AuthenticodeSignature -FilePath <file> in PowerShell shows the same data for an installed file.
  • Program rules (setup). Rules of AppLocker or of App Control for Business can block a program in a user folder. The setup runs from the release folder, from %LOCALAPPDATA%\Programs\Probistica, and, for the uninstall, from a folder %TEMP%\Probistica-setup-<32 hexadecimal digits>. For a signed setup, a publisher rule for the certificate that manifest.txt names lets it run from each of these folders. For an unsigned setup, use a file hash rule, or a path rule for each of these folders.
  • Excel add-in policy. With the Trust Center setting "Require Application Add-ins to be signed by Trusted Publisher", Excel loads only a signed XLL whose certificate is in the store Trusted Publishers of the user. For a signed XLL, deploy the certificate that manifest.txt names to that store, for example with a Group Policy. Excel does not load an unsigned XLL with this setting.

Detection rule

Use the installed file and its file version:

  • File: %APPDATA%\Microsoft\AddIns\Probistica64.xll
  • Property: FileVersion, for example 0.3.0.0 (the product version plus .0). The ProductVersion is the version without .0, for example 0.3.0.

For an install with the setup, the entry HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\{6F85C95A-7B98-4DCA-BD2B-19159EB7CBBD} with the value DisplayVersion is a second rule.

Update

Close Excel, and run the install of the new release. The setup program replaces %APPDATA%\Microsoft\AddIns\Probistica64.xll and keeps the OPEN value. The setup also updates its entry and its installed copy. License files and the settings in %APPDATA%\Probistica stay.

Roll back

  • To remove the version: run the uninstall.
  • To restore the add-in list of Excel exactly: each install and uninstall exports the Options key first, to %TEMP%\Probistica-install-options-<yyyyMMdd-HHmmss-fff>.reg. The file holds all values of the key. An import does not delete values that came later. Close Excel, delete the values OPEN, OPEN1, OPEN2, ... of HKCU\Software\Microsoft\Office\16.0\Excel\Options, and then run reg import "<file>".
  • To go back to an older version: run the install of the older release. The setup program does not compare versions.

Remove Probistica completely

Per user (in the context of each user, with Excel closed):

  1. Run the uninstall. It removes the OPEN values of Probistica, the Add-in Manager value, the AddInLoadTimes values of the installed path and of its ribbon name Dna_<GUID>_<n>, the XLL copy, and (setup) the entry and the installed setup program.
  2. If you want to remove the license data too, delete %LOCALAPPDATA%\Probistica\Licenses (the .lic files and state.json).
  3. Optional: delete %LOCALAPPDATA%\Probistica\ErrorReports (unsent error or support reports, including any text or reply e-mail typed after a failed Send).
  4. Optional: delete %APPDATA%\Probistica. It holds define-distribution.xml, the settings of the Define Distribution window, and the damaged copies of that file.
  5. Optional: delete the copies %TEMP%\Probistica-install-options-*.reg, the setup folders %TEMP%\Probistica-setup-* of an earlier uninstall, and %LOCALAPPDATA%\Programs\Probistica if a file remains there.
  6. Optional: delete HKCU\SOFTWARE\Policies\Probistica if you set it.

Per computer (as an administrator):

  1. Delete %PROGRAMDATA%\Probistica\Licenses if you put license files there.
  2. Delete HKLM\SOFTWARE\Policies\Probistica if you set it.
  3. Remove the license files from the share of LicensePath, if you use one.

The footprint of Probistica lists each item. The uninstall keeps the AddInLoadTimes values that Excel wrote for another path of the XLL, for example after a manual load from a download folder. They do no harm.