From 21c430b0d2a46bae326655209fefde13ae17b051 Mon Sep 17 00:00:00 2001
From: Rob Mensching <rob@firegiant.com>
Date: Tue, 23 Feb 2021 07:45:42 -0800
Subject: Rename FullyResolved to SymbolsFinalized and TryAddSymbolXxx to
TryProcessSymbol
Plus fix up more documentation
---
.../BaseBurnBackendExtension.cs | 63 ++++++++--------------
.../BaseWindowsInstallerBackendBinderExtension.cs | 10 ++--
.../IBurnBackendExtension.cs | 45 ++++++++--------
.../IWindowsInstallerBackendBinderExtension.cs | 22 ++++----
4 files changed, 61 insertions(+), 79 deletions(-)
(limited to 'src')
diff --git a/src/WixToolset.Extensibility/BaseBurnBackendExtension.cs b/src/WixToolset.Extensibility/BaseBurnBackendExtension.cs
index 0575d725..488f882a 100644
--- a/src/WixToolset.Extensibility/BaseBurnBackendExtension.cs
+++ b/src/WixToolset.Extensibility/BaseBurnBackendExtension.cs
@@ -2,6 +2,7 @@
namespace WixToolset.Extensibility
{
+ using System;
using System.Collections.Generic;
using System.Linq;
using WixToolset.Data;
@@ -35,24 +36,8 @@ namespace WixToolset.Extensibility
protected virtual IEnumerable<IntermediateSymbolDefinition> SymbolDefinitions => Enumerable.Empty<IntermediateSymbolDefinition>();
/// <summary>
- /// Called after all output changes occur and right before the output is bound into its final format.
+ /// See <see cref="IBurnBackendExtension.PreBackendBind(IBindContext)"/>
/// </summary>
- public virtual void BundleFinalize()
- {
- }
-
- /// <summary>
- /// Called after output is bound into its final format.
- /// </summary>
- /// <param name="result"></param>
- public virtual void PostBackendBind(IBindResult result)
- {
- }
-
- /// <summary>
- /// Called before binding occurs.
- /// </summary>
- /// <param name="context"></param>
public virtual void PreBackendBind(IBindContext context)
{
this.Context = context;
@@ -61,44 +46,32 @@ namespace WixToolset.Extensibility
}
/// <summary>
- ///
+ /// See <see cref="IBurnBackendExtension.ResolveRelatedFile(String, String, String, SourceLineNumber)"/>
/// </summary>
- /// <param name="source"></param>
- /// <param name="relatedSource"></param>
- /// <param name="type"></param>
- /// <param name="sourceLineNumbers"></param>
- /// <param name="bindStage"></param>
- /// <returns></returns>
- public virtual IResolveFileResult ResolveRelatedFile(string source, string relatedSource, string type, SourceLineNumber sourceLineNumbers, BindStage bindStage)
+ public virtual IResolveFileResult ResolveRelatedFile(string source, string relatedSource, string type, SourceLineNumber sourceLineNumbers)
{
return null;
}
/// <summary>
- ///
+ /// See <see cref="IBurnBackendExtension.SymbolsFinalized(IntermediateSection)"/>
+ /// </summary>
+ public virtual void SymbolsFinalized(IntermediateSection section)
+ {
+ }
+
+ /// <summary>
+ /// See <see cref="IBurnBackendExtension.ResolveUrl(String, String, String, String, String)"/>
/// </summary>
- /// <param name="url"></param>
- /// <param name="fallbackUrl"></param>
- /// <param name="packageId"></param>
- /// <param name="payloadId"></param>
- /// <param name="fileName"></param>
- /// <returns></returns>
public virtual string ResolveUrl(string url, string fallbackUrl, string packageId, string payloadId, string fileName)
{
return null;
}
/// <summary>
- /// Called for each extension symbol that hasn't been handled yet.
- /// Use IBurnBackendHelper to add data to the appropriate data manifest.
+ /// See <see cref="IBurnBackendExtension.TryProcessSymbol(IntermediateSection, IntermediateSymbol)"/>
/// </summary>
- /// <param name="section">The linked section.</param>
- /// <param name="symbol">The current symbol.</param>
- /// <returns>
- /// True if the extension handled the symbol, false otherwise.
- /// The Burn backend will warn on all unhandled symbols.
- /// </returns>
- public virtual bool TryAddSymbolToDataManifest(IntermediateSection section, IntermediateSymbol symbol)
+ public virtual bool TryProcessSymbol(IntermediateSection section, IntermediateSymbol symbol)
{
if (this.SymbolDefinitions.Any(t => t == symbol.Definition) &&
symbol.Definition.HasTag(BurnConstants.BootstrapperApplicationDataSymbolDefinitionTag))
@@ -109,5 +82,13 @@ namespace WixToolset.Extensibility
return false;
}
+
+ /// <summary>
+ /// See <see cref="IBurnBackendExtension.PostBackendBind(IBindResult)"/>
+ /// </summary>
+ /// <param name="result"></param>
+ public virtual void PostBackendBind(IBindResult result)
+ {
+ }
}
}
diff --git a/src/WixToolset.Extensibility/BaseWindowsInstallerBackendBinderExtension.cs b/src/WixToolset.Extensibility/BaseWindowsInstallerBackendBinderExtension.cs
index c0086aed..47777fae 100644
--- a/src/WixToolset.Extensibility/BaseWindowsInstallerBackendBinderExtension.cs
+++ b/src/WixToolset.Extensibility/BaseWindowsInstallerBackendBinderExtension.cs
@@ -53,9 +53,9 @@ namespace WixToolset.Extensibility
}
/// <summary>
- /// See <see cref="IWindowsInstallerBackendBinderExtension.FullyResolved(IntermediateSection)"/>
+ /// See <see cref="IWindowsInstallerBackendBinderExtension.SymbolsFinalized(IntermediateSection)"/>
/// </summary>
- public virtual void FullyResolved(IntermediateSection section)
+ public virtual void SymbolsFinalized(IntermediateSection section)
{
}
@@ -70,13 +70,13 @@ namespace WixToolset.Extensibility
public virtual string ResolveMedia(MediaSymbol mediaRow, string mediaLayoutDirectory, string layoutDirectory) => null;
/// <summary>
- /// See <see cref="IWindowsInstallerBackendBinderExtension.PreBackendBind(IBindContext)"/>
+ /// See <see cref="IWindowsInstallerBackendBinderExtension.TryProcessSymbol(IntermediateSection, IntermediateSymbol, WindowsInstallerData, TableDefinitionCollection)"/>
/// </summary>
- public virtual bool TryAddSymbolToOutput(IntermediateSection section, IntermediateSymbol symbol, WindowsInstallerData output, TableDefinitionCollection tableDefinitions)
+ public virtual bool TryProcessSymbol(IntermediateSection section, IntermediateSymbol symbol, WindowsInstallerData data, TableDefinitionCollection tableDefinitions)
{
if (this.TableDefinitions.Any(t => t.SymbolDefinition == symbol.Definition))
{
- return this.BackendHelper.TryAddSymbolToOutputMatchingTableDefinitions(section, symbol, output, tableDefinitions);
+ return this.BackendHelper.TryAddSymbolToOutputMatchingTableDefinitions(section, symbol, data, tableDefinitions);
}
return false;
diff --git a/src/WixToolset.Extensibility/IBurnBackendExtension.cs b/src/WixToolset.Extensibility/IBurnBackendExtension.cs
index 769c2457..07f5cd1b 100644
--- a/src/WixToolset.Extensibility/IBurnBackendExtension.cs
+++ b/src/WixToolset.Extensibility/IBurnBackendExtension.cs
@@ -16,30 +16,36 @@ namespace WixToolset.Extensibility
void PreBackendBind(IBindContext context);
/// <summary>
- ///
+ /// Called to find a file related to another source in the authoring. For example, most often used
+ /// to find cabinets and uncompressed files for an MSI package.
/// </summary>
- /// <param name="source"></param>
- /// <param name="relatedSource"></param>
- /// <param name="type"></param>
- /// <param name="sourceLineNumbers"></param>
- /// <param name="bindStage"></param>
- /// <returns></returns>
- IResolveFileResult ResolveRelatedFile(string source, string relatedSource, string type, SourceLineNumber sourceLineNumbers, BindStage bindStage);
+ /// <param name="source">Path to the source package.</param>
+ /// <param name="relatedSource">Expected path to the related file.</param>
+ /// <param name="type">Type of related file, such as "File" or "Cabinet"</param>
+ /// <param name="sourceLineNumbers">Source line number of source package.</param>
+ /// <returns><c>IResolveFileResult</c> if the related file was found, or null for default handling.</returns>
+ IResolveFileResult ResolveRelatedFile(string source, string relatedSource, string type, SourceLineNumber sourceLineNumbers);
/// <summary>
- ///
+ /// Called right before the output is bound into its final format.
/// </summary>
- /// <param name="url"></param>
- /// <param name="fallbackUrl"></param>
- /// <param name="packageId"></param>
- /// <param name="payloadId"></param>
- /// <param name="fileName"></param>
- /// <returns></returns>
+ /// <param name="section">The finalized intermediate section.</param>
+ void SymbolsFinalized(IntermediateSection section);
+
+ /// <summary>
+ /// Called to customize the DownloadUrl provided in source cde.
+ /// </summary>
+ /// <param name="url">The value from the source code. May not actually be a URL.</param>
+ /// <param name="fallbackUrl">The default URL if the extension does not return a value.</param>
+ /// <param name="packageId">Identifier of the package.</param>
+ /// <param name="payloadId">Identifier of the payload.</param>
+ /// <param name="fileName">Filename of the payload.</param>
+ /// <returns>Url to override, or null to use default value.</returns>
string ResolveUrl(string url, string fallbackUrl, string packageId, string payloadId, string fileName);
/// <summary>
/// Called for each extension symbol that hasn't been handled yet.
- /// Use IBurnBackendHelper to add data to the appropriate data manifest.
+ /// Use IBurnBackendHelper to add data.
/// </summary>
/// <param name="section">The linked section.</param>
/// <param name="symbol">The current symbol.</param>
@@ -47,12 +53,7 @@ namespace WixToolset.Extensibility
/// True if the extension handled the symbol, false otherwise.
/// The Burn backend will warn on all unhandled symbols.
/// </returns>
- bool TryAddSymbolToDataManifest(IntermediateSection section, IntermediateSymbol symbol);
-
- /// <summary>
- /// Called after all output changes occur and right before the output is bound into its final format.
- /// </summary>
- void BundleFinalize();
+ bool TryProcessSymbol(IntermediateSection section, IntermediateSymbol symbol);
/// <summary>
/// Called after output is bound into its final format.
diff --git a/src/WixToolset.Extensibility/IWindowsInstallerBackendBinderExtension.cs b/src/WixToolset.Extensibility/IWindowsInstallerBackendBinderExtension.cs
index b913dadc..12a38b9a 100644
--- a/src/WixToolset.Extensibility/IWindowsInstallerBackendBinderExtension.cs
+++ b/src/WixToolset.Extensibility/IWindowsInstallerBackendBinderExtension.cs
@@ -24,10 +24,10 @@ namespace WixToolset.Extensibility
void PreBackendBind(IBindContext context);
/// <summary>
- ///
+ /// Extension can process the intermediate before the Windows Installer data is created.
/// </summary>
- /// <param name="section">The resolved intermedate section.</param>
- void FullyResolved(IntermediateSection section);
+ /// <param name="section">The finalized intermediate section.</param>
+ void SymbolsFinalized(IntermediateSection section);
/// <summary>
/// Finds an existing cabinet that contains the provided files.
@@ -41,20 +41,20 @@ namespace WixToolset.Extensibility
/// Override layout location for a media.
/// </summary>
/// <param name="mediaSymbol">Media symbol.</param>
- /// <param name="mediaLayoutDirectory">Default media layout directory.</param>
- /// <param name="layoutDirectory">Default layout directory.</param>
+ /// <param name="mediaLayoutDirectory">Default media specific layout directory.</param>
+ /// <param name="layoutDirectory">Default overall layout directory.</param>
/// <returns>Layout location or null to use the default processing.</returns>
string ResolveMedia(MediaSymbol mediaSymbol, string mediaLayoutDirectory, string layoutDirectory);
/// <summary>
- ///
+ /// Called for each extension symbol that hasn't been handled yet.
/// </summary>
- /// <param name="section"></param>
- /// <param name="symbol"></param>
- /// <param name="output">Windows Installer data </param>
+ /// <param name="section">The linked section.</param>
+ /// <param name="symbol">The current symbol.</param>
+ /// <param name="data">Windows Installer data </param>
/// <param name="tableDefinitions">Collection of table definitions available for the output.</param>
- /// <returns>True if the symbol was added to the output, or false if not.</returns>
- bool TryAddSymbolToOutput(IntermediateSection section, IntermediateSymbol symbol, WindowsInstallerData output, TableDefinitionCollection tableDefinitions);
+ /// <returns>True if the symbol was handled, or false if not.</returns>
+ bool TryProcessSymbol(IntermediateSection section, IntermediateSymbol symbol, WindowsInstallerData data, TableDefinitionCollection tableDefinitions);
/// <summary>
/// Called after all output changes occur and right before the output is bound into its final format.
--
cgit v1.2.3-55-g6feb