Implement IWindowsInstallerDecompileExtensions

Update Util extension to validate extension model and fix some small
issues in MSI decompiling.

Fixes 6367

7 files changed, 313 insertions, 70 deletions

diff --git a/src/api/wix/WixToolset.Extensibility/BaseWindowsInstallerBackendBinderExtension.cs b/src/api/wix/WixToolset.Extensibility/BaseWindowsInstallerBackendBinderExtension.cs
index e48579d7..a54f05fc 100644
--- a/src/api/wix/WixToolset.Extensibility/BaseWindowsInstallerBackendBinderExtension.cs
+++ b/src/api/wix/WixToolset.Extensibility/BaseWindowsInstallerBackendBinderExtension.cs
@@ -4,7 +4,6 @@ namespace WixToolset.Extensibility
 {
     using System;
     using System.Collections.Generic;
-    using System.Linq;
     using WixToolset.Data;
     using WixToolset.Data.Symbols;
     using WixToolset.Data.WindowsInstaller;
@@ -12,7 +11,7 @@ namespace WixToolset.Extensibility
     using WixToolset.Extensibility.Services;
 
     /// <summary>
-    /// Base class for creating a preprocessor extension.
+    /// Base class for creating a windows installer backend extension.
     /// </summary>
     public abstract class BaseWindowsInstallerBackendBinderExtension : IWindowsInstallerBackendBinderExtension
     {
@@ -39,7 +38,10 @@ namespace WixToolset.Extensibility
         /// <summary>
         /// Creates a resolved cabinet result.
         /// </summary>
-        protected IResolvedCabinet CreateResolvedCabinet() => this.Context.ServiceProvider.GetService<IResolvedCabinet>();
+        protected IResolvedCabinet CreateResolvedCabinet()
+        {
+            return this.Context.ServiceProvider.GetService<IResolvedCabinet>();
+        }
 
         /// <summary>
         /// See <see cref="IWindowsInstallerBackendBinderExtension.PreBackendBind(IBindContext)"/>
diff --git a/src/api/wix/WixToolset.Extensibility/BaseWindowsInstallerDecompilerExtension.cs b/src/api/wix/WixToolset.Extensibility/BaseWindowsInstallerDecompilerExtension.cs
new file mode 100644
index 00000000..8072cd88
--- /dev/null
+++ b/src/api/wix/WixToolset.Extensibility/BaseWindowsInstallerDecompilerExtension.cs
@@ -0,0 +1,77 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved. Licensed under the Microsoft Reciprocal License. See LICENSE.TXT file in the project root for full license information.
+
+namespace WixToolset.Extensibility
+{
+    using System.Collections.Generic;
+    using WixToolset.Data;
+    using WixToolset.Data.WindowsInstaller;
+    using WixToolset.Extensibility.Data;
+    using WixToolset.Extensibility.Services;
+
+    /// <summary>
+    /// Base class for creating a windows installer decompiler extensions.
+    /// </summary>
+    public abstract class BaseWindowsInstallerDecompilerExtension : IWindowsInstallerDecompilerExtension
+    {
+        /// <summary>
+        /// Context for use by the extension.
+        /// </summary>
+        protected IWindowsInstallerDecompileContext Context { get; private set; }
+
+        /// <summary>
+        /// Messaging for use by the extension.
+        /// </summary>
+        protected IMessaging Messaging { get; private set; }
+
+        /// <summary>
+        /// Decompiler helper for use by the extension.
+        /// </summary>
+        protected IWindowsInstallerDecompilerHelper DecompilerHelper { get; private set; }
+
+        /// <summary>
+        /// See <see cref="IWindowsInstallerDecompilerExtension.TableDefinitions"/>
+        /// </summary>
+        public virtual IReadOnlyCollection<TableDefinition> TableDefinitions { get; }
+
+        /// <summary>
+        /// See <see cref="IWindowsInstallerDecompilerExtension.PostDecompile(IWindowsInstallerDecompileResult)"/>
+        /// </summary>
+        public virtual void PreDecompile(IWindowsInstallerDecompileContext context)
+        {
+            this.Context = context;
+
+            this.Messaging = context.ServiceProvider.GetService<IMessaging>();
+
+            this.DecompilerHelper = context.ServiceProvider.GetService<IWindowsInstallerDecompilerHelper>();
+        }
+
+        /// <summary>
+        /// See <see cref="IWindowsInstallerDecompilerExtension.PreDecompileTables(TableIndexedCollection)"/>
+        /// </summary>
+        public virtual void PreDecompileTables(TableIndexedCollection tables)
+        {
+        }
+
+        /// <summary>
+        /// See <see cref="IWindowsInstallerDecompilerExtension.TryDecompileTable(Table)"/>
+        /// </summary>
+        public virtual bool TryDecompileTable(Table table)
+        {
+            return false;
+        }
+
+        /// <summary>
+        /// See <see cref="IWindowsInstallerDecompilerExtension.PostDecompileTables(TableIndexedCollection)"/>
+        /// </summary>
+        public virtual void PostDecompileTables(TableIndexedCollection tables)
+        {
+        }
+
+        /// <summary>
+        /// See <see cref="IWindowsInstallerDecompilerExtension.PostDecompile(IWindowsInstallerDecompileResult)"/>
+        /// </summary>
+        public virtual void PostDecompile(IWindowsInstallerDecompileResult result)
+        {
+        }
+    }
+}
diff --git a/src/api/wix/WixToolset.Extensibility/Data/IWindowsInstallerDecompileContext.cs b/src/api/wix/WixToolset.Extensibility/Data/IWindowsInstallerDecompileContext.cs
index f744121a..27d30a5a 100644
--- a/src/api/wix/WixToolset.Extensibility/Data/IWindowsInstallerDecompileContext.cs
+++ b/src/api/wix/WixToolset.Extensibility/Data/IWindowsInstallerDecompileContext.cs
@@ -7,7 +7,7 @@ namespace WixToolset.Extensibility.Data
     using WixToolset.Data;
 
     /// <summary>
-    /// The context used to decompile Windows Installer packages.
+    /// The context used to decompile a Windows Installer database.
     /// </summary>
     public interface IWindowsInstallerDecompileContext
     {
@@ -32,6 +32,16 @@ namespace WixToolset.Extensibility.Data
         IReadOnlyCollection<IWindowsInstallerDecompilerExtension> Extensions { get; set; }
 
         /// <summary>
+        /// Collection of extension data to use during decompiling.
+        /// </summary>
+        IReadOnlyCollection<IExtensionData> ExtensionData { get; set; }
+
+        /// <summary>
+        /// Symbol definition creator used to load extension data.
+        /// </summary>
+        ISymbolDefinitionCreator SymbolDefinitionCreator { get; set; }
+
+        /// <summary>
         /// Gets or sets the folder where content is extracted.
         /// </summary>
         string ExtractFolder { get; set; }
diff --git a/src/api/wix/WixToolset.Extensibility/Data/IWindowsInstallerDecompileResult.cs b/src/api/wix/WixToolset.Extensibility/Data/IWindowsInstallerDecompileResult.cs
index 3b1dd815..724dd7fc 100644
--- a/src/api/wix/WixToolset.Extensibility/Data/IWindowsInstallerDecompileResult.cs
+++ b/src/api/wix/WixToolset.Extensibility/Data/IWindowsInstallerDecompileResult.cs
@@ -6,13 +6,24 @@ namespace WixToolset.Extensibility.Data
     using System.Xml.Linq;
     using WixToolset.Data;
 
-#pragma warning disable 1591 // TODO: add documentation
+    /// <summary>
+    /// The result from decompiling a Windows Installer database.
+    /// </summary>
     public interface IWindowsInstallerDecompileResult
     {
+        /// <summary>
+        /// Decompiled document.
+        /// </summary>
         XDocument Document { get; set; }
 
-        IReadOnlyCollection<string> ExtractedFilePaths { get; set; }
+        /// <summary>
+        /// Extracted paths.
+        /// </summary>
+        IList<string> ExtractedFilePaths { get; set; }
 
+        /// <summary>
+        /// Decompiled platform.
+        /// </summary>
         Platform? Platform { get; set; }
     }
 }
diff --git a/src/api/wix/WixToolset.Extensibility/DecompilerExtension.cs b/src/api/wix/WixToolset.Extensibility/DecompilerExtension.cs
deleted file mode 100644
index b492cf3a..00000000
--- a/src/api/wix/WixToolset.Extensibility/DecompilerExtension.cs
+++ /dev/null
@@ -1,61 +0,0 @@
-// Copyright (c) .NET Foundation and contributors. All rights reserved. Licensed under the Microsoft Reciprocal License. See LICENSE.TXT file in the project root for full license information.
-
-namespace WixToolset.Extensibility
-{
-    using WixToolset.Data;
-
-#if BRING_BACK_LATER
-    /// <summary>
-    /// Base class for creating a decompiler extension.
-    /// </summary>
-    public abstract class DecompilerExtension : IDecompilerExtension
-    {
-        /// <summary>
-        /// Gets or sets the decompiler core for the extension.
-        /// </summary>
-        /// <value>The decompiler core for the extension.</value>
-        public IDecompilerCore Core { get; set; }
-
-        /// <summary>
-        /// Gets the table definitions this extension decompiles.
-        /// </summary>
-        /// <value>Table definitions this extension decompiles.</value>
-        public virtual TableDefinitionCollection TableDefinitions { get; protected set; }
-
-        /// <summary>
-        /// Gets the library that this decompiler wants removed from the decomipiled output.
-        /// </summary>
-        /// <param name="tableDefinitions">The table definitions to use while loading the library.</param>
-        /// <returns>The library for this extension or null if there is no library to be removed.</returns>
-        public virtual Library GetLibraryToRemove(TableDefinitionCollection tableDefinitions)
-        {
-            return null;
-        }
-
-        /// <summary>
-        /// Called at the beginning of the decompilation of a database.
-        /// </summary>
-        /// <param name="tables">The collection of all tables.</param>
-        public virtual void Initialize(TableIndexedCollection tables)
-        {
-        }
-
-        /// <summary>
-        /// Decompiles an extension table.
-        /// </summary>
-        /// <param name="table">The table to decompile.</param>
-        public virtual void DecompileTable(Table table)
-        {
-            this.Core.UnexpectedTable(table);
-        }
-
-        /// <summary>
-        /// Finalize decompilation.
-        /// </summary>
-        /// <param name="tables">The collection of all tables.</param>
-        public virtual void Finish(TableIndexedCollection tables)
-        {
-        }
-    }
-#endif
-}
diff --git a/src/api/wix/WixToolset.Extensibility/IWindowsInstallerDecompilerExtension.cs b/src/api/wix/WixToolset.Extensibility/IWindowsInstallerDecompilerExtension.cs
index add5f886..f7d54799 100644
--- a/src/api/wix/WixToolset.Extensibility/IWindowsInstallerDecompilerExtension.cs
+++ b/src/api/wix/WixToolset.Extensibility/IWindowsInstallerDecompilerExtension.cs
@@ -2,21 +2,45 @@
 
 namespace WixToolset.Extensibility
 {
-    using WixToolset.Data;
+    using System.Collections.Generic;
     using WixToolset.Data.WindowsInstaller;
     using WixToolset.Extensibility.Data;
 
     /// <summary>
-    /// Interface all binder extensions implement.
+    /// Interface all windows installer decompiler extensions implement.
     /// </summary>
     public interface IWindowsInstallerDecompilerExtension
     {
         /// <summary>
+        /// Gets the table definitions this extension decompiles.
+        /// </summary>
+        /// <value>Table definitions this extension decompiles.</value>
+        IReadOnlyCollection<TableDefinition> TableDefinitions { get; }
+
+        /// <summary>
         /// Called before decompiling occurs.
         /// </summary>
+        /// <param name="context">Decompile context.</param>
         void PreDecompile(IWindowsInstallerDecompileContext context);
 
-        // TODO: Redesign this interface to be useful.
+        /// <summary>
+        /// Called before decompiling occurs.
+        /// </summary>
+        /// <param name="tables">The collection of all tables.</param>
+        void PreDecompileTables(TableIndexedCollection tables);
+
+        /// <summary>
+        /// Try to decompile an extension table.
+        /// </summary>
+        /// <param name="table">The table to decompile.</param>
+        /// <returns>True if the table was decompiled, false otherwise.</returns>
+        bool TryDecompileTable(Table table);
+
+        /// <summary>
+        /// After decompilation tables.
+        /// </summary>
+        /// <param name="tables">The collection of all tables.</param>
+        void PostDecompileTables(TableIndexedCollection tables);
 
         /// <summary>
         /// Called after all output changes occur and right before the output is bound into its final format.
diff --git a/src/api/wix/WixToolset.Extensibility/Services/IWindowsInstallerDecompilerHelper.cs b/src/api/wix/WixToolset.Extensibility/Services/IWindowsInstallerDecompilerHelper.cs
new file mode 100644
index 00000000..1f5ac47a
--- /dev/null
+++ b/src/api/wix/WixToolset.Extensibility/Services/IWindowsInstallerDecompilerHelper.cs
@@ -0,0 +1,180 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved. Licensed under the Microsoft Reciprocal License. See LICENSE.TXT file in the project root for full license information.
+
+namespace WixToolset.Extensibility.Services
+{
+    using System.Xml.Linq;
+    using WixToolset.Data.WindowsInstaller;
+
+    /// <summary>
+    /// Interface provided to help Windows Installer decompiler extensions.
+    /// </summary>
+    public interface IWindowsInstallerDecompilerHelper
+    {
+        /// <summary>
+        /// Gets or sets the root element of the decompiled output.
+        /// </summary>
+        XElement RootElement { get; set; }
+
+        /// <summary>
+        /// Creates an element from the standard WiX Toolset namespace and adds it to the root document.
+        /// </summary>
+        /// <param name="name">Name of the element to create and add.</param>
+        /// <param name="content">Optional content to add to the new element.</param>
+        /// <returns>Element in the standard namespace.</returns>
+        XElement AddElementToRoot(string name, params object[] content);
+
+        /// <summary>
+        /// Creates an element with the specified name and adds it to the root document.
+        /// </summary>
+        /// <param name="name">Name of the element to create and add.</param>
+        /// <param name="content">Optional content to add to the new element.</param>
+        /// <returns>Element in the standard namespace.</returns>
+        XElement AddElementToRoot(XName name, params object[] content);
+
+        /// <summary>
+        /// Adds an existing element to the root document.
+        /// </summary>
+        /// <param name="element">Element to add.</param>
+        /// <returns>Same element provided.</returns>
+        XElement AddElementToRoot(XElement element);
+
+        /// <summary>
+        /// Creates an element from the standard WiX Toolset namespace.
+        /// </summary>
+        /// <param name="name">Name of the element to create.</param>
+        /// <param name="content">Optional content to add to the new element.</param>
+        /// <returns>Element in the standard namespace.</returns>
+        XElement CreateElement(string name, params object[] content);
+
+        /// <summary>
+        /// Get an element index by a row's table and primary keys.
+        /// </summary>
+        /// <param name="row">Row to get element.</param>
+        /// <returns>Element indexed for the row or null if not found.</returns>
+        XElement GetIndexedElement(Row row);
+
+        /// <summary>
+        /// Get an element index by table and primary key.
+        /// </summary>
+        /// <param name="table">Table name for indexed element.</param>
+        /// <param name="primaryKey">Primary key for indexed element.</param>
+        /// <returns>Element indexed for the table and primary key or null if not found.</returns>
+        XElement GetIndexedElement(string table, string primaryKey);
+
+        /// <summary>
+        /// Get an element index by table and primary keys.
+        /// </summary>
+        /// <param name="table">Table name for indexed element.</param>
+        /// <param name="primaryKey1">Primary key for first column indexed element.</param>
+        /// <param name="primaryKey2">Primary key for second column indexed element.</param>
+        /// <returns>Element indexed for the table and primary keys or null if not found.</returns>
+        XElement GetIndexedElement(string table, string primaryKey1, string primaryKey2);
+
+        /// <summary>
+        /// Get an element index by table and primary keys.
+        /// </summary>
+        /// <param name="table">Table name for indexed element.</param>
+        /// <param name="primaryKey1">Primary key for first column indexed element.</param>
+        /// <param name="primaryKey2">Primary key for second column indexed element.</param>
+        /// <param name="primaryKey3">Primary key for third column indexed element.</param>
+        /// <returns>Element indexed for the table and primary keys or null if not found.</returns>
+        XElement GetIndexedElement(string table, string primaryKey1, string primaryKey2, string primaryKey3);
+
+        /// <summary>
+        /// Get an element index by table and primary keys.
+        /// </summary>
+        /// <param name="table">Table name for indexed element.</param>
+        /// <param name="primaryKeys">Primary keys for indexed element.</param>
+        /// <returns>Element indexed for the table and primary keys or null if not found.</returns>
+        XElement GetIndexedElement(string table, string[] primaryKeys);
+
+        /// <summary>
+        /// Try to get an element index by a row's table and primary keys.
+        /// </summary>
+        /// <param name="row">Row to get element.</param>
+        /// <param name="element">Element indexed for the row.</param>
+        /// <returns>True if the element was index otherwise false.</returns>
+        bool TryGetIndexedElement(Row row, out XElement element);
+
+        /// <summary>
+        /// Try to get an element index by table name and primary key.
+        /// </summary>
+        /// <param name="table">Table name for indexed element.</param>
+        /// <param name="primaryKey">Primary key for indexed element.</param>
+        /// <param name="element">Element indexed for the table and primary key.</param>
+        /// <returns>True if the element was index otherwise false.</returns>
+        bool TryGetIndexedElement(string table, string primaryKey, out XElement element);
+
+        /// <summary>
+        /// Try to get an element index by table name and primary keys.
+        /// </summary>
+        /// <param name="table">Table name for indexed element.</param>
+        /// <param name="primaryKey1">First column's primary key for indexed element.</param>
+        /// <param name="primaryKey2">Second column's primary key for indexed element.</param>
+        /// <param name="element">Element indexed for the table and primary key.</param>
+        /// <returns>True if the element was index otherwise false.</returns>
+        bool TryGetIndexedElement(string table, string primaryKey1, string primaryKey2, out XElement element);
+
+        /// <summary>
+        /// Try to get an element index by table name and primary keys.
+        /// </summary>
+        /// <param name="table">Table name for indexed element.</param>
+        /// <param name="primaryKey1">First column's primary key for indexed element.</param>
+        /// <param name="primaryKey2">Second column's primary key for indexed element.</param>
+        /// <param name="primaryKey3">Third column's primary key for indexed element.</param>
+        /// <param name="element">Element indexed for the table and primary key.</param>
+        /// <returns>True if the element was index otherwise false.</returns>
+        bool TryGetIndexedElement(string table, string primaryKey1, string primaryKey2, string primaryKey3, out XElement element);
+
+        /// <summary>
+        /// Try to get an element index by table name and primary keys.
+        /// </summary>
+        /// <param name="table">Table name for indexed element.</param>
+        /// <param name="primaryKeys">Primary keys for indexed element.</param>
+        /// <param name="element">Element indexed for the table and primary key.</param>
+        /// <returns>True if the element was index otherwise false.</returns>
+        bool TryGetIndexedElement(string table, string[] primaryKeys, out XElement element);
+
+        /// <summary>
+        /// Index an element by a row's table and primary keys.
+        /// </summary>
+        /// <param name="row">Row to index element.</param>
+        /// <param name="element">Element to index.</param>
+        void IndexElement(Row row, XElement element);
+
+        /// <summary>
+        /// Index an element by table and primary key.
+        /// </summary>
+        /// <param name="table">Table name to index element.</param>
+        /// <param name="primaryKey">Primary key to index element.</param>
+        /// <param name="element">Element to index.</param>
+        void IndexElement(string table, string primaryKey, XElement element);
+
+        /// <summary>
+        /// Index an element by table and primary keys.
+        /// </summary>
+        /// <param name="table">Table name to index element.</param>
+        /// <param name="primaryKey1">First column's primary key to index element.</param>
+        /// <param name="primaryKey2">Second column's primary key to index element.</param>
+        /// <param name="element">Element to index.</param>
+        void IndexElement(string table, string primaryKey1, string primaryKey2, XElement element);
+
+        /// <summary>
+        /// Index an element by table and primary keys.
+        /// </summary>
+        /// <param name="table">Table name to index element.</param>
+        /// <param name="primaryKey1">First column's primary key to index element.</param>
+        /// <param name="primaryKey2">Second column's primary key to index element.</param>
+        /// <param name="primaryKey3">Third column's primary key to index element.</param>
+        /// <param name="element">Element to index.</param>
+        void IndexElement(string table, string primaryKey1, string primaryKey2, string primaryKey3, XElement element);
+
+        /// <summary>
+        /// Index an element by table and primary keys.
+        /// </summary>
+        /// <param name="table">Table name to index element.</param>
+        /// <param name="primaryKeys">Column's primary key to index element.</param>
+        /// <param name="element">Element to index.</param>
+        void IndexElement(string table, string[] primaryKeys, XElement element);
+    }
+}