Deploying eM Client as an MSIX package

What changed from MSI

MSIX is the packaging format Windows uses for modern apps. It installs into a protected system folder, keeps the app separate from the rest of the system, and removes cleanly. Most of what you know from MSI has a direct equivalent, but the tools are different.

Upgrade from eM Client 10 (MSI)

An MSIX package can't upgrade an MSI installation. To move existing v10 machines to v11, use the transition MSI file from emclient.com/download-11. The MSI file doesn't contain the app itself. It does the following:

• uninstalls eM Client 10 and keeps the user database
• keeps file and protocol associations, such as eM Client being set as the default mail app
• installs eM Client 11 through the public .appinstaller file, so it needs internet access

On first start, eM Client 11 carries over the Run on startup setting and scheduled backup tasks from version 10.

If eM Client 11 was installed alongside version 10

Installing the MSIX directly, without the transition MSI, leaves eM Client 10 on the machine. Both apps use the same database, and once version 11 upgrades it, version 10 can no longer open it.

eM Client 11 detects this. When it finds an older eM Client 10 MSI installation, it shows a notification in the app with an Uninstall button:

• Uninstall starts the standard Windows Installer removal of eM Client 10. User data is kept. Windows asks for administrator rights, because version 10 was installed per machine.
• Later hides the notification for seven days. Closing it any other way doesn't postpone it, so it comes back on the next start.
• After version 10 is removed, eM Client 11 checks the Run on startup and backup settings again, so they point to version 11.

The files you work with

We publish three types of file. Normally a user only sees the first; for managed deployment you'll mostly use the second.

This is the .appinstaller file we publish, with notes on each part:

<AppInstaller Uri="https://licensing.emclient.com/api/update/emclient.appinstaller?version=11.0.xxxx"
              Version="11.0.xxxx.0"
              xmlns="http://schemas.microsoft.com/appx/appinstaller/2017">
  <!-- The package to install: name, publisher, version and download URL -->
  <MainBundle Name="eMClient.20054CA46072C"
              Publisher="CN=eM Client s.r.o., O=eM Client s.r.o., L=Praha 8, C=CZ"
              Version="11.0.xxxx.0"
              Uri="https://cdn-dist.emclient.com/dist/v11.0.xxxx/setup.msixbundle" />
  <!-- Check the AppInstaller Uri on the first line for a newer version when the app starts (at most once every 24 h) -->
  <UpdateSettings>
    <OnLaunch />
  </UpdateSettings>
</AppInstaller>

Download the MSIX bundle

This script reads the current .appinstaller and downloads the bundle it points to. Run it on any machine with internet access.

$src = 'https://licensing.emclient.com/api/update/emclient.appinstaller'
Invoke-WebRequest $src -OutFile .\emclient.appinstaller -UseBasicParsing
[xml]$ai = Get-Content .\emclient.appinstaller
$ver = $ai.AppInstaller.MainBundle.Version
Invoke-WebRequest $ai.AppInstaller.MainBundle.Uri -OutFile ".\emclient-$ver.msixbundle" -UseBasicParsing
"Downloaded eM Client $ver"

Install for all users on a machine

MSIX apps are always registered per user. The MSIX equivalent of a per-machine install is provisioning. You add the package to the Windows image once. Windows then registers it for every user at sign-in, including users who sign in for the first time later. The program files are stored once on the machine, not once per user.

PowerShell or DISM

Run elevated, for example from a startup script, an RMM tool or a task sequence:

Add-AppxProvisionedPackage -Online -PackagePath 'C:\Deploy\emclient-11.0.xxxx.0.msixbundle' -SkipLicense

# Check that it is provisioned
Get-AppxProvisionedPackage -Online | Where-Object DisplayName -like 'eMClient*'

DISM /Online /Add-ProvisionedAppxPackage /PackagePath:"C:\Deploy\emclient-11.0.xxxx.0.msixbundle" /SkipLicense

Users who are already signed in get the app at their next sign-in. To register it right away for the current user as well, run Add-AppxPackage -Path <bundle> in that user's session.

Deployment tools

Remove eM Client from all users

