From 03bf92eb863f2ef37f3a2ef374e429c870d24239 Mon Sep 17 00:00:00 2001 From: FireGiant Docs Date: Wed, 14 May 2025 12:17:39 -0700 Subject: [PATCH 1/6] Update outdated references to Bal.wixext to BootstrapperApplications.wixext --- src/content/docs/wix/tools/burn/wixstdba.md | 2 +- src/content/docs/wix/tools/wixext/index.md | 11 +++++------ 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/src/content/docs/wix/tools/burn/wixstdba.md b/src/content/docs/wix/tools/burn/wixstdba.md index 0d0d322..0003236 100644 --- a/src/content/docs/wix/tools/burn/wixstdba.md +++ b/src/content/docs/wix/tools/burn/wixstdba.md @@ -7,7 +7,7 @@ WixStandardBootstrapperApplication (WixStdBA) is the "stock" bootstrapper applic ## WixStdBA themes -WixStdBA is included in the WixToolset.Bal.wixext WiX extension NuGet package. You need a reference to that package to use WixStdBA. +WixStdBA is included in the WixToolset.BootstrapperApplications.wixext WiX extension NuGet package. You need a reference to that package to use WixStdBA. WixStdBA includes several themes to choose between RTF and hyperlinks for licenses and small or large dialogs: diff --git a/src/content/docs/wix/tools/wixext/index.md b/src/content/docs/wix/tools/wixext/index.md index 8b3b348..d094c3a 100644 --- a/src/content/docs/wix/tools/wixext/index.md +++ b/src/content/docs/wix/tools/wixext/index.md @@ -8,7 +8,7 @@ The following WiX extensions are provided by the WiX team: | Extension | Documentation | | --------- | ------------- | -| WixToolset.Bal.wixext | [Bal schema](../../schema/bal/) | +| WixToolset.BootstrapperApplications.wixext | [Bal schema](../../schema/bal/) | | WixToolset.ComPlus.wixext | [Complus schema](../../schema/complus/) | | WixToolset.Dependency.wixext | [Dependency schema](../../schema/dependency/) | | WixToolset.DifxApp.wixext | [Difxapp schema](../../schema/difxapp/) | @@ -24,7 +24,6 @@ The following WiX extensions are provided by the WiX team: | WixToolset.Util.wixext | [Util schema](../../schema/util/) | | WixToolset.VisualStudio.wixext | [Vs schema](../../schema/vs/) | - ## Using extensions To use a WiX extension during the build of your project, you need to load the extension and reference its namespace in your WiX authoring. @@ -41,8 +40,8 @@ For example: ```xml wix extension add -g WixToolset.Util.wixext -wix extension add -g WixToolset.Bal.wixext -wix build Bundle.wxs Bundle.en-us.wxl -ext WixToolset.Util.wixext -ext WixToolset.Bal.wixext +wix extension add -g WixToolset.BootstrapperApplications.wixext +wix build Bundle.wxs Bundle.en-us.wxl -ext WixToolset.Util.wixext -ext WixToolset.BootstrapperApplications.wixext ``` @@ -52,7 +51,7 @@ WiX extensions are available as NuGet packages on NuGet.org. You can reference t ```xml - + ``` @@ -61,7 +60,7 @@ You might need to specify a version for WiX extension packages (such as when the ```xml - + ``` From 8f520c454138f7f0ce8cdf4498027ae0583f7adb Mon Sep 17 00:00:00 2001 From: FireGiant Docs Date: Fri, 7 Nov 2025 11:22:51 -0800 Subject: [PATCH 2/6] Add licensing notice to HeatWave Build Tools --- src/content/docs/heatwave/build-tools/driver.md | 4 ++++ .../docs/heatwave/build-tools/firegiant-licensing.md | 2 +- src/content/docs/heatwave/build-tools/harvesting/index.md | 4 ++++ src/content/docs/heatwave/build-tools/index.md | 2 +- src/content/docs/heatwave/build-tools/msix/index.md | 6 +++++- src/content/docs/heatwave/build-tools/protected-services.md | 4 ++++ 6 files changed, 19 insertions(+), 3 deletions(-) diff --git a/src/content/docs/heatwave/build-tools/driver.md b/src/content/docs/heatwave/build-tools/driver.md index 0958bb4..5ba7ac2 100644 --- a/src/content/docs/heatwave/build-tools/driver.md +++ b/src/content/docs/heatwave/build-tools/driver.md @@ -8,6 +8,10 @@ sidebar: The FireGiant Driver Extension can install, repair, upgrade, uninstall, and roll back kernel and file system drivers. This WiX Extension is very lightweight and robust and avoids all the complexity DifxApp requires to install plug and play (PnP) drivers. All you need is your system driver, FG-WiX and one line of XML. +:::caution[Licensed feature] +Like the other features in HeatWave Build Tools, a license file is required to use FireGiant Driver Extension. See the [FireGiant licensing documentation for more information](../firegiant-licensing/). +::: + Here is a snippet of .wxs code that can install a simple kernel driver: ```xml title=FooDriver.wxs diff --git a/src/content/docs/heatwave/build-tools/firegiant-licensing.md b/src/content/docs/heatwave/build-tools/firegiant-licensing.md index ad94bb7..243baa0 100644 --- a/src/content/docs/heatwave/build-tools/firegiant-licensing.md +++ b/src/content/docs/heatwave/build-tools/firegiant-licensing.md @@ -4,7 +4,7 @@ sidebar: order: 1 --- -The HeatWave Build Tools require a license file, a .fglic file, to be available on developer and build machines. The license file is only used by the build tools and does **not** need to be distributed with the built installation packages. You can download your license file from [your FireGiant Account's License page][lp]. +The HeatWave Build Tools require a license file, a `.fglic`, to be available on developer and build machines. The license file is only used by the build tools and does **not** need to be distributed with the built installation packages. You can download your license file from [your FireGiant Account's License page][lp]. ## License file placement diff --git a/src/content/docs/heatwave/build-tools/harvesting/index.md b/src/content/docs/heatwave/build-tools/harvesting/index.md index 98491ff..8eb8b6b 100644 --- a/src/content/docs/heatwave/build-tools/harvesting/index.md +++ b/src/content/docs/heatwave/build-tools/harvesting/index.md @@ -6,6 +6,10 @@ sidebar: Advanced Harvesting gathers resources from MSBuild project references, folders and self-registration to generate .wxs code that installs those resources. Advanced Harvesting takes great care to organize the harvested resources according to the Windows Installer's best practices. +:::caution[Licensed feature] +Like the other features in HeatWave Build Tools, a license file is required to use FireGiant Advanced Harvesting. See the [FireGiant licensing documentation for more information](../firegiant-licensing/). +::: + Harvesting is controlled by extension elements, `` and ``. To get started with Advanced Harvesting add a package reference to the `FireGiant.HeatWave.BuildTools.wixext` extension--via [Manage NuGet Packages][add] in your .wixproj. The parent element will act as the template for the harvesting. Let's look at a very simple example. Consider a *SetupProject1.wixproj* with a project reference to *ConsoleApplication1.csproj* which in turn has a project reference to *ClassLibrary1.csproj*. In *SetupProject1.wixproj*, list the outputs we want to harvest from the project by adding `HarvestOutputGroup` metadata. In this example, we'll harvest the build outputs and dependencies of *ConsoleApplication1.csproj*: diff --git a/src/content/docs/heatwave/build-tools/index.md b/src/content/docs/heatwave/build-tools/index.md index 3f4a3f7..3e359c7 100644 --- a/src/content/docs/heatwave/build-tools/index.md +++ b/src/content/docs/heatwave/build-tools/index.md @@ -5,7 +5,7 @@ title: About HeatWave Build Tools The HeatWave Build Tools extend the WiX Toolset by providing extensions and APIs that improve the development experience of installation packages and bundles. * [Advanced Harvesting](harvesting/) - the most flexible tooling to gather and organize files from project references and folders. -* [BundleApplication Framework]() - managed and native libraries to simplify the development of custom Burn-based bootstrapper applications. +* [Bundle Application Framework]() - managed and native libraries to simplify the development of custom Burn-based bootstrapper applications. * [MSIX Extension](msix/) - create MSIX packages from .wxs code. * [Driver Extension](driver/) - enhances MSI to install non-PnP, system-level drivers. diff --git a/src/content/docs/heatwave/build-tools/msix/index.md b/src/content/docs/heatwave/build-tools/msix/index.md index 19a0e6e..4030eff 100644 --- a/src/content/docs/heatwave/build-tools/msix/index.md +++ b/src/content/docs/heatwave/build-tools/msix/index.md @@ -2,7 +2,11 @@ title: FireGiant MSIX Extension description: Documentation how to use the FireGiant MSIX Extension sidebar: - order: 3 + order: 0 --- The FireGiant MSIX Extension allows you to create MSIX Packages with your existing .wxs source code. Only three additions need to be made to get started. Once complete, building your project will create both an MSI package and an MSIX package. + +:::caution[Licensed feature] +Like the other features in HeatWave Build Tools, a license file is required to use FireGiant MSIX Extension. See the [FireGiant licensing documentation for more information](../firegiant-licensing/). +::: diff --git a/src/content/docs/heatwave/build-tools/protected-services.md b/src/content/docs/heatwave/build-tools/protected-services.md index bf9fdfc..ffbba36 100644 --- a/src/content/docs/heatwave/build-tools/protected-services.md +++ b/src/content/docs/heatwave/build-tools/protected-services.md @@ -12,6 +12,10 @@ During installation, the FireGiant protected service extension: - Installs the ELAM driver private certificate. - Configures the service to launch as a protected service. +:::caution[Licensed feature] +Like the other features in HeatWave Build Tools, a license file is required to use FireGiant Protected Services Extension. See the [FireGiant licensing documentation for more information](../firegiant-licensing/). +::: + To use the protected service extension, add a reference to the `FireGiant.HeatWave.BuildTools.wixext` and access the extension by adding the following namespace to your .wxs code: ```xml title=ProtectedService.wxs From 66f194e9ab29272876f9020bb1099f1c5579eae5 Mon Sep 17 00:00:00 2001 From: FireGiant Docs Date: Fri, 7 Nov 2025 23:57:51 -0800 Subject: [PATCH 3/6] Add the FireGiant Bundle Application Framework API Reference --- astro.config.mjs | 5 +- .../bundleaction.md | 20 + .../bundleactionstate.md | 20 + .../bundleapplyphase.md | 14 + .../bundlecacheoperation.md | 15 + .../bundlecondition.md | 26 + .../bundleerrortype.md | 16 + .../bundlefeature.md | 100 +++ .../bundlefeaturestate.md | 15 + .../bundleinstallmessage.md | 26 + .../bundleoverallprogress.md | 45 ++ .../bundlepackage.md | 180 ++++++ .../bundlepackagecachetype.md | 13 + .../bundlepackageprogress.md | 66 ++ .../bundlepackagestate.md | 16 + .../bundlepackagetype.md | 23 + .../bundleprogressaction.md | 27 + .../bundlerelatedoperation.md | 17 + .../bundlerelatedpackage.md | 45 ++ .../bundlerelationtype.md | 20 + .../bundlerequeststate.md | 16 + .../bundleresolvesourcelocation.md | 38 ++ .../bundleresult.md | 27 + .../bundleresumetype.md | 17 + .../bundlesameversionaction.md | 14 + .../bundleuibase.md | 571 ++++++++++++++++++ .../bundleuiwindowcontext.md | 40 ++ .../firegiantbundleapplication.md | 32 + .../ibundleapplication.md | 441 ++++++++++++++ .../ibundleui.md | 552 +++++++++++++++++ .../ibundleuifactory.md | 25 + .../index.md | 43 ++ 32 files changed, 2524 insertions(+), 1 deletion(-) create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleaction.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleactionstate.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleapplyphase.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlecacheoperation.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlecondition.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleerrortype.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlefeature.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlefeaturestate.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleinstallmessage.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleoverallprogress.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlepackage.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlepackagecachetype.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlepackageprogress.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlepackagestate.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlepackagetype.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleprogressaction.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlerelatedoperation.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlerelatedpackage.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlerelationtype.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlerequeststate.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleresolvesourcelocation.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleresult.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleresumetype.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlesameversionaction.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleuibase.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleuiwindowcontext.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/firegiantbundleapplication.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/ibundleapplication.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/ibundleui.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/ibundleuifactory.md create mode 100644 src/content/docs/firegiant/api/firegiantbundleapplicationframework/index.md diff --git a/astro.config.mjs b/astro.config.mjs index 6ef954e..6a8a982 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -116,7 +116,10 @@ export default defineConfig({ ] }, ] }, - { label: 'API Reference', collapsed: true, autogenerate: { directory: '/wix/api' } }, + { label: 'API Reference', collapsed: true, items: [ + { label: 'FireGiant Bundle Application Framework API', collapsed: true, autogenerate: { directory: '/firegiant/api/firegiantbundleapplicationframework' } }, + { label: 'WiX Toolset API', collapsed: true, autogenerate: { directory: '/wix/api' } }, + ] }, { label: 'Schema Reference', collapsed: true, items: [ { label: 'WiX Core Schema', collapsed: true, autogenerate: { directory: '/wix/schema/wxs' } }, { label: 'Localization Schema', collapsed: true, autogenerate: { directory: '/wix/schema/wxl' } }, diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleaction.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleaction.md new file mode 100644 index 0000000..b8c0828 --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleaction.md @@ -0,0 +1,20 @@ +--- +title: BundleAction Enumeration +pagefind: false +--- +Bundle actions. +## Members +| Member | Description | +| ------ | ----------- | +| Cache | Cache bundle action. | +| Help | Help bundle action. | +| Install | Install bundle action. | +| Layout | Layout bundle action. | +| Modify | Modify bundle action. | +| Repair | Repair bundle action. | +| Uninstall | Uninstall bundle action. | +| Unknown | Unknown bundle action. | +| UpdateReplace | Update bundle action. | +| UpdateReplaceEmbedded | Update using embedded bundle action. | + +`FireGiant.BundleApplicationFramework v6.0.1` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleactionstate.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleactionstate.md new file mode 100644 index 0000000..995c533 --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleactionstate.md @@ -0,0 +1,20 @@ +--- +title: BundleActionState Enumeration +pagefind: false +--- +Action state for a package or bundle. +## Members +| Member | Description | +| ------ | ----------- | +| AdminInstall | Administrative install action state. | +| Install | Install action state. | +| MajorUpgrade | Major upgrade action state. | +| Mend | Mend action state. | +| MinorUpgrade | Minor upgrade action state. | +| Modify | Modify action state. | +| None | No action or do not change the action state. | +| Patch | Patch action state. | +| Repair | Repair action state. | +| Uninstall | Uninstall action state. | + +`FireGiant.BundleApplicationFramework v6.0.1` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleapplyphase.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleapplyphase.md new file mode 100644 index 0000000..d82fcdb --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleapplyphase.md @@ -0,0 +1,14 @@ +--- +title: BundleApplyPhase Enumeration +pagefind: false +--- +Apply phases of a bundle. +## Members +| Member | Description | +| ------ | ----------- | +| Acquire | Acquire (download/cache/verify) phase. | +| Execute | Execute (install/uninstall) phase. | +| Rollback | Rollback phase. | +| Unknown | Unknown apply phase. | + +`FireGiant.BundleApplicationFramework v6.0.1` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlecacheoperation.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlecacheoperation.md new file mode 100644 index 0000000..f1c236b --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlecacheoperation.md @@ -0,0 +1,15 @@ +--- +title: BundleCacheOperation Enumeration +pagefind: false +--- +Bundle cache operations. +## Members +| Member | Description | +| ------ | ----------- | +| Copy | Copy payload to cache. | +| Download | Download payload to cache. | +| Extract | Extract payload from containers to cache. | +| None | Payload source is not available. | +| Unknown | Unknown cache operation. | + +`FireGiant.BundleApplicationFramework v6.0.1` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlecondition.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlecondition.md new file mode 100644 index 0000000..c69171e --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlecondition.md @@ -0,0 +1,26 @@ +--- +title: BundleCondition Class +pagefind: false +--- +Condition evaluated during bundle initialization. +## Properties +| Property | Description | +| ------ | ----------- | +| [Condition](#condition) | Condition to evaluate. If the condition evaluates to false, Message is displayed and executionis blocked. | +| [Message](#message) | Message to be shown when the Condition fails. | +### Remarks +Use the bal:Condition element to add conditions to your bundle. + +`FireGiant.BundleApplicationFramework v6.0.1` +## Condition Property {#condition} +Condition to evaluate. If the condition evaluates to false, Message is displayed and executionis blocked. +### Declaration +```cs +public string Condition { get; set; } +``` +## Message Property {#message} +Message to be shown when the Condition fails. +### Declaration +```cs +public string Message { get; set; } +``` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleerrortype.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleerrortype.md new file mode 100644 index 0000000..b64ff27 --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleerrortype.md @@ -0,0 +1,16 @@ +--- +title: BundleErrorType Enumeration +pagefind: false +--- +Types of error. +## Members +| Member | Description | +| ------ | ----------- | +| Apply | Failure during apply phase. | +| Elevate | Failure during elevation. | +| ExePackage | Failure from an executable package. | +| HttpProxyAuthentication | Failure to authenticate with an HTTP proxy. | +| HttpServerAuthentication | Failure to authenticate with an HTTP server. | +| WindowsInstaller | Failure from Windows Installer. | + +`FireGiant.BundleApplicationFramework v6.0.1` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlefeature.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlefeature.md new file mode 100644 index 0000000..95ad699 --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlefeature.md @@ -0,0 +1,100 @@ +--- +title: BundleFeature Class +pagefind: false +--- +Details about a feature that is part of a Bundle's package. +## Properties +| Property | Description | +| ------ | ----------- | +| [Attributes](#attributes) | The default remote execution option for the feature. | +| [Description](#description) | Description of the package. | +| [Display](#display) | The number in this field specifies the order in which the feature is to be displayed in the user interface. + The value also determines whether or not the feature is initially displayed expanded or collapsed. If the value is null or 0 (zero), the record is not displayed. + If the value is odd, the feature node is expanded initially. + If the value is even, the feature node is collapsed initially. | +| [Id](#id) | Unique identity of the feature in the package. | +| [Level](#level) | The installation level of this feature. | +| [PackageId](#packageid) | Unique identity of the package in the chain. | +| [ParentId](#parentid) | Optional identity of the parent of a feature in the package. | +| [RequestState](#requeststate) | Request state for the feature. | +| [RequestStateSet](#requeststateset) | Indicates whether the request state was explicitly set by the BundleUI. | +| [Size](#size) | Size of the files contained in the feature. | +| [State](#state) | Feature state. | +| [Title](#title) | Title of feature in the package. | + +`FireGiant.BundleApplicationFramework v6.0.1` +## Attributes Property {#attributes} +The default remote execution option for the feature. +### Declaration +```cs +public int Attributes { get; set; } +``` +## Description Property {#description} +Description of the package. +### Declaration +```cs +public string Description { get; set; } +``` +## Display Property {#display} +The number in this field specifies the order in which the feature is to be displayed in the user interface. + The value also determines whether or not the feature is initially displayed expanded or collapsed. If the value is null or 0 (zero), the record is not displayed. + If the value is odd, the feature node is expanded initially. + If the value is even, the feature node is collapsed initially. +### Declaration +```cs +public int Display { get; set; } +``` +## Id Property {#id} +Unique identity of the feature in the package. +### Declaration +```cs +public string Id { get; set; } +``` +## Level Property {#level} +The installation level of this feature. +### Declaration +```cs +public int Level { get; set; } +``` +## PackageId Property {#packageid} +Unique identity of the package in the chain. +### Declaration +```cs +public string PackageId { get; set; } +``` +## ParentId Property {#parentid} +Optional identity of the parent of a feature in the package. +### Declaration +```cs +public string ParentId { get; set; } +``` +## RequestState Property {#requeststate} +Request state for the feature. +### Declaration +```cs +public BundleFeatureState RequestState { get; set; } +``` +## RequestStateSet Property {#requeststateset} +Indicates whether the request state was explicitly set by the BundleUI. +### Declaration +```cs +public bool RequestStateSet { get; set; } +``` +## Size Property {#size} +Size of the files contained in the feature. +### Declaration +```cs +public int Size { get; set; } +``` +## State Property {#state} +Feature state. +### Declaration +```cs +public BundleFeatureState State { get; set; } +``` +## Title Property {#title} +Title of feature in the package. +### Declaration +```cs +public string Title { get; set; } +``` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlefeaturestate.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlefeaturestate.md new file mode 100644 index 0000000..3fc3712 --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlefeaturestate.md @@ -0,0 +1,15 @@ +--- +title: BundleFeatureState Enumeration +pagefind: false +--- +Feature state. +## Members +| Member | Description | +| ------ | ----------- | +| Absent | Feature is not installed. | +| Advertised | Feature is advertised. | +| Local | Feature is installed locally. | +| Source | Feature is installed run from source. | +| Unknown | Feature state is unkown. | + +`FireGiant.BundleApplicationFramework v6.0.1` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleinstallmessage.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleinstallmessage.md new file mode 100644 index 0000000..67903e7 --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleinstallmessage.md @@ -0,0 +1,26 @@ +--- +title: BundleInstallMessage Enumeration +pagefind: false +--- +Types of messages sent during apply. +## Members +| Member | Description | +| ------ | ----------- | +| ActionData | Data from an action. | +| ActionStart | Start of an action. | +| CommonData | Data sent by Windows Installer. | +| Error | Error. | +| FatalExit | Fatal exit. | +| FilesInUse | Files in use prompt. | +| Info | Informational message. | +| Initialize | Initialize message. | +| OutOfDiskSpace | Out of disk space error. | +| Progress | Progress from an action. | +| ResolveSource | Source resolution prompt. | +| RMFilesInUse | Restart manager files in use prompt. | +| ShowDialog | Show dialog prompt. | +| Terminate | Terminate message. | +| User | Message requiring user interaction. | +| Warning | Warning. | + +`FireGiant.BundleApplicationFramework v6.0.1` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleoverallprogress.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleoverallprogress.md new file mode 100644 index 0000000..6c168e9 --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleoverallprogress.md @@ -0,0 +1,45 @@ +--- +title: BundleOverallProgress Class +pagefind: false +--- +Overall progress during apply. +## Properties +| Property | Description | +| ------ | ----------- | +| [CachePercentage](#cachepercentage) | Percentage of cache complete. | +| [ExecutePercentage](#executepercentage) | Percentage of execution complete. | +| [OverallPercentage](#overallpercentage) | Overall percentage complete. | +| [RestartRequired](#restartrequired) | Indicates when an restart required. | +| [ShowUI](#showui) | Indicates whether UI should be displayed. | + +`FireGiant.BundleApplicationFramework v6.0.1` +## CachePercentage Property {#cachepercentage} +Percentage of cache complete. +### Declaration +```cs +public int CachePercentage { get; set; } +``` +## ExecutePercentage Property {#executepercentage} +Percentage of execution complete. +### Declaration +```cs +public int ExecutePercentage { get; set; } +``` +## OverallPercentage Property {#overallpercentage} +Overall percentage complete. +### Declaration +```cs +public int OverallPercentage { get; set; } +``` +## RestartRequired Property {#restartrequired} +Indicates when an restart required. +### Declaration +```cs +public bool RestartRequired { get; set; } +``` +## ShowUI Property {#showui} +Indicates whether UI should be displayed. +### Declaration +```cs +public bool ShowUI { get; set; } +``` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlepackage.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlepackage.md new file mode 100644 index 0000000..7af52f3 --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlepackage.md @@ -0,0 +1,180 @@ +--- +title: BundlePackage Class +pagefind: false +--- +Details about a package that is part of the Bundle's chain. +## Properties +| Property | Description | +| ------ | ----------- | +| [ApplyPhase](#applyphase) | Apply phase of the package. | +| [Cached](#cached) | Indicates whether any part of the package is cached. | +| [CacheOperation](#cacheoperation) | Cache operation used to cache the package. | +| [CacheType](#cachetype) | Cache type of the package. | +| [Description](#description) | Description of the package. | +| [DetectResult](#detectresult) | Status result of the package at completion of Bundle detect processing. | +| [DisplayInternalUI](#displayinternalui) | Indicates whether an MSI is allowed to display its internal UI. | +| [DisplayName](#displayname) | Display name for the package. | +| [ExecuteAction](#executeaction) | Execute action for the package. | +| [Features](#features) | Features in the package. | +| [Id](#id) | Unique identity of the package in the chain. | +| [InstallCondition](#installcondition) | Installation condition provided on the package. | +| [Permanent](#permanent) | Indicates whether the package is permanent. | +| [ProductCode](#productcode) | Product code of an MSI package. | +| [RelatedPackages](#relatedpackages) | Related packages to the package. | +| [RequestState](#requeststate) | Request state for the package. | +| [RequestStateSet](#requeststateset) | Indicates whether the request state was explicitly set by the BundleUI. | +| [RollbackAction](#rollbackaction) | Rollback action for the package. | +| [SameVersionAction](#sameversionaction) | Indicates whether the package is allowed to execute same version upgrades. | +| [State](#state) | Package state. | +| [Type](#type) | Package type. | +| [UpgradeCode](#upgradecode) | Upgrade code of an MSI package. | +| [Version](#version) | Version of the package. | +| [Vital](#vital) | Indicates whether failure to install the package will fail the chain. | + +`FireGiant.BundleApplicationFramework v6.0.1` +## ApplyPhase Property {#applyphase} +Apply phase of the package. +### Declaration +```cs +public BundleApplyPhase ApplyPhase { get; set; } +``` +## Cached Property {#cached} +Indicates whether any part of the package is cached. +### Declaration +```cs +public bool Cached { get; set; } +``` +## CacheOperation Property {#cacheoperation} +Cache operation used to cache the package. +### Declaration +```cs +public BundleCacheOperation CacheOperation { get; set; } +``` +## CacheType Property {#cachetype} +Cache type of the package. +### Declaration +```cs +public BundlePackageCacheType CacheType { get; set; } +``` +## Description Property {#description} +Description of the package. +### Declaration +```cs +public string Description { get; set; } +``` +## DetectResult Property {#detectresult} +Status result of the package at completion of Bundle detect processing. +### Declaration +```cs +public int DetectResult { get; set; } +``` +## DisplayInternalUI Property {#displayinternalui} +Indicates whether an MSI is allowed to display its internal UI. +### Declaration +```cs +public bool DisplayInternalUI { get; set; } +``` +## DisplayName Property {#displayname} +Display name for the package. +### Declaration +```cs +public string DisplayName { get; set; } +``` +## ExecuteAction Property {#executeaction} +Execute action for the package. +### Declaration +```cs +public BundleActionState ExecuteAction { get; set; } +``` +## Features Property {#features} +Features in the package. +### Declaration +```cs +public IEnumerable{BundleFeature} Features { get; set; } +``` +## Id Property {#id} +Unique identity of the package in the chain. +### Declaration +```cs +public string Id { get; set; } +``` +## InstallCondition Property {#installcondition} +Installation condition provided on the package. +### Declaration +```cs +public string InstallCondition { get; set; } +``` +## Permanent Property {#permanent} +Indicates whether the package is permanent. +### Declaration +```cs +public bool Permanent { get; set; } +``` +## ProductCode Property {#productcode} +Product code of an MSI package. +### Declaration +```cs +public string ProductCode { get; set; } +``` +## RelatedPackages Property {#relatedpackages} +Related packages to the package. +### Declaration +```cs +public IEnumerable{BundleRelatedPackage} RelatedPackages { get; set; } +``` +## RequestState Property {#requeststate} +Request state for the package. +### Declaration +```cs +public BundleRequestState RequestState { get; set; } +``` +## RequestStateSet Property {#requeststateset} +Indicates whether the request state was explicitly set by the BundleUI. +### Declaration +```cs +public bool RequestStateSet { get; set; } +``` +## RollbackAction Property {#rollbackaction} +Rollback action for the package. +### Declaration +```cs +public BundleActionState RollbackAction { get; set; } +``` +## SameVersionAction Property {#sameversionaction} +Indicates whether the package is allowed to execute same version upgrades. +### Declaration +```cs +public BundleSameVersionAction SameVersionAction { get; set; } +``` +## State Property {#state} +Package state. +### Declaration +```cs +public BundlePackageState State { get; set; } +``` +### Remarks +This state is updated as the bundle is applied. +## Type Property {#type} +Package type. +### Declaration +```cs +public BundlePackageType Type { get; set; } +``` +## UpgradeCode Property {#upgradecode} +Upgrade code of an MSI package. +### Declaration +```cs +public string UpgradeCode { get; set; } +``` +## Version Property {#version} +Version of the package. +### Declaration +```cs +public WixToolset.Versioning.WixVersion Version { get; set; } +``` +## Vital Property {#vital} +Indicates whether failure to install the package will fail the chain. +### Declaration +```cs +public bool Vital { get; set; } +``` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlepackagecachetype.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlepackagecachetype.md new file mode 100644 index 0000000..6f8d878 --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlepackagecachetype.md @@ -0,0 +1,13 @@ +--- +title: BundlePackageCacheType Enumeration +pagefind: false +--- +Cache type for package. +## Members +| Member | Description | +| ------ | ----------- | +| Always | Cache the package even if it is not being installed. | +| No | Do not cache package | +| Yes | Cache the package if it is being installed. | + +`FireGiant.BundleApplicationFramework v6.0.1` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlepackageprogress.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlepackageprogress.md new file mode 100644 index 0000000..3e4b3c3 --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlepackageprogress.md @@ -0,0 +1,66 @@ +--- +title: BundlePackageProgress Class +pagefind: false +--- +Progress of a package. +## Properties +| Property | Description | +| ------ | ----------- | +| [Action](#action) | Current progress action. | +| [CachePercentage](#cachepercentage) | Cache percentage complete for the package. | +| [ExecutePercentage](#executepercentage) | Execution percentage complete for the package. | +| [OverallPercentage](#overallpercentage) | Overall percentage complete for the package. | +| [Package](#package) | Package in progress. | +| [Phase](#phase) | Current apply phase. | +| [RestartRequired](#restartrequired) | Indicates whether the package required a restart. | +| [ShowUI](#showui) | Indicates whether UI should be displayed. | + +`FireGiant.BundleApplicationFramework v6.0.1` +## Action Property {#action} +Current progress action. +### Declaration +```cs +public BundleProgressAction Action { get; set; } +``` +## CachePercentage Property {#cachepercentage} +Cache percentage complete for the package. +### Declaration +```cs +public int CachePercentage { get; set; } +``` +## ExecutePercentage Property {#executepercentage} +Execution percentage complete for the package. +### Declaration +```cs +public int ExecutePercentage { get; set; } +``` +## OverallPercentage Property {#overallpercentage} +Overall percentage complete for the package. +### Declaration +```cs +public int OverallPercentage { get; set; } +``` +## Package Property {#package} +Package in progress. +### Declaration +```cs +public BundlePackage Package { get; set; } +``` +## Phase Property {#phase} +Current apply phase. +### Declaration +```cs +public BundleApplyPhase Phase { get; set; } +``` +## RestartRequired Property {#restartrequired} +Indicates whether the package required a restart. +### Declaration +```cs +public bool RestartRequired { get; set; } +``` +## ShowUI Property {#showui} +Indicates whether UI should be displayed. +### Declaration +```cs +public bool ShowUI { get; set; } +``` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlepackagestate.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlepackagestate.md new file mode 100644 index 0000000..9d91fb4 --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlepackagestate.md @@ -0,0 +1,16 @@ +--- +title: BundlePackageState Enumeration +pagefind: false +--- +Package state. +## Members +| Member | Description | +| ------ | ----------- | +| Absent | Package is not installed. | +| Cached | No longer used, see the BundlePackage.Cached property instead. | +| Obsolete | Package is obsolete. | +| Present | Package is installed. | +| Superseded | Package is superseded by another package. | +| Unknown | Package state is unkown. | + +`FireGiant.BundleApplicationFramework v6.0.1` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlepackagetype.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlepackagetype.md new file mode 100644 index 0000000..b794663 --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlepackagetype.md @@ -0,0 +1,23 @@ +--- +title: BundlePackageType Enumeration +pagefind: false +--- +Package type. +## Members +| Member | Description | +| ------ | ----------- | +| BundleAddon | Addon bundle to this bundle. | +| BundleDependentAddon | This bundle is an addon to the related bundle. | +| BundleDependentPatch | This bundle is a patch for the related bundle. | +| BundleDetect | Arbitrary detected bundle (`RelatedBundle/@Action=Detect`). | +| BundleNested | Bundle is part of chain in this bundle. | +| BundlePatch | Patch bundle for this bundle. | +| BundleUpdate | Related bundle is newer than this bundle. | +| BundleUpgrade | Upgrade code is shared with this bundle. | +| Exe | Executable package. | +| Msi | MSI package. | +| Msp | MSP patch. | +| Msu | MSU package. | +| Unknown | Unknown package type. | + +`FireGiant.BundleApplicationFramework v6.0.1` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleprogressaction.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleprogressaction.md new file mode 100644 index 0000000..2289dc2 --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleprogressaction.md @@ -0,0 +1,27 @@ +--- +title: BundleProgressAction Enumeration +pagefind: false +--- +Progress for a bundle +## Members +| Member | Description | +| ------ | ----------- | +| CacheCopy | Copying payloads to cache. | +| CacheDownload | Download payloads to cache. | +| CacheExtract | Extract payloads to cache. | +| ExecuteAdminInstall | Executing administrative install. | +| ExecuteInstall | Executing install. | +| ExecuteMajorUpgrade | Executing major upgrade. | +| ExecuteMend | Executing mend. | +| ExecuteMinorUpgrade | Executing minor upgrade. | +| ExecuteModify | Executing modify. | +| ExecutePatch | Executing patch. | +| ExecuteRepair | Executing repair. | +| ExecuteUninstall | Executing uninstall. | +| FirstCacheAction | First action in range of cache actions. | +| FirstExecuteAction | First action in range of execute actions. | +| LastCacheAction | Last action in range of cache actions. | +| LastExecuteAction | Last action in range of execution actions. | +| Unknown | Unknown progress action. | + +`FireGiant.BundleApplicationFramework v6.0.1` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlerelatedoperation.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlerelatedoperation.md new file mode 100644 index 0000000..5d60add --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlerelatedoperation.md @@ -0,0 +1,17 @@ +--- +title: BundleRelatedOperation Enumeration +pagefind: false +--- +Relation types between packages. +## Members +| Member | Description | +| ------ | ----------- | +| Downgrade | The related package will be downgraded. | +| Install | The related package will be installed. | +| MajorUpgrade | The related package will be upgraded as a major revision. | +| MinorUpgrade | The related package will be upgraded as a minor revision. | +| None | No related operation. | +| Remove | The related package will be removed. | +| Repair | The related package will be repaired. | + +`FireGiant.BundleApplicationFramework v6.0.1` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlerelatedpackage.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlerelatedpackage.md new file mode 100644 index 0000000..3d63f6a --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlerelatedpackage.md @@ -0,0 +1,45 @@ +--- +title: BundleRelatedPackage Class +pagefind: false +--- +Details about a related package to a Bundle's package that was detected. +## Properties +| Property | Description | +| ------ | ----------- | +| [Operation](#operation) | Operation of the package relative to the related package. | +| [PackageId](#packageid) | Unique identity of the package in the chain. | +| [PerMachine](#permachine) | Indicates whether the related package is installed per-machine. | +| [ProductCode](#productcode) | Product code of the related package. | +| [Version](#version) | Version of the related package. | + +`FireGiant.BundleApplicationFramework v6.0.1` +## Operation Property {#operation} +Operation of the package relative to the related package. +### Declaration +```cs +public BundleRelatedOperation Operation { get; set; } +``` +## PackageId Property {#packageid} +Unique identity of the package in the chain. +### Declaration +```cs +public string PackageId { get; set; } +``` +## PerMachine Property {#permachine} +Indicates whether the related package is installed per-machine. +### Declaration +```cs +public bool PerMachine { get; set; } +``` +## ProductCode Property {#productcode} +Product code of the related package. +### Declaration +```cs +public string ProductCode { get; set; } +``` +## Version Property {#version} +Version of the related package. +### Declaration +```cs +public WixToolset.Versioning.WixVersion Version { get; set; } +``` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlerelationtype.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlerelationtype.md new file mode 100644 index 0000000..5fbf5f1 --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlerelationtype.md @@ -0,0 +1,20 @@ +--- +title: BundleRelationType Enumeration +pagefind: false +--- +Relation types between bundles. +## Members +| Member | Description | +| ------ | ----------- | +| Addon | The related bundle is an add-on for the running bundle. | +| ChainPackage | The related bundle is in the running bundle's chain. | +| Dependent | Dependent relationship. | +| DependentAddon | The running bundle is an add-on for the related bundle. | +| DependentPatch | The running bundle is a patch for the related bundle. | +| Detect | The related bundle is detected by the running bundle. | +| None | No relation. | +| Patch | The related bundle is a patch for the running bundle. | +| Update | The related bundle is a newer version of the running bundle. | +| Upgrade | The related bundle shares an upgrade code with the running bundle. | + +`FireGiant.BundleApplicationFramework v6.0.1` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlerequeststate.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlerequeststate.md new file mode 100644 index 0000000..f01dd7f --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlerequeststate.md @@ -0,0 +1,16 @@ +--- +title: BundleRequestState Enumeration +pagefind: false +--- +Request state. +## Members +| Member | Description | +| ------ | ----------- | +| Absent | Uninstall and remove from cache. | +| Cache | Cache if not installed, uninstall if installed. | +| ForceAbsent | Force removal of bundle or package, including permanent packages. | +| None | No request state or no change to request state. | +| Present | Install if not present. | +| Repair | Repair if installed, install if not installed. | + +`FireGiant.BundleApplicationFramework v6.0.1` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleresolvesourcelocation.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleresolvesourcelocation.md new file mode 100644 index 0000000..8ea5846 --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleresolvesourcelocation.md @@ -0,0 +1,38 @@ +--- +title: BundleResolveSourceLocation Class +pagefind: false +--- +Updates payload source locations. +## Properties +| Property | Description | +| ------ | ----------- | +| [NewDownloadSource](#newdownloadsource) | Optional new URL to download payload. | +| [NewLocalSource](#newlocalsource) | Optional new path to payload. | +| [ProxyUserName](#proxyusername) | Optional username for download authentication. | +| [ProxyUserPassword](#proxyuserpassword) | Optional password for download authentication. | + +`FireGiant.BundleApplicationFramework v6.0.1` +## NewDownloadSource Property {#newdownloadsource} +Optional new URL to download payload. +### Declaration +```cs +public string NewDownloadSource { get; set; } +``` +## NewLocalSource Property {#newlocalsource} +Optional new path to payload. +### Declaration +```cs +public string NewLocalSource { get; set; } +``` +## ProxyUserName Property {#proxyusername} +Optional username for download authentication. +### Declaration +```cs +public string ProxyUserName { get; set; } +``` +## ProxyUserPassword Property {#proxyuserpassword} +Optional password for download authentication. +### Declaration +```cs +public string ProxyUserPassword { get; set; } +``` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleresult.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleresult.md new file mode 100644 index 0000000..f07909e --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleresult.md @@ -0,0 +1,27 @@ +--- +title: BundleResult Enumeration +pagefind: false +--- +Bundle result. +## Members +| Member | Description | +| ------ | ----------- | +| Abort | Abort result. | +| Cancel | Cancel result. | +| Close | Close result. | +| Continue | Continue result. | +| Download | Download result. | +| Error | Error result. | +| Help | Help result. | +| Ignore | Ignore result. | +| No | No result. | +| None | No result. | +| Ok | Ok result. | +| Restart | Restart result. | +| Retry | Retry result. | +| Suspend | Suspend result. | +| Timeout | Timeout result. | +| TryAgain | Try again result. | +| Yes | Yes result. | + +`FireGiant.BundleApplicationFramework v6.0.1` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleresumetype.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleresumetype.md new file mode 100644 index 0000000..3a2c54b --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleresumetype.md @@ -0,0 +1,17 @@ +--- +title: BundleResumeType Enumeration +pagefind: false +--- +Resume type. +## Members +| Member | Description | +| ------ | ----------- | +| Arp | Launched via Add/Remove Programs (aka: Programs and Features). | +| Interrupted | Interrupted installation resumed. | +| Invalid | Invalid resume type. | +| None | Not resumed. | +| Reboot | Resumed post-restart. | +| RebootPending | Restart pending from previous installation. | +| Suspend | Resumed from suspended install. | + +`FireGiant.BundleApplicationFramework v6.0.1` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlesameversionaction.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlesameversionaction.md new file mode 100644 index 0000000..c3341b1 --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundlesameversionaction.md @@ -0,0 +1,14 @@ +--- +title: BundleSameVersionAction Enumeration +pagefind: false +--- +Action to take when bundles have same version. +## Members +| Member | Description | +| ------ | ----------- | +| InstallSideBySide | Install side by side. | +| Unknown | Fail installation. | +| Unkown | Fail installation. | +| Upgrade | Upgrade same version. | + +`FireGiant.BundleApplicationFramework v6.0.1` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleuibase.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleuibase.md new file mode 100644 index 0000000..a51af14 --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleuibase.md @@ -0,0 +1,571 @@ +--- +title: BundleUIBase Class +pagefind: false +--- +Base BundleUI that provides default implementation for IBundleUI. +## Methods +| Method | Description | +| ------ | ----------- | +| [CreateWindow()](#createwindow_nop) | | +| [InitializeSynchronizationContext()](#initializesynchronizationcontext_nop) | Obsolete. Use CreateWindow() to return the desired synchronization context. | +| [OnCompleteCancel(bool, bool)](#oncompletecancel_bool_bool) | Callback when the bundle application is canceled. | +| [OnCompleteFailure(bool, int, bool)](#oncompletefailure_bool_int_bool) | Callback when the bundle application fails. | +| [OnCompleteSuccess(bool, bool)](#oncompletesuccess_bool_bool) | Callback when the bundle application succeeds. | +| [OnConditionFailure(BundleCondition, string)](#onconditionfailure_bundlecondition_string) | Callback when a condition fails. | +| [OnDowngradeAllowed(string, bool)](#ondowngradeallowed_string_bool) | Callback when a newer bundle is detected. | +| [OnError(BundleErrorType, string, int, string, int, BundleResult)](#onerror_bundleerrortype_string_int_string_int_bundleresult) | Callback when an overall bundle appliation error occurs. | +| [OnForceReboot(int, bool)](#onforcereboot_int_bool) | Callback when the Burn engine forces a restart. | +| [OnInitializeHelp()](#oninitializehelp_nop) | Callback before help will be started. | +| [OnInitializeInstall(bool)](#oninitializeinstall_bool) | Callback before install will be started. | +| [OnInitializeLayout()](#oninitializelayout_nop) | Callback before layout will be started. | +| [OnInitializeModify(bool)](#oninitializemodify_bool) | Callback before modify will be started. | +| [OnInitializeRepair(bool)](#oninitializerepair_bool) | Callback before repair will be started. | +| [OnInitializeUninstall(bool)](#oninitializeuninstall_bool) | Callback before uninstall will be started. | +| [OnMsiMessage(BundlePackage, BundleInstallMessage, string, int, string[], bool)](#onmsimessage_bundlepackage_bundleinstallmessage_string_int_string[]_bool) | Callback when Windows Installer send an message. | +| [OnPackageComplete(BundlePackage, BundleProgressAction, int)](#onpackagecomplete_bundlepackage_bundleprogressaction_int) | Callback when action on package is complete. | +| [OnPackageProgress(BundlePackageProgress)](#onpackageprogress_bundlepackageprogress) | Callback on overall package progress update. | +| [OnProgress(BundleOverallProgress)](#onprogress_bundleoverallprogress) | Callback on overall progress update. | +| [OnResolveSource(string, string, string[], BundleResolveSourceLocation)](#onresolvesource_string_string_string[]_bundleresolvesourcelocation) | Callback when payload or container cannot be located. | +| [OnSameVersionInstalled(string, string, bool, WixToolset.Versioning.WixVersion)](#onsameversioninstalled_string_string_bool_wixtoolsetversioningwixversion) | Callback when a bundle with the same is detected. | +| [OnStartHelp(bool)](#onstarthelp_bool) | Callback when help should be displayed. | +| [OnStartInstall(bool)](#onstartinstall_bool) | Callback when installation preparation should begin. | +| [OnStartLayout(bool)](#onstartlayout_bool) | Callback when layout preparation should begin. | +| [OnStartModify(bool)](#onstartmodify_bool) | Callback when modify preparation should begin. | +| [OnStartProgressInstall(bool)](#onstartprogressinstall_bool) | Callback when installation progress should begin. | +| [OnStartProgressLayout(bool)](#onstartprogresslayout_bool) | Callback when layout progress should begin. | +| [OnStartProgressModify(bool)](#onstartprogressmodify_bool) | Callback when modify progress should begin. | +| [OnStartProgressRepair(bool)](#onstartprogressrepair_bool) | Callback when repair progress should begin. | +| [OnStartProgressUninstall(bool)](#onstartprogressuninstall_bool) | Callback when uninstall progress should begin. | +| [OnStartProgressUpdateReplace(bool)](#onstartprogressupdatereplace_bool) | Callback when update progress should begin. | +| [OnStartRepair(bool)](#onstartrepair_bool) | Callback when repair preparation should begin. | +| [OnStartUninstall(bool)](#onstartuninstall_bool) | Callback when uninstall preparation should begin. | +| [OnStartUpdateReplace(bool)](#onstartupdatereplace_bool) | Callback when update preparation should begin. | +| [OnUpdateAvailable(string, string)](#onupdateavailable_string_string) | Callback to determine if update should be executed. | +| [PromptCancel()](#promptcancel_nop) | | +| [Run()](#run_nop) | | +| [Stop()](#stop_nop) | | +| [UpdateCheckAllowed(string)](#updatecheckallowed_string) | Callback to determine whether update check can be attempted at updateLocation. | +## Properties +| Property | Description | +| ------ | ----------- | +| [WindowHandle](#windowhandle) | Obsolete. Use CreateWindow() to return the window handle. | + +`FireGiant.BundleApplicationFramework v6.0.1` +## CreateWindow() Method {#createwindow_nop} + +### Declaration +```cs +public BundleUIWindowContext CreateWindow() +``` +## InitializeSynchronizationContext() Method {#initializesynchronizationcontext_nop} +Obsolete. Use CreateWindow() to return the desired synchronization context. +### Declaration +```cs +public System.Threading.SynchronizationContext InitializeSynchronizationContext() +``` +### Return value +`System.Threading.SynchronizationContext` Synchronization context. +## OnCompleteCancel(bool restartRequired, bool fullUI) Method {#oncompletecancel_bool_bool} +Callback when the bundle application is canceled. +### Declaration +```cs +public void OnCompleteCancel( + bool restartRequired, + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| restartRequired | bool | Indicates whether restart is required. | +| fullUI | bool | Indicates whether UI should be displayed. | +## OnCompleteFailure(bool restartRequired, int errorCode, bool fullUI) Method {#oncompletefailure_bool_int_bool} +Callback when the bundle application fails. +### Declaration +```cs +public void OnCompleteFailure( + bool restartRequired, + int errorCode, + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| restartRequired | bool | Indicates whether restart is required. | +| errorCode | int | Error code for the failure. | +| fullUI | bool | Indicates whether UI should be displayed. | +## OnCompleteSuccess(bool restartRequired, bool fullUI) Method {#oncompletesuccess_bool_bool} +Callback when the bundle application succeeds. +### Declaration +```cs +public void OnCompleteSuccess( + bool restartRequired, + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| restartRequired | bool | Indicates whether restart is required. | +| fullUI | bool | Indicates whether UI should be displayed. | +## OnConditionFailure(BundleCondition condition, string message) Method {#onconditionfailure_bundlecondition_string} +Callback when a condition fails. +### Declaration +```cs +public bool OnConditionFailure( + BundleCondition condition, + string message +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| condition | BundleCondition | Failed condition. | +| message | string | Formatted message that can be displayed to the user. | +### Return value +`bool` False to fail the bundle application. +## OnDowngradeAllowed(string bundleId, bool perMachine) Method {#ondowngradeallowed_string_bool} +Callback when a newer bundle is detected. +### Declaration +```cs +public bool OnDowngradeAllowed( + string bundleId, + bool perMachine +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| bundleId | string | Id of the new bundle already installed. | +| perMachine | bool | Indicates wither the newer bundle is per-machine. | +### Return value +`bool` True if this bundle should downgrade the newer bundle. +### Remarks +Default value is false and will fail the installation. False is the recommended response. +## OnError(BundleErrorType type, string packageId, int code, string message, int uIHint, BundleResult recommendation) Method {#onerror_bundleerrortype_string_int_string_int_bundleresult} +Callback when an overall bundle appliation error occurs. +### Declaration +```cs +public BundleResult? OnError( + BundleErrorType type, + string packageId, + int code, + string message, + int uIHint, + BundleResult recommendation +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| type | BundleErrorType | Type of error. | +| packageId | string | Optional identifier of package involved in the error. | +| code | int | Error code. | +| message | string | Error message. | +| uIHint | int | Flags for use if displaying a message box. | +| recommendation | BundleResult | Result recommended by the bundle application for this class of error. | +## OnForceReboot(int status, bool fullUI) Method {#onforcereboot_int_bool} +Callback when the Burn engine forces a restart. +### Declaration +```cs +public bool OnForceReboot( + int status, + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| status | int | Error code before the force restart. | +| fullUI | bool | Indicates whether UI should be displayed. | +## OnInitializeHelp() Method {#oninitializehelp_nop} +Callback before help will be started. +### Declaration +```cs +public void OnInitializeHelp() +``` +## OnInitializeInstall(bool fullUI) Method {#oninitializeinstall_bool} +Callback before install will be started. +### Declaration +```cs +public void OnInitializeInstall( + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| fullUI | bool | Indicates whether UI should be displayed. | +## OnInitializeLayout() Method {#oninitializelayout_nop} +Callback before layout will be started. +### Declaration +```cs +public void OnInitializeLayout() +``` +## OnInitializeModify(bool fullUI) Method {#oninitializemodify_bool} +Callback before modify will be started. +### Declaration +```cs +public void OnInitializeModify( + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| fullUI | bool | Indicates whether UI should be displayed. | +## OnInitializeRepair(bool fullUI) Method {#oninitializerepair_bool} +Callback before repair will be started. +### Declaration +```cs +public void OnInitializeRepair( + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| fullUI | bool | Indicates whether UI should be displayed. | +## OnInitializeUninstall(bool fullUI) Method {#oninitializeuninstall_bool} +Callback before uninstall will be started. +### Declaration +```cs +public void OnInitializeUninstall( + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| fullUI | bool | Indicates whether UI should be displayed. | +## OnMsiMessage(BundlePackage package, BundleInstallMessage messageType, string message, int displayParameters, string[] data, bool fullUI) Method {#onmsimessage_bundlepackage_bundleinstallmessage_string_int_string[]_bool} +Callback when Windows Installer send an message. +### Declaration +```cs +public BundleResult? OnMsiMessage( + BundlePackage package, + BundleInstallMessage messageType, + string message, + int displayParameters, + string[] data, + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| package | BundlePackage | MSI package that sent the message. | +| messageType | BundleInstallMessage | Type of message from the Windows Installer. | +| message | string | Formatted message from the Windows Installer | +| displayParameters | int | Flags for use if displaying a message box. | +| data | string[] | Optional data specific to the message provided by the Windows Installer. | +| fullUI | bool | Indicates whether UI should be displayed. | +### Return value +`BundleResult?` Result of the message handling. +## OnPackageComplete(BundlePackage package, BundleProgressAction action, int errorCode) Method {#onpackagecomplete_bundlepackage_bundleprogressaction_int} +Callback when action on package is complete. +### Declaration +```cs +public void OnPackageComplete( + BundlePackage package, + BundleProgressAction action, + int errorCode +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| package | BundlePackage | Package completed. | +| action | BundleProgressAction | Action completed. | +| errorCode | int | Error encountered during action. 0 indicates success. | +## OnPackageProgress(BundlePackageProgress packageProgress) Method {#onpackageprogress_bundlepackageprogress} +Callback on overall package progress update. +### Declaration +```cs +public void OnPackageProgress( + BundlePackageProgress packageProgress +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| packageProgress | BundlePackageProgress | Overall progress. | +## OnProgress(BundleOverallProgress progress) Method {#onprogress_bundleoverallprogress} +Callback on overall progress update. +### Declaration +```cs +public void OnProgress( + BundleOverallProgress progress +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| progress | BundleOverallProgress | Overall progress. | +## OnResolveSource(string packageOrContainerId, string payloadId, string[] sources, BundleResolveSourceLocation locations) Method {#onresolvesource_string_string_string[]_bundleresolvesourcelocation} +Callback when payload or container cannot be located. +### Declaration +```cs +public bool OnResolveSource( + string packageOrContainerId, + string payloadId, + string[] sources, + BundleResolveSourceLocation locations +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| packageOrContainerId | string | Package or container identifier for payload that cannot be found. | +| payloadId | string | Payload that cannot be found. | +| sources | string[] | Paths where payload was not found. | +| locations | BundleResolveSourceLocation | New resource source locations to find the payload. | +### Return value +`bool` True to retry with new locations, otherwise false to fail the installation. +## OnSameVersionInstalled(string bundleId, string bundleTag, bool perMachine, WixToolset.Versioning.WixVersion version) Method {#onsameversioninstalled_string_string_bool_wixtoolsetversioningwixversion} +Callback when a bundle with the same is detected. +### Declaration +```cs +public BundleSameVersionAction OnSameVersionInstalled( + string bundleId, + string bundleTag, + bool perMachine, + WixToolset.Versioning.WixVersion version +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| bundleId | string | Id of the already installed bundle. | +| bundleTag | string | Tag of the already installed bundle. | +| perMachine | bool | Indicates wither the newer bundle is per-machine. | +| version | WixToolset.Versioning.WixVersion | Version of the already installed bundle. | +### Return value +`BundleSameVersionAction` Action to handle same version. +### Remarks +Default value is to fail the install. +## OnStartHelp(bool fullUI) Method {#onstarthelp_bool} +Callback when help should be displayed. +### Declaration +```cs +public bool OnStartHelp( + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| fullUI | bool | Indicates whether UI should be displayed. | +### Return value +`bool` True if the BundleUI handles the callback, otherwise bootstrapper application will exit. +## OnStartInstall(bool fullUI) Method {#onstartinstall_bool} +Callback when installation preparation should begin. +### Declaration +```cs +public bool OnStartInstall( + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| fullUI | bool | Indicates whether UI should be displayed. | +### Return value +`bool` True if the BundleUI handles the callback, otherwise bootstrapper application will continue on to progress phase. +## OnStartLayout(bool fullUI) Method {#onstartlayout_bool} +Callback when layout preparation should begin. +### Declaration +```cs +public bool OnStartLayout( + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| fullUI | bool | Indicates whether UI should be displayed. | +### Return value +`bool` True if the BundleUI handles the callback, otherwise bootstrapper application will continue on to progress phase. +## OnStartModify(bool fullUI) Method {#onstartmodify_bool} +Callback when modify preparation should begin. +### Declaration +```cs +public bool OnStartModify( + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| fullUI | bool | Indicates whether UI should be displayed. | +### Return value +`bool` True if the BundleUI handles the callback, otherwise bootstrapper application will continue on to progress phase. +## OnStartProgressInstall(bool showUI) Method {#onstartprogressinstall_bool} +Callback when installation progress should begin. +### Declaration +```cs +public void OnStartProgressInstall( + bool showUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| showUI | bool | Indicates whether UI should be displayed. | +## OnStartProgressLayout(bool showUI) Method {#onstartprogresslayout_bool} +Callback when layout progress should begin. +### Declaration +```cs +public void OnStartProgressLayout( + bool showUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| showUI | bool | Indicates whether UI should be displayed. | +## OnStartProgressModify(bool showUI) Method {#onstartprogressmodify_bool} +Callback when modify progress should begin. +### Declaration +```cs +public void OnStartProgressModify( + bool showUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| showUI | bool | Indicates whether UI should be displayed. | +## OnStartProgressRepair(bool showUI) Method {#onstartprogressrepair_bool} +Callback when repair progress should begin. +### Declaration +```cs +public void OnStartProgressRepair( + bool showUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| showUI | bool | Indicates whether UI should be displayed. | +## OnStartProgressUninstall(bool showUI) Method {#onstartprogressuninstall_bool} +Callback when uninstall progress should begin. +### Declaration +```cs +public void OnStartProgressUninstall( + bool showUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| showUI | bool | Indicates whether UI should be displayed. | +## OnStartProgressUpdateReplace(bool showUI) Method {#onstartprogressupdatereplace_bool} +Callback when update progress should begin. +### Declaration +```cs +public void OnStartProgressUpdateReplace( + bool showUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| showUI | bool | Indicates whether UI should be displayed. | +## OnStartRepair(bool fullUI) Method {#onstartrepair_bool} +Callback when repair preparation should begin. +### Declaration +```cs +public bool OnStartRepair( + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| fullUI | bool | Indicates whether UI should be displayed. | +### Return value +`bool` True if the BundleUI handles the callback, otherwise bootstrapper application will continue on to progress phase. +## OnStartUninstall(bool fullUI) Method {#onstartuninstall_bool} +Callback when uninstall preparation should begin. +### Declaration +```cs +public bool OnStartUninstall( + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| fullUI | bool | Indicates whether UI should be displayed. | +### Return value +`bool` True if the BundleUI handles the callback, otherwise bootstrapper application will continue on to progress phase. +## OnStartUpdateReplace(bool fullUI) Method {#onstartupdatereplace_bool} +Callback when update preparation should begin. +### Declaration +```cs +public bool OnStartUpdateReplace( + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| fullUI | bool | Indicates whether UI should be displayed. | +### Return value +`bool` True if the BundleUI handles the callback, otherwise bootstrapper application will continue on to progress phase. +## OnUpdateAvailable(string updateLocation, string title) Method {#onupdateavailable_string_string} +Callback to determine if update should be executed. +### Declaration +```cs +public bool OnUpdateAvailable( + string updateLocation, + string title +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| updateLocation | string | Location where update was found. | +| title | string | Title of found update. | +### Return value +`bool` True if update should be executed. +## PromptCancel() Method {#promptcancel_nop} + +### Declaration +```cs +public bool PromptCancel() +``` +## Run() Method {#run_nop} + +### Declaration +```cs +public void Run() +``` +## Stop() Method {#stop_nop} + +### Declaration +```cs +public void Stop() +``` +## UpdateCheckAllowed(string updateLocation) Method {#updatecheckallowed_string} +Callback to determine whether update check can be attempted at updateLocation. +### Declaration +```cs +public bool UpdateCheckAllowed( + string updateLocation +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| updateLocation | string | Location to check for updates. | +### Return value +`bool` True to allow check for update. +## WindowHandle Property {#windowhandle} +Obsolete. Use CreateWindow() to return the window handle. +### Declaration +```cs +public object WindowHandle { get; set; } +``` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleuiwindowcontext.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleuiwindowcontext.md new file mode 100644 index 0000000..4157a4c --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/bundleuiwindowcontext.md @@ -0,0 +1,40 @@ +--- +title: BundleUIWindowContext Class +pagefind: false +--- +Context returned when the BundleUI window is created. +## Properties +| Property | Description | +| ------ | ----------- | +| [SynchronizationContext](#synchronizationcontext) | An optional synchronization context (a new DispatcherSynchronizationContext() for WPF or + WindowsFormsSynchronizationContext.Current after a WinForms form is created) can be used + and all IBundleUI methods will be called from the UI thread. This makes updating the UI + trivial but care must be taken to not do to much work during the callbacks as UI thread + is blocked. + + Alternatively, using null means IBundleUI methods will be called from a background thread. + In this case, care must be taken to update the UI from the UI thread. | +| [WindowHandle](#windowhandle) | A window handle is required even when no UI is displayed to ensure all Windows messages are + processed during then bundle process. | + +`FireGiant.BundleApplicationFramework v6.0.1` +## SynchronizationContext Property {#synchronizationcontext} +An optional synchronization context (a new DispatcherSynchronizationContext() for WPF or + WindowsFormsSynchronizationContext.Current after a WinForms form is created) can be used + and all IBundleUI methods will be called from the UI thread. This makes updating the UI + trivial but care must be taken to not do to much work during the callbacks as UI thread + is blocked. + + Alternatively, using null means IBundleUI methods will be called from a background thread. + In this case, care must be taken to update the UI from the UI thread. +### Declaration +```cs +public System.Threading.SynchronizationContext SynchronizationContext { get; set; } +``` +## WindowHandle Property {#windowhandle} +A window handle is required even when no UI is displayed to ensure all Windows messages are + processed during then bundle process. +### Declaration +```cs +public object WindowHandle { get; set; } +``` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/firegiantbundleapplication.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/firegiantbundleapplication.md new file mode 100644 index 0000000..cc6e739 --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/firegiantbundleapplication.md @@ -0,0 +1,32 @@ +--- +title: FireGiantBundleApplication Class +pagefind: false +--- +Connects to the Burn engine and runs the bundle. +## Methods +| Method | Description | +| ------ | ----------- | +| [Run()](#run_nop) | Runs the bundle application. | +| [Run(System.Reflection.Assembly)](#run_systemreflectionassembly) | Runs the bundle application. | + +`FireGiant.BundleApplicationFramework v6.0.1` +## Run() Method {#run_nop} +Runs the bundle application. +### Declaration +```cs +public void Run() +``` +### Remarks +The calling assembly will be used as the UI assembly. +## Run(System.Reflection.Assembly uiAssembly) Method {#run_systemreflectionassembly} +Runs the bundle application. +### Declaration +```cs +public void Run( + System.Reflection.Assembly uiAssembly +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| uiAssembly | System.Reflection.Assembly | Assembly containing the IBundleUIFactory created when run. | diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/ibundleapplication.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/ibundleapplication.md new file mode 100644 index 0000000..9de3c3c --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/ibundleapplication.md @@ -0,0 +1,441 @@ +--- +title: IBundleApplication Interface +pagefind: false +--- +Bundle application provided to support the BundleUI. +## Methods +| Method | Description | +| ------ | ----------- | +| [Cancel()](#cancel_nop) | Sets the bundle application to be canceled. | +| [CheckCanceled()](#checkcanceled_nop) | Check to see if the bundle application has been canceled. | +| [CheckFailed()](#checkfailed_nop) | Check to see if the bundle application is in an error state. | +| [CloseSplashScreen()](#closesplashscreen_nop) | Directs the Burn engine to dismiss the splash screen. | +| [DetectAgain()](#detectagain_nop) | Requests the Burn engine re-execute detection after UIReady() was already called. | +| [DisallowRestart()](#disallowrestart_nop) | Directs the Burn engine to best-effort prevent restarts. | +| [Error(int)](#error_int) | Sets the bundle error state. | +| [EvaluateCondition(string)](#evaluatecondition_string) | Request the Burn engine evalute a condition. | +| [FormatString(string)](#formatstring_string) | Request the Burn engine to resolve a string with variable references ("[VARNAME]"). | +| [GetBundleLogPath()](#getbundlelogpath_nop) | Get the path to the bundle log file. | +| [GetCommandLineArguments()](#getcommandlinearguments_nop) | Returns the bundle command-line arguments. | +| [GetManifest()](#getmanifest_nop) | Returns the bundle manifest. | +| [GetNumericVariable(string)](#getnumericvariable_string) | Gets a numeric variable. | +| [GetPackage(int)](#getpackage_int) | Gets a package by index. | +| [GetPackage(string)](#getpackage_string) | Gets a package by identity. | +| [GetStringVariable(string)](#getstringvariable_string) | Gets a string variable. | +| [GetVersionVariable(string)](#getversionvariable_string) | Gets a version variable. | +| [Go()](#go_nop) | Directs the bundle application to plan with the default PlanAction. | +| [GoWithAction(BundleAction)](#gowithaction_bundleaction) | Directs the bundle applicaiton to plan a specific action. | +| [LogError(int, string, string[])](#logerror_int_string_string[]) | Log an error message to the bundle's log file. | +| [LogMessage(string, string[])](#logmessage_string_string[]) | Log a message to the bundle's log file. | +| [ParseCommandLine()](#parsecommandline_nop) | Parse the bundle command-line for the pattern VARNAME=VALUE to assign variables. | +| [PromptCancel(string, string)](#promptcancel_string_string) | Prompts the user to cancel with a specific cancel message. | +| [SendCancelPrompt()](#sendcancelprompt_nop) | Requests the bundle application to prompt for cancel. | +| [SendEmbeddedError(int, string, int)](#sendembeddederror_int_string_int) | Send message to parent bundle when embedded. | +| [SetPlanFeatureRequestState(string, string, BundleFeatureState)](#setplanfeaturerequeststate_string_string_bundlefeaturestate) | Sets the requested state for a package's feature. Must be called before calling Go() or GoWithAction(). | +| [SetPlanPackageRequestState(string, BundleRequestState)](#setplanpackagerequeststate_string_bundlerequeststate) | Sets the requested state for a package. Must be called before calling Go() or GoWithAction(). | +| [SetVariable(string, string)](#setvariable_string_string) | Sets a string variable. | +| [SetVariable(string, long)](#setvariable_string_long) | Sets a numeric variable. | +| [SetVersionVariable(string, string)](#setversionvariable_string_string) | Sets a version variable. | +| [UIReady()](#uiready_nop) | Obsolete. This method is unused. | +## Properties +| Property | Description | +| ------ | ----------- | +| [AllowRestart](#allowrestart) | Indicates whether restarts are allowed. | +| [PackageCount](#packagecount) | Count of packages in the bundle. | +| [Packages](#packages) | Enumerates the packages in the bundle. | +| [PlanAction](#planaction) | The default plan action set via the bundle command-line. | +| [RestartRequired](#restartrequired) | Indicates whether a restart was required. | +| [ResumeType](#resumetype) | Resume type of the bundle. | +| [RollingBack](#rollingback) | Indicates if the bundle application is rolling back. | + +`FireGiant.BundleApplicationFramework v6.0.1` +## Cancel() Method {#cancel_nop} +Sets the bundle application to be canceled. +### Declaration +```cs +public void Cancel() +``` +## CheckCanceled() Method {#checkcanceled_nop} +Check to see if the bundle application has been canceled. +### Declaration +```cs +public bool CheckCanceled() +``` +### Return value +`bool` True if the bundle application was canceled. +## CheckFailed() Method {#checkfailed_nop} +Check to see if the bundle application is in an error state. +### Declaration +```cs +public bool CheckFailed() +``` +### Return value +`bool` True if the bundle application is in an error state. +## CloseSplashScreen() Method {#closesplashscreen_nop} +Directs the Burn engine to dismiss the splash screen. +### Declaration +```cs +public void CloseSplashScreen() +``` +## DetectAgain() Method {#detectagain_nop} +Requests the Burn engine re-execute detection after UIReady() was already called. +### Declaration +```cs +public void DetectAgain() +``` +## DisallowRestart() Method {#disallowrestart_nop} +Directs the Burn engine to best-effort prevent restarts. +### Declaration +```cs +public void DisallowRestart() +``` +## Error(int errorCode) Method {#error_int} +Sets the bundle error state. +### Declaration +```cs +public bool Error( + int errorCode +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| errorCode | int | Error code to set. | +### Return value +`bool` True if the bundle is in an error state. +## EvaluateCondition(string condition) Method {#evaluatecondition_string} +Request the Burn engine evalute a condition. +### Declaration +```cs +public bool EvaluateCondition( + string condition +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| condition | string | Condition to evaluate. | +### Return value +`bool` Evaluation of condition. +## FormatString(string format) Method {#formatstring_string} +Request the Burn engine to resolve a string with variable references ("[VARNAME]"). +### Declaration +```cs +public string FormatString( + string format +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| format | string | String with variable references to resolve. | +### Return value +`string` Formatted string. +## GetBundleLogPath() Method {#getbundlelogpath_nop} +Get the path to the bundle log file. +### Declaration +```cs +public string GetBundleLogPath() +``` +## GetCommandLineArguments() Method {#getcommandlinearguments_nop} +Returns the bundle command-line arguments. +### Declaration +```cs +public string[] GetCommandLineArguments() +``` +### Return value +`string[]` Array of command-line arguments. +## GetManifest() Method {#getmanifest_nop} +Returns the bundle manifest. +### Declaration +```cs +public System.Xml.Linq.XDocument GetManifest() +``` +### Return value +`System.Xml.Linq.XDocument` XML document containing the bundle manifest. +## GetNumericVariable(string name) Method {#getnumericvariable_string} +Gets a numeric variable. +### Declaration +```cs +public long? GetNumericVariable( + string name +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| name | string | Name of variable to retrieve. | +### Return value +`long?` Long or null if the variable is not defined. +## GetPackage(int index) Method {#getpackage_int} +Gets a package by index. +### Declaration +```cs +public BundlePackage GetPackage( + int index +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| index | int | Index of package to retrieve. | +### Return value +`BundlePackage` Bundle package. +## GetPackage(string id) Method {#getpackage_string} +Gets a package by identity. +### Declaration +```cs +public BundlePackage GetPackage( + string id +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| id | string | Identity of package to retrieve. | +### Return value +`BundlePackage` Bundle package. +## GetStringVariable(string name) Method {#getstringvariable_string} +Gets a string variable. +### Declaration +```cs +public string GetStringVariable( + string name +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| name | string | Name of variable to retrieve. | +### Return value +`string` String or null if the variable is not defined. +## GetVersionVariable(string name) Method {#getversionvariable_string} +Gets a version variable. +### Declaration +```cs +public string GetVersionVariable( + string name +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| name | string | Name of variable to retrieve. | +### Return value +`string` Version or null if the variable is not defined. +## Go() Method {#go_nop} +Directs the bundle application to plan with the default PlanAction. +### Declaration +```cs +public void Go() +``` +## GoWithAction(BundleAction action) Method {#gowithaction_bundleaction} +Directs the bundle applicaiton to plan a specific action. +### Declaration +```cs +public void GoWithAction( + BundleAction action +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| action | BundleAction | | +## LogError(int errorCode, string format, string[] args) Method {#logerror_int_string_string[]} +Log an error message to the bundle's log file. +### Declaration +```cs +public void LogError( + int errorCode, + string format, + string[] args +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| errorCode | int | Error code for the message | +| format | string | Format string for the message. | +| args | string[] | Data to provide to the format. | +## LogMessage(string format, string[] args) Method {#logmessage_string_string[]} +Log a message to the bundle's log file. +### Declaration +```cs +public void LogMessage( + string format, + string[] args +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| format | string | Format string for the message. | +| args | string[] | Data to provide to the format. | +## ParseCommandLine() Method {#parsecommandline_nop} +Parse the bundle command-line for the pattern VARNAME=VALUE to assign variables. +### Declaration +```cs +public void ParseCommandLine() +``` +## PromptCancel(string message, string caption) Method {#promptcancel_string_string} +Prompts the user to cancel with a specific cancel message. +### Declaration +```cs +public bool PromptCancel( + string message, + string caption +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| message | string | Message to display. | +| caption | string | Caption of the cancel prompt. | +### Return value +`bool` True if the user chose to cancel. +## SendCancelPrompt() Method {#sendcancelprompt_nop} +Requests the bundle application to prompt for cancel. +### Declaration +```cs +public bool SendCancelPrompt() +``` +### Return value +`bool` True if the user chose to cancel. +## SendEmbeddedError(int code, string message, int uiHint) Method {#sendembeddederror_int_string_int} +Send message to parent bundle when embedded. +### Declaration +```cs +public int SendEmbeddedError( + int code, + string message, + int uiHint +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| code | int | Status code to send. | +| message | string | Message to send. | +| uiHint | int | Flags to send. | +### Return value +`int` Result from parent bundle. +## SetPlanFeatureRequestState(string packageId, string featureId, BundleFeatureState requestState) Method {#setplanfeaturerequeststate_string_string_bundlefeaturestate} +Sets the requested state for a package's feature. Must be called before calling Go() or GoWithAction(). +### Declaration +```cs +public void SetPlanFeatureRequestState( + string packageId, + string featureId, + BundleFeatureState requestState +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| packageId | string | Identity of the package containing the feature. | +| featureId | string | Identity of the feature to set plan state. | +| requestState | BundleFeatureState | Requested state to assign to feature. | +## SetPlanPackageRequestState(string packageId, BundleRequestState requestState) Method {#setplanpackagerequeststate_string_bundlerequeststate} +Sets the requested state for a package. Must be called before calling Go() or GoWithAction(). +### Declaration +```cs +public void SetPlanPackageRequestState( + string packageId, + BundleRequestState requestState +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| packageId | string | Identity of the package to set plan state. | +| requestState | BundleRequestState | Requested state to assign to package. | +## SetVariable(string name, string value) Method {#setvariable_string_string} +Sets a string variable. +### Declaration +```cs +public void SetVariable( + string name, + string value +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| name | string | Name of variable to set. | +| value | string | Value of variable to set. | +## SetVariable(string name, long value) Method {#setvariable_string_long} +Sets a numeric variable. +### Declaration +```cs +public void SetVariable( + string name, + long value +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| name | string | Name of variable to set. | +| value | long | Value of variable to set. | +## SetVersionVariable(string name, string value) Method {#setversionvariable_string_string} +Sets a version variable. +### Declaration +```cs +public void SetVersionVariable( + string name, + string value +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| name | string | Name of variable to set. | +| value | string | Value of variable to set. | +## UIReady() Method {#uiready_nop} +Obsolete. This method is unused. +### Declaration +```cs +public void UIReady() +``` +## AllowRestart Property {#allowrestart} +Indicates whether restarts are allowed. +### Declaration +```cs +public bool AllowRestart { get; set; } +``` +## PackageCount Property {#packagecount} +Count of packages in the bundle. +### Declaration +```cs +public int PackageCount { get; set; } +``` +## Packages Property {#packages} +Enumerates the packages in the bundle. +### Declaration +```cs +public IEnumerable{BundlePackage} Packages { get; set; } +``` +## PlanAction Property {#planaction} +The default plan action set via the bundle command-line. +### Declaration +```cs +public BundleAction PlanAction { get; set; } +``` +## RestartRequired Property {#restartrequired} +Indicates whether a restart was required. +### Declaration +```cs +public bool RestartRequired { get; set; } +``` +## ResumeType Property {#resumetype} +Resume type of the bundle. +### Declaration +```cs +public BundleResumeType ResumeType { get; set; } +``` +## RollingBack Property {#rollingback} +Indicates if the bundle application is rolling back. +### Declaration +```cs +public bool RollingBack { get; set; } +``` diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/ibundleui.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/ibundleui.md new file mode 100644 index 0000000..d3f4bf8 --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/ibundleui.md @@ -0,0 +1,552 @@ +--- +title: IBundleUI Interface +pagefind: false +--- +BundleUI interface. +## Methods +| Method | Description | +| ------ | ----------- | +| [CreateWindow()](#createwindow_nop) | Create (but do not show) the BundleUI window to return the window's handle to the bootstrapper application. | +| [OnCompleteCancel(bool, bool)](#oncompletecancel_bool_bool) | Callback when the bundle application is canceled. | +| [OnCompleteFailure(bool, int, bool)](#oncompletefailure_bool_int_bool) | Callback when the bundle application fails. | +| [OnCompleteSuccess(bool, bool)](#oncompletesuccess_bool_bool) | Callback when the bundle application succeeds. | +| [OnConditionFailure(BundleCondition, string)](#onconditionfailure_bundlecondition_string) | Callback when a condition fails. | +| [OnDowngradeAllowed(string, bool)](#ondowngradeallowed_string_bool) | Callback when a newer bundle is detected. | +| [OnError(BundleErrorType, string, int, string, int, BundleResult)](#onerror_bundleerrortype_string_int_string_int_bundleresult) | Callback when an overall bundle appliation error occurs. | +| [OnForceReboot(int, bool)](#onforcereboot_int_bool) | Callback when the Burn engine forces a restart. | +| [OnInitializeHelp()](#oninitializehelp_nop) | Callback before help will be started. | +| [OnInitializeInstall(bool)](#oninitializeinstall_bool) | Callback before install will be started. | +| [OnInitializeLayout()](#oninitializelayout_nop) | Callback before layout will be started. | +| [OnInitializeModify(bool)](#oninitializemodify_bool) | Callback before modify will be started. | +| [OnInitializeRepair(bool)](#oninitializerepair_bool) | Callback before repair will be started. | +| [OnInitializeUninstall(bool)](#oninitializeuninstall_bool) | Callback before uninstall will be started. | +| [OnMsiMessage(BundlePackage, BundleInstallMessage, string, int, string[], bool)](#onmsimessage_bundlepackage_bundleinstallmessage_string_int_string[]_bool) | Callback when Windows Installer send an message. | +| [OnPackageComplete(BundlePackage, BundleProgressAction, int)](#onpackagecomplete_bundlepackage_bundleprogressaction_int) | Callback when action on package is complete. | +| [OnPackageProgress(BundlePackageProgress)](#onpackageprogress_bundlepackageprogress) | Callback on overall package progress update. | +| [OnProgress(BundleOverallProgress)](#onprogress_bundleoverallprogress) | Callback on overall progress update. | +| [OnResolveSource(string, string, string[], BundleResolveSourceLocation)](#onresolvesource_string_string_string[]_bundleresolvesourcelocation) | Callback when payload or container cannot be located. | +| [OnSameVersionInstalled(string, string, bool, WixToolset.Versioning.WixVersion)](#onsameversioninstalled_string_string_bool_wixtoolsetversioningwixversion) | Callback when a bundle with the same version is detected. | +| [OnStartHelp(bool)](#onstarthelp_bool) | Callback when help should be displayed. | +| [OnStartInstall(bool)](#onstartinstall_bool) | Callback when layout preparation should begin. | +| [OnStartLayout(bool)](#onstartlayout_bool) | Callback when installation preparation should begin. | +| [OnStartModify(bool)](#onstartmodify_bool) | Callback when modify preparation should begin. | +| [OnStartProgressInstall(bool)](#onstartprogressinstall_bool) | Callback when layout progress should begin. | +| [OnStartProgressLayout(bool)](#onstartprogresslayout_bool) | Callback when installation progress should begin. | +| [OnStartProgressModify(bool)](#onstartprogressmodify_bool) | Callback when modify progress should begin. | +| [OnStartProgressRepair(bool)](#onstartprogressrepair_bool) | Callback when repair progress should begin. | +| [OnStartProgressUninstall(bool)](#onstartprogressuninstall_bool) | Callback when uninstall progress should begin. | +| [OnStartProgressUpdateReplace(bool)](#onstartprogressupdatereplace_bool) | Callback when update progress should begin. | +| [OnStartRepair(bool)](#onstartrepair_bool) | Callback when repair preparation should begin. | +| [OnStartUninstall(bool)](#onstartuninstall_bool) | Callback when uninstall preparation should begin. | +| [OnStartUpdateReplace(bool)](#onstartupdatereplace_bool) | Callback when update preparation should begin. | +| [OnUpdateAvailable(string, string)](#onupdateavailable_string_string) | Callback to determine if update should be executed. | +| [PromptCancel()](#promptcancel_nop) | Prompt the user to cancel the bundle. | +| [Run()](#run_nop) | Runs the BundleUI until Stop(). | +| [Stop()](#stop_nop) | Called to stop the running of the BundleUI. | +| [UpdateCheckAllowed(string)](#updatecheckallowed_string) | Callback to determine whether update check can be attempted at updateLocation. | + +`FireGiant.BundleApplicationFramework v6.0.1` +## CreateWindow() Method {#createwindow_nop} +Create (but do not show) the BundleUI window to return the window's handle to the bootstrapper application. +### Declaration +```cs +public BundleUIWindowContext CreateWindow() +``` +### Return value +`BundleUIWindowContext` BundleUI window context with the windows handle and optional synchronization context. +## OnCompleteCancel(bool restartRequired, bool fullUI) Method {#oncompletecancel_bool_bool} +Callback when the bundle application is canceled. +### Declaration +```cs +public void OnCompleteCancel( + bool restartRequired, + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| restartRequired | bool | Indicates whether restart is required. | +| fullUI | bool | Indicates whether UI should be displayed. | +## OnCompleteFailure(bool restartRequired, int errorCode, bool fullUI) Method {#oncompletefailure_bool_int_bool} +Callback when the bundle application fails. +### Declaration +```cs +public void OnCompleteFailure( + bool restartRequired, + int errorCode, + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| restartRequired | bool | Indicates whether restart is required. | +| errorCode | int | Error code for the failure. | +| fullUI | bool | Indicates whether UI should be displayed. | +## OnCompleteSuccess(bool restartRequired, bool fullUI) Method {#oncompletesuccess_bool_bool} +Callback when the bundle application succeeds. +### Declaration +```cs +public void OnCompleteSuccess( + bool restartRequired, + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| restartRequired | bool | Indicates whether restart is required. | +| fullUI | bool | Indicates whether UI should be displayed. | +## OnConditionFailure(BundleCondition condition, string message) Method {#onconditionfailure_bundlecondition_string} +Callback when a condition fails. +### Declaration +```cs +public bool OnConditionFailure( + BundleCondition condition, + string message +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| condition | BundleCondition | Failed condition. | +| message | string | Formatted message that can be displayed to the user. | +### Return value +`bool` False to fail the bundle application. +## OnDowngradeAllowed(string bundleId, bool perMachine) Method {#ondowngradeallowed_string_bool} +Callback when a newer bundle is detected. +### Declaration +```cs +public bool OnDowngradeAllowed( + string bundleId, + bool perMachine +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| bundleId | string | Id of the new bundle already installed. | +| perMachine | bool | Indicates wither the newer bundle is per-machine. | +### Return value +`bool` True if this bundle should downgrade the newer bundle. +## OnError(BundleErrorType type, string packageId, int code, string message, int uIHint, BundleResult recommendation) Method {#onerror_bundleerrortype_string_int_string_int_bundleresult} +Callback when an overall bundle appliation error occurs. +### Declaration +```cs +public BundleResult? OnError( + BundleErrorType type, + string packageId, + int code, + string message, + int uIHint, + BundleResult recommendation +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| type | BundleErrorType | Type of error. | +| packageId | string | Optional identifier of package involved in the error. | +| code | int | Error code. | +| message | string | Error message. | +| uIHint | int | Flags for use if displaying a message box. | +| recommendation | BundleResult | Result recommended by the bundle application for this class of error. | +## OnForceReboot(int status, bool fullUI) Method {#onforcereboot_int_bool} +Callback when the Burn engine forces a restart. +### Declaration +```cs +public bool OnForceReboot( + int status, + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| status | int | Error code before the force restart. | +| fullUI | bool | Indicates whether UI should be displayed. | +## OnInitializeHelp() Method {#oninitializehelp_nop} +Callback before help will be started. +### Declaration +```cs +public void OnInitializeHelp() +``` +## OnInitializeInstall(bool fullUI) Method {#oninitializeinstall_bool} +Callback before install will be started. +### Declaration +```cs +public void OnInitializeInstall( + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| fullUI | bool | Indicates whether UI should be displayed. | +## OnInitializeLayout() Method {#oninitializelayout_nop} +Callback before layout will be started. +### Declaration +```cs +public void OnInitializeLayout() +``` +## OnInitializeModify(bool fullUI) Method {#oninitializemodify_bool} +Callback before modify will be started. +### Declaration +```cs +public void OnInitializeModify( + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| fullUI | bool | Indicates whether UI should be displayed. | +## OnInitializeRepair(bool fullUI) Method {#oninitializerepair_bool} +Callback before repair will be started. +### Declaration +```cs +public void OnInitializeRepair( + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| fullUI | bool | Indicates whether UI should be displayed. | +## OnInitializeUninstall(bool fullUI) Method {#oninitializeuninstall_bool} +Callback before uninstall will be started. +### Declaration +```cs +public void OnInitializeUninstall( + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| fullUI | bool | Indicates whether UI should be displayed. | +## OnMsiMessage(BundlePackage package, BundleInstallMessage messageType, string message, int displayParameters, string[] data, bool fullUI) Method {#onmsimessage_bundlepackage_bundleinstallmessage_string_int_string[]_bool} +Callback when Windows Installer send an message. +### Declaration +```cs +public BundleResult? OnMsiMessage( + BundlePackage package, + BundleInstallMessage messageType, + string message, + int displayParameters, + string[] data, + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| package | BundlePackage | MSI package that sent the message. | +| messageType | BundleInstallMessage | Type of message from the Windows Installer. | +| message | string | Formatted message from the Windows Installer | +| displayParameters | int | Flags for use if displaying a message box. | +| data | string[] | Optional data specific to the message provided by the Windows Installer. | +| fullUI | bool | Indicates whether UI should be displayed. | +### Return value +`BundleResult?` Result of the message handling. +## OnPackageComplete(BundlePackage package, BundleProgressAction action, int errorCode) Method {#onpackagecomplete_bundlepackage_bundleprogressaction_int} +Callback when action on package is complete. +### Declaration +```cs +public void OnPackageComplete( + BundlePackage package, + BundleProgressAction action, + int errorCode +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| package | BundlePackage | Package completed. | +| action | BundleProgressAction | Action completed. | +| errorCode | int | Error encountered during action. 0 indicates success. | +## OnPackageProgress(BundlePackageProgress packageProgress) Method {#onpackageprogress_bundlepackageprogress} +Callback on overall package progress update. +### Declaration +```cs +public void OnPackageProgress( + BundlePackageProgress packageProgress +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| packageProgress | BundlePackageProgress | Overall progress. | +## OnProgress(BundleOverallProgress progress) Method {#onprogress_bundleoverallprogress} +Callback on overall progress update. +### Declaration +```cs +public void OnProgress( + BundleOverallProgress progress +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| progress | BundleOverallProgress | Overall progress. | +## OnResolveSource(string packageOrContainerId, string payloadId, string[] sources, BundleResolveSourceLocation locations) Method {#onresolvesource_string_string_string[]_bundleresolvesourcelocation} +Callback when payload or container cannot be located. +### Declaration +```cs +public bool OnResolveSource( + string packageOrContainerId, + string payloadId, + string[] sources, + BundleResolveSourceLocation locations +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| packageOrContainerId | string | Package or container identifier for payload that cannot be found. | +| payloadId | string | Payload that cannot be found. | +| sources | string[] | Possible sources where payload was not found. | +| locations | BundleResolveSourceLocation | New resource source locations to find the payload. | +### Return value +`bool` True to retry with new locations, otherwise false to fail the installation. +## OnSameVersionInstalled(string bundleId, string bundleTag, bool perMachine, WixToolset.Versioning.WixVersion version) Method {#onsameversioninstalled_string_string_bool_wixtoolsetversioningwixversion} +Callback when a bundle with the same version is detected. +### Declaration +```cs +public BundleSameVersionAction OnSameVersionInstalled( + string bundleId, + string bundleTag, + bool perMachine, + WixToolset.Versioning.WixVersion version +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| bundleId | string | Id of the already installed bundle. | +| bundleTag | string | Tag of the already installed bundle. | +| perMachine | bool | Indicates wither the newer bundle is per-machine. | +| version | WixToolset.Versioning.WixVersion | Version of the already installed bundle. | +### Return value +`BundleSameVersionAction` Action to handle same version. +## OnStartHelp(bool fullUI) Method {#onstarthelp_bool} +Callback when help should be displayed. +### Declaration +```cs +public bool OnStartHelp( + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| fullUI | bool | Indicates whether UI should be displayed. | +### Return value +`bool` True if the BundleUI handles the callback, otherwise bootstrapper application will exit. +## OnStartInstall(bool fullUI) Method {#onstartinstall_bool} +Callback when layout preparation should begin. +### Declaration +```cs +public bool OnStartInstall( + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| fullUI | bool | Indicates whether UI should be displayed. | +### Return value +`bool` True if the BundleUI handles the callback, otherwise bootstrapper application will continue on to progress phase. +## OnStartLayout(bool fullUI) Method {#onstartlayout_bool} +Callback when installation preparation should begin. +### Declaration +```cs +public bool OnStartLayout( + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| fullUI | bool | Indicates whether UI should be displayed. | +### Return value +`bool` True if the BundleUI handles the callback, otherwise bootstrapper application will continue on to progress phase. +## OnStartModify(bool fullUI) Method {#onstartmodify_bool} +Callback when modify preparation should begin. +### Declaration +```cs +public bool OnStartModify( + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| fullUI | bool | Indicates whether UI should be displayed. | +### Return value +`bool` True if the BundleUI handles the callback, otherwise bootstrapper application will continue on to progress phase. +## OnStartProgressInstall(bool showUI) Method {#onstartprogressinstall_bool} +Callback when layout progress should begin. +### Declaration +```cs +public void OnStartProgressInstall( + bool showUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| showUI | bool | Indicates whether UI should be displayed. | +## OnStartProgressLayout(bool showUI) Method {#onstartprogresslayout_bool} +Callback when installation progress should begin. +### Declaration +```cs +public void OnStartProgressLayout( + bool showUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| showUI | bool | Indicates whether UI should be displayed. | +## OnStartProgressModify(bool showUI) Method {#onstartprogressmodify_bool} +Callback when modify progress should begin. +### Declaration +```cs +public void OnStartProgressModify( + bool showUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| showUI | bool | Indicates whether UI should be displayed. | +## OnStartProgressRepair(bool showUI) Method {#onstartprogressrepair_bool} +Callback when repair progress should begin. +### Declaration +```cs +public void OnStartProgressRepair( + bool showUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| showUI | bool | Indicates whether UI should be displayed. | +## OnStartProgressUninstall(bool showUI) Method {#onstartprogressuninstall_bool} +Callback when uninstall progress should begin. +### Declaration +```cs +public void OnStartProgressUninstall( + bool showUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| showUI | bool | Indicates whether UI should be displayed. | +## OnStartProgressUpdateReplace(bool showUI) Method {#onstartprogressupdatereplace_bool} +Callback when update progress should begin. +### Declaration +```cs +public void OnStartProgressUpdateReplace( + bool showUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| showUI | bool | Indicates whether UI should be displayed. | +## OnStartRepair(bool fullUI) Method {#onstartrepair_bool} +Callback when repair preparation should begin. +### Declaration +```cs +public bool OnStartRepair( + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| fullUI | bool | Indicates whether UI should be displayed. | +### Return value +`bool` True if the BundleUI handles the callback, otherwise bootstrapper application will continue on to progress phase. +## OnStartUninstall(bool fullUI) Method {#onstartuninstall_bool} +Callback when uninstall preparation should begin. +### Declaration +```cs +public bool OnStartUninstall( + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| fullUI | bool | Indicates whether UI should be displayed. | +### Return value +`bool` True if the BundleUI handles the callback, otherwise bootstrapper application will continue on to progress phase. +## OnStartUpdateReplace(bool fullUI) Method {#onstartupdatereplace_bool} +Callback when update preparation should begin. +### Declaration +```cs +public bool OnStartUpdateReplace( + bool fullUI +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| fullUI | bool | Indicates whether UI should be displayed. | +### Return value +`bool` True if the BundleUI handles the callback, otherwise bootstrapper application will continue on to progress phase. +## OnUpdateAvailable(string updateLocation, string title) Method {#onupdateavailable_string_string} +Callback to determine if update should be executed. +### Declaration +```cs +public bool OnUpdateAvailable( + string updateLocation, + string title +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| updateLocation | string | Location where update was found. | +| title | string | Title of found update. | +### Return value +`bool` True if update should be executed. +## PromptCancel() Method {#promptcancel_nop} +Prompt the user to cancel the bundle. +### Declaration +```cs +public bool PromptCancel() +``` +### Return value +`bool` True if the user allowed the cancel. +## Run() Method {#run_nop} +Runs the BundleUI until Stop(). +### Declaration +```cs +public void Run() +``` +## Stop() Method {#stop_nop} +Called to stop the running of the BundleUI. +### Declaration +```cs +public void Stop() +``` +## UpdateCheckAllowed(string updateLocation) Method {#updatecheckallowed_string} +Callback to determine whether update check can be attempted at updateLocation. +### Declaration +```cs +public bool UpdateCheckAllowed( + string updateLocation +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| updateLocation | string | Location to check for updates. | +### Return value +`bool` True to allow check for update. diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/ibundleuifactory.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/ibundleuifactory.md new file mode 100644 index 0000000..49bdb8f --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/ibundleuifactory.md @@ -0,0 +1,25 @@ +--- +title: IBundleUIFactory Interface +pagefind: false +--- +BundleUI factory interface. +## Methods +| Method | Description | +| ------ | ----------- | +| [CreateBundleUI(IBundleApplication)](#createbundleui_ibundleapplication) | Called by the framework to request a BundleUI. | + +`FireGiant.BundleApplicationFramework v6.0.1` +## CreateBundleUI(IBundleApplication bundleApplication) Method {#createbundleui_ibundleapplication} +Called by the framework to request a BundleUI. +### Declaration +```cs +public IBundleUI CreateBundleUI( + IBundleApplication bundleApplication +) +``` +### Parameters +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| bundleApplication | IBundleApplication | Bundle application provided by the framework. | +### Return value +`IBundleUI` BundleUI or null if this factory does not support the parameters provided by the bundleApplication. diff --git a/src/content/docs/firegiant/api/firegiantbundleapplicationframework/index.md b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/index.md new file mode 100644 index 0000000..cc961e4 --- /dev/null +++ b/src/content/docs/firegiant/api/firegiantbundleapplicationframework/index.md @@ -0,0 +1,43 @@ +--- +title: FireGiant.BundleApplicationFramework namespace +pagefind: false +--- +## Classes +| Class | Description | +| -------- | ----------- | +| [BundleCondition](bundlecondition/) | Condition evaluated during bundle initialization. | +| [BundleFeature](bundlefeature/) | Details about a feature that is part of a Bundle's package. | +| [BundleOverallProgress](bundleoverallprogress/) | Overall progress during apply. | +| [BundlePackage](bundlepackage/) | Details about a package that is part of the Bundle's chain. | +| [BundlePackageProgress](bundlepackageprogress/) | Progress of a package. | +| [BundleRelatedPackage](bundlerelatedpackage/) | Details about a related package to a Bundle's package that was detected. | +| [BundleResolveSourceLocation](bundleresolvesourcelocation/) | Updates payload source locations. | +| [BundleUIBase](bundleuibase/) | Base BundleUI that provides default implementation for IBundleUI. | +| [BundleUIWindowContext](bundleuiwindowcontext/) | Context returned when the BundleUI window is created. | +| [FireGiantBundleApplication](firegiantbundleapplication/) | Connects to the Burn engine and runs the bundle. | +## Interfaces +| Interface | Description | +| -------- | ----------- | +| [IBundleApplication](ibundleapplication/) | Bundle application provided to support the BundleUI. | +| [IBundleUI](ibundleui/) | BundleUI interface. | +| [IBundleUIFactory](ibundleuifactory/) | BundleUI factory interface. | +## Enumerations +| Enumeration | Description | +| -------- | ----------- | +| [BundleAction](bundleaction/) | Bundle actions. | +| [BundleActionState](bundleactionstate/) | Action state for a package or bundle. | +| [BundleApplyPhase](bundleapplyphase/) | Apply phases of a bundle. | +| [BundleCacheOperation](bundlecacheoperation/) | Bundle cache operations. | +| [BundleErrorType](bundleerrortype/) | Types of error. | +| [BundleFeatureState](bundlefeaturestate/) | Feature state. | +| [BundleInstallMessage](bundleinstallmessage/) | Types of messages sent during apply. | +| [BundlePackageCacheType](bundlepackagecachetype/) | Cache type for package. | +| [BundlePackageState](bundlepackagestate/) | Package state. | +| [BundlePackageType](bundlepackagetype/) | Package type. | +| [BundleProgressAction](bundleprogressaction/) | Progress for a bundle | +| [BundleRelatedOperation](bundlerelatedoperation/) | Relation types between packages. | +| [BundleRelationType](bundlerelationtype/) | Relation types between bundles. | +| [BundleRequestState](bundlerequeststate/) | Request state. | +| [BundleResult](bundleresult/) | Bundle result. | +| [BundleResumeType](bundleresumetype/) | Resume type. | +| [BundleSameVersionAction](bundlesameversionaction/) | Action to take when bundles have same version. | From 826a3a490df9a32728b34a8388f9821f15ac542a Mon Sep 17 00:00:00 2001 From: FireGiant Docs Date: Sat, 8 Nov 2025 00:33:13 -0800 Subject: [PATCH 4/6] Add FGBA documentation --- astro.config.mjs | 1 + .../heatwave/build-tools/fgba/bundleui.md | 262 ++++++++++++++++++ .../heatwave/build-tools/fgba/debugging.md | 29 ++ .../docs/heatwave/build-tools/fgba/factory.md | 23 ++ .../docs/heatwave/build-tools/fgba/index.md | 67 +++++ 5 files changed, 382 insertions(+) create mode 100644 src/content/docs/heatwave/build-tools/fgba/bundleui.md create mode 100644 src/content/docs/heatwave/build-tools/fgba/debugging.md create mode 100644 src/content/docs/heatwave/build-tools/fgba/factory.md create mode 100644 src/content/docs/heatwave/build-tools/fgba/index.md diff --git a/astro.config.mjs b/astro.config.mjs index 6a8a982..317e487 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -53,6 +53,7 @@ export default defineConfig({ 'heatwave/build-tools', 'heatwave/build-tools/firegiant-licensing', { label: 'Advanced Harvesting', collapsed: true, autogenerate: { directory: '/heatwave/build-tools/harvesting' } }, + { label: 'Bundle Application Framework', collapsed: true, autogenerate: { directory: '/heatwave/build-tools/fgba' } }, { label: 'MSIX', collapsed: true, autogenerate: { directory: '/heatwave/build-tools/msix' } }, 'heatwave/build-tools/driver', 'heatwave/build-tools/protected-services', diff --git a/src/content/docs/heatwave/build-tools/fgba/bundleui.md b/src/content/docs/heatwave/build-tools/fgba/bundleui.md new file mode 100644 index 0000000..1a3cc5e --- /dev/null +++ b/src/content/docs/heatwave/build-tools/fgba/bundleui.md @@ -0,0 +1,262 @@ +--- +title: Building a BundleUI +sidebar: + order: 2 +--- + +The Bundle UI is the central object in the FireGiant Bundle Application Framework that you create to manage your UI. It inherits from [`FireGiant.BundleApplicationFramework.BundleUIBase`](/firegiant/api/firegiantbundleapplicationframework/bundleuibase/) and must implement three methods: CreateWindow, Run, and Stop. +* `CreateWindow()` is called to get the Bundle UI's window handle and appropriate threading context. A window handle is _always_ required because some Burn operations must pump Windows messages. The window may not be displayed to the user (and should be created hidden) but Burn requires it. +* `Run()` is called for the Bundle UI to enter its main event loop. When the Bundle UI exits this function, the bundle application exits. +* `Stop()` is called when the Bundle UI should exit. This method sends the quit message to the Bundle UI's main event loop. + +## Minimal Bundle UI + +Here is the minimal WPF-based Bundle UI. It stores a reference to the [`FireGiant.BundleApplicationFramework.IBundleApplication`](/firegiant/api/firegiantbundleapplicationframework/ibundleapplication/) to communicate with Burn and its WPF-based `MainWindow` starts out hidden. + +```cs title=ExampleWpfBundleUI.cs +using FireGiant.BundleApplicationFramework; + +public class ExampleWpfBundleUI : BundleUIBase +{ + private readonly IBundleApplication _bundleApplication; + private MainWindow _window; + + public ExampleWpfBundleUI(IBundleApplication bundleApplication) + { + _bundleApplication = bundleApplication; + } + + public override BundleUIWindowContext CreateWindow() + { + _window = new MainWindow(); + + return new BundleUIWindowContext + { + WindowHandle = new WindowInteropHelper(_window).EnsureHandle(), + SynchronizationContext = new DispatcherSynchronizationContext(), + }; + } + + public override void Run() + { + Dispatcher.Run(); + } + + public override void Stop() + { + Dispatcher.CurrentDispatcher.InvokeShutdown(); + } +``` + +:::note[IBundleApplication] +Technically speaking, this minimal Bundle UI does not need the `IBundleApplication` reference. But as we'll see, every realistic Bundle UI will use the `_bundleApplication`. The `IBundleApplication` provides methods to read/write variables, log messages, cancel progress, and much more. +::: + +With the most minimal Bundle UI created, let's look at the callbacks that are available to customize your Bundle UI's behavior. + +## Bundle UI callbacks + +Without overriding any other Bundle UI methods, your Bundle UI supports all bundle actions (Install, Modify, Repair, Uninstall, etc) and all phases (Detect, Plan, Apply) without displaying any UI or customization. Since the goal of implementing a Bundle UI is to customize the bundle experience and/or display some UI, let's explore the available customization callbacks. + +### Bundle action handling + +A Bundle UI has three callbacks for each bundle action: Initialize, Start and Start Progress. +* `OnInititialize{Action}()` is called before any action related operations have occured. It is not very common to use this callback because very little is known at this time. In Burn terms, the `Initialize` callbacks happen before the Detect phase is executed. +* `OnStart{Action}(bool fullUI)` is called after the bundle has completed the Detect phase so the current state of the machine is known. The Bundle UI should set any configuration at this time. It can display UI to interact with the user if `fullUI` is true. Otherwise, it should do any configuration silently then call `IBundleApplication.Go()`. In Burn terms, the `Start` callbacks happen after the Detect phase completes and `Go()` starts the Plan phase. +* `OnStartProgress{Action}(bool showUI)` is called after the bundle has planned its work and is ready to start. The BundleUI should display UI (such as a progress bar) if `showUI` is true. In Burn terms, the `StartProgress` callbacks, happen at the beginning of the Apply phase. + +The following is a example of a Bundle UI that shows UI for install and uninstall. + +```cs title=ExampleWpfBundleUI.cs +public class ExampleWpfBundleUI : BundleUIBase +{ + private readonly IBundleApplication _bundleApplication; + private MainWindow _window; + + ... + + public override bool OnStartInstall(bool fullUI) + { + if (fullUI) + { + _window.Model = new ExampleInstallViewModel(_bundleApplication); + _window.Show(); + + // Let FGBA know that we're handling this callback because the + // window and viewmodel will call _bundleApplication.Go() when + // the user presses the "Install" button. + return true; + } + + // Let the default handle the non-UI case. + return base.OnStartInstall(fullUI); + } + + public override bool OnStartUninstall(bool fullUI) + { + if (fullUI) + { + _window.Model = new ExampleUninstallViewModel(_bundleApplication); + _window.Show(); + + // Let FGBA know that we're handling this callback because the + // window and viewmodel will call _bundleApplication.Go() when + // the user presses the "Ok" button to start the uninstall. + return true; + } + + // Let the default handle the non-UI case. + return base.OnStartUninstall(fullUI); + } + + public override void OnStartProgressInstall(bool showUI) + { + if (showUI) + { + _window.Model = new ExampleProgressViewModel(_bundleApplication, "Installing..."); + _window.Show(); + } + } + + public override void OnStartProgressUninstall(bool showUI) + { + if (showUI) + { + _window.Model = new ExampleProgressViewModel(_bundleApplication, "Uninstalling..."); + _window.Show(); + } + } + + // Other callbacks. + + // Initialization, these are rarely needed. + // OnInitializeHelp() + // OnInitializeLayout() + // OnInitializeInstall() + // OnInitializeModify() + // OnInitializeRepair() + // OnInitializeUninstall() + + // Show a custom UI for any of these actions. + // OnStartHelp() + // OnStartLayout() + // OnStartInstall() - seen above + // OnStartModify() + // OnStartRepair() + // OnStartUninstall() - seen above + + // Show progress page and handle progress updates. + // OnStartProgressLayout + // OnStartProgressInstall - seen above + // OnStartProgressModify + // OnStartProgressRepair + // OnStartProgressUninstall - seen above +``` + +:::note[Callback code duplication] +You may find there is some duplication between callbacks for a particular action. Feel free to refactor as you see fit. +::: + +### Progress callbacks + +During the Apply phase of the bundle, there are several callbacks that can report what is happening in Burn. These callbacks can be useful to show progress and potentially prompt the user for input. + +```cs title=ExampleWpfBundleUI.cs + public virtual void OnProgress(BundleOverallProgress progress) + { + if (_window.Model is ExampleProgressViewModel vm) + { + vm.ProgressBarPercentage = progress.OverallPercentage; + } + + base.OnProgress(progress); + } + + public virtual void OnPackageProgress(BundlePackageProgress packageProgress) + { + if (_window.Model is ExampleProgressViewModel vm) + { + vm.CurrentPackageName = packageProgress.Package.DisplayName; + } + + base.OnPackageProgress(packageProgress); + } + + public virtual void OnPackageComplete( + BundlePackage package, + BundleProgressAction action, + int errorCode) + { + if (_window.Model is ExampleProgressViewModel vm) + { + vm.CurrentPackageName = null; + } + + base.OnPackageComplete(package, action, errorCode); + } + + + // Other useful callbacks. + // OnMsiMessage + // OnResolveSource +``` + +### Completion callbacks + +The FireGiant Bundle Application Framework calls the Bundle UI when the bundle action has completed with success, error or was canceled by the user. You can use the following callbacks to show the appropriate UI. + +```cs title=ExampleWpfBundleUI.cs + public override void OnCompleteCancel(bool restartRequired, bool fullUI) + { + if (fullUI) + { + // ExampleDoneViewModel will need to call this.Stop() when the user clicks "Ok" or + // closes the dialog. + _window.Model = new ExampleDoneViewModel(this, _bundleApplication, restartRequired, + "Canceled..."); + _window.Show(); + } + else + { + base.OnCompleteCancel(restartRequired, fullUI); + } + } + + public override void OnCompleteFailure(bool restartRequired, int errorCode, bool fullUI) + { + if (fullUI) + { + // ExampleDoneViewModel will need to call this.Stop() when the user clicks "Ok" or + // closes the dialog. + _window.Model = new ExampleDoneViewModel(this, _bundleApplication, restartRequired, + "Failed :(", errorCode); + _window.Show(); + } + else + { + base.OnCompleteCancel(restartRequired, fullUI); + } + } + + public override void OnCompleteSuccess(bool restartRequired, bool fullUI) + { + if (fullUI) + { + // ExampleDoneViewModel will need to call this.Stop() when the user clicks "Ok" or + // closes the dialog. + _window.Model = new ExampleDoneViewModel(this, _bundleApplication, restartRequired, + "Success!!!"); + _window.Show(); + } + else + { + base.OnCompleteCancel(restartRequired, fullUI); + } + } +``` + +:::tip[Show UI] +Notice in the example that the `_window` will be shown in `fullUI`. This is important becuase it is possible the bundle will complete without calling any of the OnStart callbacks. This usually happens when there is an error very early in the initialization of the bundle. +::: + +Feel free to explore the other callbacks that a Bundle UI can override in the [`BundleUIBase`](/firegiant/api/firegiantbundleapplicationframework/bundleuibase/). diff --git a/src/content/docs/heatwave/build-tools/fgba/debugging.md b/src/content/docs/heatwave/build-tools/fgba/debugging.md new file mode 100644 index 0000000..86f11ac --- /dev/null +++ b/src/content/docs/heatwave/build-tools/fgba/debugging.md @@ -0,0 +1,29 @@ +--- +title: Debugging a Bundle UI +sidebar: + order: 3 +--- + +Bundle UIs are challenging to debug. They are an executable carried as a payload in a bundle that is extracted then launched from Burn. That means every change to your Bundle UI requires rebuilding the Bundle UI .csproj then your bundle .wixproj. Additionally, the process you need to debug is not the produced bundle .exe but a process started by that process. Fortunately, there is a mechanism to make the Bundle UI process pause at startup and display a message box so you can attach a debugger. + +## One-time debug configuration + +1. Set a **system** environment variable named `WixDebugBootstrapperApplication` to the file name of the Bundle UI executable. + + For example, if your Bundle UI is named `mybundleui.csproj` then the output is probably `mybundleui.exe` (unless you customize the .csproj). Set a system environment variable `WixDebugBootstrapperApplication` to `mybundleui.exe`. + +2. Restart Visual Studio to pick up the new environment variable. + + +## Debugging + +1. Make your Bundle UI changes +2. Build the Bundle UI .csproj with those changes +3. Build the bundle .wixproj +4. Start the output bundle .exe +5. A message box will appear with the process id for the Bundle UI .exe +6. Attach a debugger to the Bundle UI process +7. Set a breakpoint in the Bundle UI code to debug +8. Continue in the debugger to hit the break point + + diff --git a/src/content/docs/heatwave/build-tools/fgba/factory.md b/src/content/docs/heatwave/build-tools/fgba/factory.md new file mode 100644 index 0000000..81a73a3 --- /dev/null +++ b/src/content/docs/heatwave/build-tools/fgba/factory.md @@ -0,0 +1,23 @@ +--- +title: Implementing a BundleUIFactory +sidebar: + order: 1 +--- + +In addition to communicating with Burn, [`FireGiantBundleApplication.Run()`](/firegiant/api/firegiantbundleapplicationframework/firegiantbundleapplication/) finds an implementation of [`IBundleUIFactory`](/firegiant/api/firegiantbundleapplicationframework/ibundleui/) and calls that to create your Bundle UI object. The following is an implementation that should be sufficient for 99.999% of Bundle UIs. This factory pattern exists for those 0.001% of cases that need to do something special. + +## Standard Bundle UI factory + +```cs title=ExampleBundleUIFactory.cs +using FireGiant.BundleApplicationFramework; + +public class ExampleBundleUIFactory : IBundleUIFactory +{ + public IBundleUI CreateBundleUI(IBundleApplication bundleApplication) + { + return new ExampleWpfBundleUI(bundleApplication); + } +} +``` + +Now that we can create Bundle UI using our factory, let's look at how to implement the Bundle UI itself. diff --git a/src/content/docs/heatwave/build-tools/fgba/index.md b/src/content/docs/heatwave/build-tools/fgba/index.md new file mode 100644 index 0000000..2f8f9f4 --- /dev/null +++ b/src/content/docs/heatwave/build-tools/fgba/index.md @@ -0,0 +1,67 @@ +--- +title: FireGiant Bundle Application Framework +sidebar: + order: 0 +--- + +FireGiant Bundle Application Framework (FGBA) makes it easy to create custom bundle experiences, better known as "Bootstrapper Applications". Bootstrapper Applications are responsible for driving the bundle process and must handle many different scenarios. FGBA handles the complex edge cases for you so your bundle always installs and (often more importantly) uninstalls. It does this by abstracting away many of the low level details of Bootstrapper Applications allowing you to focus on the "Bundle UI". + +:::caution[Licensed feature] +Like the other features in HeatWave Build Tools, a license file is required to use FireGiant Bundle Application. See the [FireGiant licensing documentation for more information](../firegiant-licensing/). +::: + +Before digging into everything that FGBA provides, let's do a quick review of the key features of bundles from the Bootstrapper and Bundle Application point of view. + +Part of the build process for a [``](/wix/schema/wxs/bundle/) is to embed the [``](/wix/schema/wxs/bootstrapperapplication/) and all of its child [``](/wix/schema/wxs/payload/) files into the bundle engine provided by WiX, called "Burn", to create your final bundle executable. When your customer runs your bundle, Burn unpacks your Bootstrapper Application and all of its payloads then launches your Bootstrapper Application executable. Since Bootstrapper Applications are executables that run in a separate process from Burn, they must connect back to Burn communicate about the bundle process. + +FGBA makes this easy with one line of code: + +```cs title=Program.cs {7} +using FireGiant.BundleApplicationFramework; + +public static class Program +{ + public static int Main(string[] args) + { + FireGiantBundleApplication.Run(); + + return 0; + } +} +``` + +:::note[Exit code] +Always `return 0` from your Bootstrapper Application's entry point. That signals to Burn that your Bootstrapper Application executed properly. It is NOT how you communicate the final exit code for the overall process. We'll see how to communicate that later. +::: + +Before we dig deeper into how you define your Bundle Application, let's complete our introduction to a few more key features of bundles. + +## Bundle actions + +Users can request six different actions from a bundle: Install, Modify, Repair, Uninstall, Layout, and Help. +* Install is the most well known action that typically has users select what options to install, possibly provide some configuration, then actually install the appropriate packages in the bundle. +* Modify is the same but occurs when the bundle is already installed. +* Repair is selected by users to fix a broken application. +* Uninstall is pretty self-explanatory; it is used to remove the bundle from the computer. +* Layout copies the bundle and all external payloads into a folder that can then be installed without network access. +* Help is the outlier, as it displays help UI and nothing else. + +## Bundle phases + +Bundle actions (except Help) go through three phases: Detect, Plan, and Apply. +* During the Detect phase, the Burn engine scans the user's machine and reports the current status of the bundle and all of its chained packages. +* During the Plan phase, the Burn engine takes a high-level directive (such as "install", "repair", or "uninstall") and determines what operations need to be done for each package. +* During the Apply phase, the operations from the Plan phase are executed. The Apply phase has two sub-phases Cache and Execute. + * During Cache, packages are downloaded, copied, and/or extracted to a secure package store. + * During Execute, the packages are installed, repaired, or uninstalled as per the plan. + +## Bundle UI modes + +Finally, bundles must handle the three UI modes: Full, Passive and Quiet. +* In Full UI mode, the user expects to be presented with the interactive user interface. Historically, this UI has been a wizard-like experience. +* In Passive UI mode, the user expects to be provided enough UI to know that the process is underway but with no other interaction. Commonly this is a simple UI that starts immediately, presents a progress bar then completes without any additional prompts. +* The Quiet UI mode is like Passive in that it starts immediately and does not prompt the user at all, but also shows no UI at all. + +The six operations, three phases and three UI modes create many different permutations Bootstrapper Applications must handle. There are almost 100 events Burn can fire to transmit all the information about the active operation, phase and UI mode. Again, FGBA simplifies your UI development by capturing all Burn events to track the bundle state in an easy to use API and provide default implementations for the events that require responses. The result is your Bundle UI only overrides the callbacks it wants to customize. + +Let's look at how to instantiate your Bundle UI next. From 71052563d927123ad578a651cd8d4493f1b5a2ea Mon Sep 17 00:00:00 2001 From: FireGiant Docs Date: Sat, 8 Nov 2025 00:33:36 -0800 Subject: [PATCH 5/6] Fix title bar links --- astro.config.mjs | 2 +- src/components/starlight/SiteTitle.astro | 11 +++++------ 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/astro.config.mjs b/astro.config.mjs index 317e487..d8cfb67 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -17,7 +17,7 @@ export default defineConfig({ filter: (page) => !page.startsWith('https://docs.firegiant.com/wix3/') }), starlight({ - title: 'Docs', + title: 'FireGiant Docs', logo: { dark: './src/assets/firegiant-logo-black.svg', light: './src/assets/firegiant-logo-standard.svg', diff --git a/src/components/starlight/SiteTitle.astro b/src/components/starlight/SiteTitle.astro index d8be866..855a6f4 100644 --- a/src/components/starlight/SiteTitle.astro +++ b/src/components/starlight/SiteTitle.astro @@ -2,16 +2,15 @@ import logoDark from '@assets/firegiant-logo-black.svg?raw'; import logoLight from '@assets/firegiant-logo-standard.svg?raw'; import docs from '@assets/docs-logo.svg?raw'; -import { type Props } from '@astrojs/starlight/props'; -const { siteTitle, siteTitleHref } = Astro.props; -const www = 'https://www.firegiant.com/'; +const wwwHref = 'https://www.firegiant.com/'; +const docsHref = 'https://docs.firegiant.com/'; --- -