feat(bundler): add config for WiX banner path, closes #2175 (#2448)

Author: lucasfernog

.changes/bundler-wix-banner-icon.md

@@ -0,0 +1,6 @@
+---
+"tauri-bundler": patch
+---
+
+Added `banner_path` field to the `WixSettings` struct.
+

.changes/cli.rs-wix-banner-icon.md

@@ -0,0 +1,5 @@
+---
+"cli.rs": patch
+---
+
+Added configuration for the WiX banner icon under `tauri.conf.json > tauri > bundle > windows > wix > bannerPath`.

docs/api/config.md

@@ -175,7 +175,8 @@ In addition to the JSON defined on the `tauri.conf.json` file, Tauri reads a pla
           { property: "featureRefs", optional: true, type: "string[]", description: `The Feature element ids you want to reference from the fragments.` },
           { property: "mergeRefs", optional: true, type: "string[]", description: `The Merge element ids you want to reference from the fragments.` },
           { property: "skipWebviewInstall", optional: true, type: "boolean", description: `Disables the Webview2 runtime installation after app install.` },
-          { property: "license", optional: true, type: "string", description: `The path to the license file to render on the installer. Must be an RTF file, so if a different extension is provided, we convert it to the RTF format.` }]} />
+          { property: "license", optional: true, type: "string", description: `The path to the license file to render on the installer. Must be an RTF file, so if a different extension is provided, we convert it to the RTF format.` },
+          { property: "bannerPath", optional: true, type: "string", description: `Path to a bitmap file to use as the installation user interface banner. This bitmap will appear at the top of all but the first page of the installer. The required dimensions are 493px × 58px.` }]} />
         }
         ]} />
       },

tooling/bundler/src/bundle/settings.rs

@@ -198,8 +198,13 @@ pub struct WixSettings {
   pub skip_webview_install: bool,
   /// The path to the LICENSE file.
   pub license: Option<String>,
-  /// Create an elevated update task within Windows Task Scheduler
+  /// Create an elevated update task within Windows Task Scheduler.
   pub enable_elevated_update_task: bool,
+  /// Path to a bitmap file to use as the installation user interface banner.
+  /// This bitmap will appear at the top of all but the first page of the installer.
+  ///
+  /// The required dimensions are 493px × 58px.
+  pub banner_path: Option<PathBuf>,
 }
 
 /// The Windows bundle settings.

tooling/bundler/src/bundle/windows/msi/wix.rs

@@ -145,14 +145,14 @@ impl ResourceDirectory {
 
 /// Copies the icon to the binary path, under the `resources` folder,
 /// and returns the path to the file.
-fn copy_icon(settings: &Settings) -> crate::Result<PathBuf> {
+fn copy_icon(settings: &Settings, filename: &str, path: &Path) -> crate::Result<PathBuf> {
   let base_dir = settings.project_out_directory();
 
   let resource_dir = base_dir.join("resources");
   std::fs::create_dir_all(&resource_dir)?;
-  let icon_target_path = resource_dir.join("icon.ico");
+  let icon_target_path = resource_dir.join(filename);
 
-  let icon_path = std::env::current_dir()?.join(&settings.windows().icon_path);
+  let icon_path = std::env::current_dir()?.join(&path);
 
   copy_file(
     icon_path,
@@ -504,8 +504,8 @@ pub fn build_wix_app_installer(
 
   data.insert("app_exe_source", to_json(&app_exe_source));
 
-  // copy icon from $CWD/icons/icon.ico folder to resource folder near msi
-  let icon_path = copy_icon(settings)?;
+  // copy icon from `settings.windows().icon_path` folder to resource folder near msi
+  let icon_path = copy_icon(settings, "icon.ico", &settings.windows().icon_path)?;
 
   data.insert("icon_path", to_json(icon_path));
 
@@ -533,6 +533,19 @@ pub fn build_wix_app_installer(
         .expect("Failed to setup custom handlebar template");
       has_custom_template = true;
     }
+
+    if let Some(banner_path) = &wix.banner_path {
+      let filename = banner_path
+        .file_name()
+        .unwrap()
+        .to_string_lossy()
+        .into_owned()
+        .to_string();
+      data.insert(
+        "banner_path",
+        to_json(copy_icon(settings, &filename, banner_path)?),
+      );
+    }
   }
 
   if !has_custom_template {

tooling/bundler/src/bundle/windows/templates/main.wxs

@@ -31,7 +31,9 @@
 
         <Media Id="1" Cabinet="app.cab" EmbedCab="yes" />
 
-        <WixVariable Id="WixUIBannerBmp" Value="{{{icon_path}}}" />
+        {{#if banner_path}}
+        <WixVariable Id="WixUIBannerBmp" Value="{{{banner_path}}}" />
+        {{/if}}
         {{#if license}}
         <WixVariable Id="WixUILicenseRtf" Value="{{{license}}}" />
         {{/if}}

tooling/cli.rs/config_definition.rs

@@ -84,6 +84,11 @@ pub struct WixConfig {
   pub license: Option<String>,
   #[serde(default)]
   pub enable_elevated_update_task: bool,
+  /// Path to a bitmap file to use as the installation user interface banner.
+  /// This bitmap will appear at the top of all but the first page of the installer.
+  ///
+  /// The required dimensions are 493px × 58px.
+  pub banner_path: Option<PathBuf>,
 }
 
 #[derive(Debug, Default, PartialEq, Clone, Deserialize, Serialize, JsonSchema)]

tooling/cli.rs/schema.json

@@ -1324,6 +1324,13 @@
     "WixConfig": {
       "type": "object",
       "properties": {
+        "bannerPath": {
+          "description": "Path to a bitmap file to use as the installation user interface banner. This bitmap will appear at the top of all but the first page of the installer.\n\nThe required dimensions are 493px × 58px.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
         "componentGroupRefs": {
           "default": [],
           "type": "array",

tooling/cli.rs/src/helpers/config.rs

@@ -25,6 +25,7 @@ impl From<WixConfig> for tauri_bundler::WixSettings {
       skip_webview_install: config.skip_webview_install,
       license: config.license,
       enable_elevated_update_task: config.enable_elevated_update_task,
+      banner_path: config.banner_path,
     }
   }
 }