# Stop provisioning it for new users
Get-AppxProvisionedPackage -Online | Where-Object DisplayName -like 'eMClient*' |
    Remove-AppxProvisionedPackage -Online

# Remove it from every user who already has it
Get-AppxPackage -AllUsers 'eMClient*' | Remove-AppxPackage -AllUsers

Install for one user only

Without admin rights, a user can install for themselves from the bundle or from the .appinstaller. Installing from the .appinstaller also turns on automatic updates (see Updates).

# From the bundle: no automatic updates
Add-AppxPackage -Path '\\server\deploy\emclient-11.0.xxxx.0.msixbundle'

# From the .appinstaller: Windows keeps the app updated
Add-AppxPackage -AppInstallerFile 'https://licensing.emclient.com/api/update/emclient.appinstaller'

Offline install on machines without internet access

The .msixbundle contains the whole app. Once you have downloaded it (see Files), installing it doesn't need internet access. You have two options, depending on whether the machines should update themselves from an internal source.

Set up an internal update source (option B)

1. Download the bundle and copy it to an internal location, such as \\fs01\apps\emclient\ or https://intranet.example.local/emclient/.
2. Save a copy of the .appinstaller next to it and change both Uri attributes to point at your server. The .appinstaller isn't signed, so you can edit it. Don't change the .msixbundle, because that would break its signature.
3. Install on clients from your copy: Add-AppxPackage -AppInstallerFile \\fs01\apps\emclient\emclient.appinstaller.
4. To release a new version, copy in the new bundle and update the two Version attributes and the bundle Uri. Clients install it the next time they start eM Client and switch to it after they close and reopen the app.

<?xml version="1.0" encoding="utf-8"?>
<AppInstaller Uri="file://fs01/apps/emclient/emclient.appinstaller"
              Version="11.0.xxxx.0"
              xmlns="http://schemas.microsoft.com/appx/appinstaller/2017">
  <MainBundle Name="eMClient.20054CA46072C"
              Publisher="CN=eM Client s.r.o., O=eM Client s.r.o., L=Praha 8, C=CZ"
              Version="11.0.xxxx.0"
              Uri="file://fs01/apps/emclient/emclient-11.0.xxxx.0.msixbundle" />
  <UpdateSettings>
    <OnLaunch HoursBetweenUpdateChecks="24" />
  </UpdateSettings>
</AppInstaller>

Control updates

In eM Client 11, Windows handles updates, not eM Client itself. How updates behave depends on how the app was installed:

Pick a policy

Check, pause or turn off automatic updates

These commands change the update settings of an installed package. Run them in the user's session after eM Client has been started at least once, because eM Client sets its update address on first start.

# Show the current update settings (no output = no automatic updates)
Get-AppxPackageAutoUpdateSettings 'eMClient.20054CA46072C_veq4nz3ze5v72'

# Turn automatic updates off
Remove-AppxPackageAutoUpdateSettings 'eMClient.20054CA46072C_veq4nz3ze5v72'

# Or pause them, here for 30 days (720 hours)
Set-AppxPackageAutoUpdateSettings 'eMClient.20054CA46072C_veq4nz3ze5v72' -PauseUpdates -HoursToPause 720

Force an update now

Add-AppxPackage -AppInstallerFile ((Get-AppxPackageAutoUpdateSettings 'eMClient.20054CA46072C_veq4nz3ze5v72').AppInstallerUri)

Network requirements

If clients go online through a proxy or firewall, allow these hosts and exclude them from TLS inspection:

• licensing.emclient.com (the .appinstaller and update checks)
• cdn-dist.emclient.com (the .msixbundle downloads)
• http://*.lencr.org on port 80 (certificate revocation checks for the two hosts above)

Windows installs MSIX packages through a system service that rejects certificates replaced by a TLS-inspecting proxy. An install that fails with error 0x80072F8F is almost always caused by this.

Command reference

The commands use full cmdlet names. You can also use the standard PowerShell aliases, which work the same way: ? or where for Where-Object, and select for Select-Object.

Package family name: eMClient.20054CA46072C_veq4nz3ze5v72

Troubleshooting