Template Distribution

The Template Distribution document function automatically distributes files, fonts, and configuration files to endpoints (client machines). It is used primarily for external distribution templates and Outlook design templates.

note

This document function is available for external distribution templates and Outlook design templates.

Basic Structure

The root element is <Configuration>. The elements are expected in this order (all optional): Path, LockFile, Shortcut, UpdateMode, Files, Registry, Cleanup.

<Configuration>
  <Path>%APPDATA%\MyApp\</Path>
  <UpdateMode>Merge</UpdateMode>
  <Files>
    <File Source="config.xml" Target="settings\config.xml" />
    <File Source="logo.png" Target="assets\logo.png" />
  </Files>
</Configuration>

note

The configuration is scriptable: <If Condition="…"> blocks let you include or exclude elements depending on system variables (e.g. the installed Office version or bitness).

<Path>

Target path of the distribution. Environment variables (e.g. %APPDATA%, %USERPROFILE%) are resolved. With UpdateMode="ViaFiles", the path may be left empty.

<LockFile>

A file whose lock is checked before distribution. If the file cannot be opened exclusively (e.g. because the associated Office application has it open), the distribution is skipped.

<LockFile>Beispiel.ppam</LockFile>

<Shortcut>

Optional directory in which a Windows shortcut to the <LockFile> is created (e.g. required for Excel add-ins).

<Shortcut>%APPDATA%\Microsoft\Excel\XLSTART\</Shortcut>

<UpdateMode>

Controls how the distribution is carried out:

Value	Description
Merge	Existing files are added/updated, not deleted (default).
Replace	The target path is reconciled with the package content; surplus files are removed.
Remove	Removes the target directory (<Path>).
ViaFiles	Distributes individual files to individual targets as defined in <Files>.
InstallFont	Installs the included fonts system-wide.
RemoveFont	Uninstalls the included fonts.

<Files>

List of files to be distributed:

<Files>
  <File Source="vorlage.dotx" Target="Vorlagen\vorlage.dotx" />
  <File Target="%APPDATA%\MyApp\readme.txt">Content of the generated text file</File>
</Files>

Attribute	Description
Source	File name or pattern in the template package (e.g. vorlage.dotx or *.dotx). Optional.
Target	Target path/file name including environment variables. Required.

note

If you set the content of a <File> element (instead of Source), a text file with that content is created at the target — e.g. <File Target="…\theme.config">DemoStyle</File>.

Registry Actions (<Registry>)

Creates or updates registry keys and values. The actions run with the privileges of the current process and exclusively on HKCU.

<Registry>
  <RegistryKey Root="HKCU" View="Default" Key="Software\Microsoft\Office\16.0\PowerPoint\AddIns\MyAddIn" Action="CreateAndUpdate">
    <RegistryValue Type="String" Name="Path" Expand="true">%APPDATA%\MyAddIn\MyAddIn.ppam</RegistryValue>
    <RegistryValue Type="DWord" Name="AutoLoad">00000001</RegistryValue>
  </RegistryKey>
</Registry>

<RegistryKey>:

Attribute	Description
Key	Registry key path (e.g. Software\Microsoft\Office\16.0\…). Required.
View	Registry view: Default, Registry32, Registry64.
Root	Registry root — only HKCU is supported.
Action	CreateAndUpdate (default), Create, Update, Remove.

<RegistryValue> (child element of <RegistryKey>; the value is held in the element content):

Attribute	Description
Name	Name of the registry value. Required.
Type	Value type: String, ExpandString, Binary, DWord, MultiString, QWord (corresponding to REG_SZ, REG_EXPAND_SZ, REG_BINARY, REG_DWORD, REG_MULTI_SZ, REG_QWORD). Required.
Expand	When set to true, environment variables in the value are resolved.

Alternatively, a .reg file can be imported — optionally redirected into a specific key:

<Registry>
  <RegistryFile ImportInKey="HKEY_CURRENT_USER\Software\MyApp">deploy.reg</RegistryFile>
</Registry>

Cleanup (<Cleanup>)

Defines actions that are executed on uninstall or — depending on Mode — before each distribution:

<Cleanup Mode="OnCleanup">
  <File Path="%APPDATA%\MyApp" />
  <RegistryValue Root="HKCU" View="Default" Key="Software\Microsoft\Office\16.0\PowerPoint\AddIns\MyAddIn" Name="Path" />
  <RegistryKey Root="HKCU" View="Default" Key="Software\Microsoft\Office\16.0\PowerPoint\AddIns\MyAddIn" />
</Cleanup>

Mode value	Description
OnCleanup	On uninstall only (default).
OnCleanupAndDistribute	On uninstall and before each new distribution.

Element	Attributes
<File>	Path (file or directory to be deleted).
<RegistryKey>	Key, View — deletes the key.
<RegistryValue>	Key, View, Name — deletes the individual value.

Installing Fonts

<Configuration>
  <UpdateMode>InstallFont</UpdateMode>
  <Files>
    <File Source="CorporateFont-Regular.ttf" Target="" />
    <File Source="CorporateFont-Bold.ttf" Target="" />
  </Files>
</Configuration>

With <UpdateMode>InstallFont</UpdateMode>, the listed fonts are installed system-wide on the client.

Distributing Outlook Design Templates

For Outlook design templates, the package content is treated as a ZIP — for this, set SourceTemplateDocumentType="Zip" on the root element:

<Configuration SourceTemplateDocumentType="Zip">
  <UpdateMode>ViaFiles</UpdateMode>
  <Files>
    <File Source="*.dotx" Target="%APPDATA%\Microsoft\QuickStyles\DemoStyle.dotx" />
    <File Target="%APPDATA%\Microsoft\QuickStyles\Theme.config">DemoStyle</File>
  </Files>
  <Registry>
    <RegistryFile>mailsettings.reg</RegistryFile>
  </Registry>
</Configuration>