Minimize public surface area of Core

Part of wixtoolset/issues#6374

6 files changed, 283 insertions, 16 deletions

diff --git a/src/WixToolset.Extensibility/Data/IFileFacade.cs b/src/WixToolset.Extensibility/Data/IFileFacade.cs
new file mode 100644
index 00000000..fea00d4e
--- /dev/null
+++ b/src/WixToolset.Extensibility/Data/IFileFacade.cs
@@ -0,0 +1,126 @@
+// 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.Data
+{
+    using System.Collections.Generic;
+    using WixToolset.Data;
+    using WixToolset.Data.Symbols;
+    using WixToolset.Data.WindowsInstaller.Rows;
+
+    /// <summary>
+    /// Interface that provides a common facade over <c>FileSymbol</c> and <c>FileRow</c>.
+    /// </summary>
+    public interface IFileFacade
+    {
+        /// <summary>
+        /// Reference to assembly application for this file.
+        /// </summary>
+        string AssemblyApplicationFileRef { get; }
+
+        /// <summary>
+        /// Reference to assembly manifest for this file.
+        /// </summary>
+        string AssemblyManifestFileRef { get; }
+
+        /// <summary>
+        /// List of assembly name values in the file.
+        /// </summary>
+        List<MsiAssemblyNameSymbol> AssemblyNames { get; set; }
+
+        /// <summary>
+        /// Optionally indicates what sort of assembly the file is.
+        /// </summary>
+        AssemblyType? AssemblyType { get; }
+
+        /// <summary>
+        /// Component containing the file.
+        /// </summary>
+        string ComponentRef { get; }
+
+        /// <summary>
+        /// Indicates whether the file is compressed.
+        /// </summary>
+        bool Compressed { get; }
+
+        /// <summary>
+        /// Disk Id for the file.
+        /// </summary>
+        int DiskId { get; set; }
+
+        /// <summary>
+        /// Name of the file.
+        /// </summary>
+        string FileName { get; }
+
+        /// <summary>
+        /// Size of the file.
+        /// </summary>
+        int FileSize { get; set; }
+
+        /// <summary>
+        /// Indicates whether the file came from a merge module.
+        /// </summary>
+        bool FromModule { get; }
+
+        /// <summary>
+        /// Indicates whether the file came from a transform.
+        /// </summary>
+        bool FromTransform { get; }
+
+        /// <summary>
+        /// Hash symbol of the file.
+        /// </summary>
+        MsiFileHashSymbol Hash { get; set; }
+
+        /// <summary>
+        /// Underlying identifier of the file.
+        /// </summary>
+        Identifier Identifier { get; }
+
+        /// <summary>
+        /// Helper accessor for the Id of the Identifier.
+        /// </summary>
+        string Id { get; }
+
+        /// <summary>
+        /// Language of the file.
+        /// </summary>
+        string Language { get; set; }
+
+        /// <summary>
+        /// Optional patch group for the file.
+        /// </summary>
+        int? PatchGroup { get; }
+
+        /// <summary>
+        /// Sequence of the file.
+        /// </summary>
+        int Sequence { get; set; }
+
+        /// <summary>
+        /// Source line number that define the file.
+        /// </summary>
+        SourceLineNumber SourceLineNumber { get; }
+
+        /// <summary>
+        /// Source to the file.
+        /// </summary>
+        string SourcePath { get; }
+
+        /// <summary>
+        /// Indicates whether the file is to be uncompressed.
+        /// </summary>
+        bool Uncompressed { get; }
+
+        /// <summary>
+        /// Version of the file.
+        /// </summary>
+        string Version { get; set; }
+
+        /// <summary>
+        /// Gets the underlying <c>FileRow</c> if one is present.
+        /// </summary>
+        /// <returns><c>FileRow</c> if one is present, otherwise throws.</returns>
+        FileRow GetFileRow();
+    }
+}
diff --git a/src/WixToolset.Extensibility/Services/IBackendHelper.cs b/src/WixToolset.Extensibility/Services/IBackendHelper.cs
index 0c8578b2..ce3ddc89 100644
--- a/src/WixToolset.Extensibility/Services/IBackendHelper.cs
+++ b/src/WixToolset.Extensibility/Services/IBackendHelper.cs
@@ -3,7 +3,10 @@
 namespace WixToolset.Extensibility.Services
 {
     using System;
+    using System.Collections.Generic;
     using WixToolset.Data;
+    using WixToolset.Data.Symbols;
+    using WixToolset.Data.WindowsInstaller.Rows;
     using WixToolset.Extensibility.Data;
 
     /// <summary>
@@ -12,6 +15,28 @@ namespace WixToolset.Extensibility.Services
     public interface IBackendHelper
     {
         /// <summary>
+        /// Creates a file facade from a <c>FileSymbol</c> and possible <c>AssemblySymbol</c>.
+        /// </summary>
+        /// <param name="file"><c>FileSymbol</c> backing the facade.</param>
+        /// <param name="assembly"><c>AssemblySymbol</c> backing the facade.</param>
+        /// <returns></returns>
+        IFileFacade CreateFileFacade(FileSymbol file, AssemblySymbol assembly);
+
+        /// <summary>
+        /// Creates a file facade from a File row.
+        /// </summary>
+        /// <param name="fileRow"><c>FileRow</c> </param>
+        /// <returns>New <c>IFileFacade</c>.</returns>
+        IFileFacade CreateFileFacade(FileRow fileRow);
+
+        /// <summary>
+        /// Creates a file facade from a Merge Module's File symbol.
+        /// </summary>
+        /// <param name="fileSymbol"><c>FileSymbol</c> created from a Merge Module.</param>
+        /// <returns>New <c>IFileFacade</c>.</returns>
+        IFileFacade CreateFileFacadeFromMergeModule(FileSymbol fileSymbol);
+
+        /// <summary>
         /// Creates a file transfer and marks it redundant if the source and destination are identical.
         /// </summary>
         /// <param name="source">Source for the file transfer.</param>
@@ -21,6 +46,12 @@ namespace WixToolset.Extensibility.Services
         IFileTransfer CreateFileTransfer(string source, string destination, bool move, SourceLineNumber sourceLineNumbers = null);
 
         /// <summary>
+        /// Creates a MSI compatible GUID.
+        /// </summary>
+        /// <returns>Creates an uppercase GUID with braces.</returns>
+        string CreateGuid();
+
+        /// <summary>
         /// Creates a version 3 name-based UUID.
         /// </summary>
         /// <param name="namespaceGuid">The namespace UUID.</param>
@@ -37,6 +68,21 @@ namespace WixToolset.Extensibility.Services
         IResolvedDirectory CreateResolvedDirectory(string directoryParent, string name);
 
         /// <summary>
+        /// Extracts embedded files.
+        /// </summary>
+        /// <param name="embeddedFiles">Embedded files to extract.</param>
+        /// <returns><c>ITrackedFile</c> for each embedded file extracted.</returns>
+        IEnumerable<ITrackedFile> ExtractEmbeddedFiles(IEnumerable<IExpectedExtractFile> embeddedFiles);
+
+        /// <summary>
+        /// Generate an identifier by hashing data from the row.
+        /// </summary>
+        /// <param name="prefix">Three letter or less prefix for generated row identifier.</param>
+        /// <param name="args">Information to hash.</param>
+        /// <returns>The generated identifier.</returns>
+        string GenerateIdentifier(string prefix, params string[] args);
+
+        /// <summary>
         /// Validates path is relative and canonicalizes it.
         /// For example, "a\..\c\.\d.exe" => "c\d.exe".
         /// </summary>
@@ -48,6 +94,85 @@ namespace WixToolset.Extensibility.Services
         string GetCanonicalRelativePath(SourceLineNumber sourceLineNumbers, string elementName, string attributeName, string relativePath);
 
         /// <summary>
+        /// Gets a valid code page from the given web name or integer value.
+        /// </summary>
+        /// <param name="value">A code page web name or integer value as a string.</param>
+        /// <param name="allowNoChange">Whether to allow -1 which does not change the database code pages. This may be the case with wxl files.</param>
+        /// <param name="onlyAnsi">Whether to allow Unicode (UCS) or UTF code pages.</param>
+        /// <param name="sourceLineNumbers">Source line information for the current authoring.</param>
+        /// <returns>A valid code page number.</returns>
+        /// <exception cref="ArgumentOutOfRangeException">The value is an integer less than 0 or greater than 65535.</exception>
+        /// <exception cref="ArgumentNullException"><paramref name="value"/> is null.</exception>
+        /// <exception cref="NotSupportedException">The value doesn't not represent a valid code page name or integer value.</exception>
+        /// <exception cref="WixException">The code page is invalid for summary information.</exception>
+        int GetValidCodePage(string value, bool allowNoChange = false, bool onlyAnsi = false, SourceLineNumber sourceLineNumbers = null);
+
+        /// <summary>
+        /// Get a source/target and short/long file name from an MSI Filename column.
+        /// </summary>
+        /// <param name="value">The Filename value.</param>
+        /// <param name="source">true to get a source name; false to get a target name</param>
+        /// <param name="longName">true to get a long name; false to get a short name</param>
+        /// <returns>The name.</returns>
+        string GetMsiFileName(string value, bool source, bool longName);
+
+        /// <summary>
+        /// Verifies if an identifier is a valid binder variable name.
+        /// </summary>
+        /// <param name="variable">Binder variable name to verify.</param>
+        /// <returns>True if the identifier is a valid binder variable name.</returns>
+        bool IsValidBinderVariable(string variable);
+
+        /// <summary>
+        /// Verifies the given string is a valid 4-part version module or bundle version.
+        /// </summary>
+        /// <param name="version">The version to verify.</param>
+        /// <returns>True if version is a valid module or bundle version.</returns>
+        bool IsValidFourPartVersion(string version);
+
+        /// <summary>
+        /// Determines if value is a valid identifier.
+        /// </summary>
+        /// <param name="id">Identifier to validate.</param>
+        /// <returns>True if valid identifier, otherwise false.</returns>
+        bool IsValidIdentifier(string id);
+
+        /// <summary>
+        /// Verifies the given string is a valid long filename.
+        /// </summary>
+        /// <param name="filename">The filename to verify.</param>
+        /// <param name="allowWildcards">Allow wildcards in the filename.</param>
+        /// <param name="allowRelative">Allow long file name to be a relative path.</param>
+        /// <returns>True if filename is a valid long filename.</returns>
+        bool IsValidLongFilename(string filename, bool allowWildcards, bool allowRelative);
+
+        /// <summary>
+        /// Verifies the given string is a valid short filename.
+        /// </summary>
+        /// <param name="filename">The filename to verify.</param>
+        /// <param name="allowWildcards">Allow wildcards in the filename.</param>
+        /// <returns>True if filename is a valid short filename.</returns>
+        bool IsValidShortFilename(string filename, bool allowWildcards);
+
+        /// <summary>
+        /// Resolve delayed fields.
+        /// </summary>
+        /// <param name="delayedFields">The fields which had resolution delayed.</param>
+        /// <param name="variableCache">The cached variable values used when resolving delayed fields.</param>
+        void ResolveDelayedFields(IEnumerable<IDelayedField> delayedFields, Dictionary<string, string> variableCache);
+
+        /// <summary>
+        /// Get the source/target and short/long file names from an MSI Filename column.
+        /// </summary>
+        /// <param name="value">The Filename value.</param>
+        /// <returns>An array of strings of length 4. The contents are: short target, long target, short source, and long source.</returns>
+        /// <remarks>
+        /// If any particular file name part is not parsed, its set to null in the appropriate location of the returned array of strings.
+        /// Thus the returned array will always be of length 4.
+        /// </remarks>
+        string[] SplitMsiFileName(string value);
+
+        /// <summary>
         /// Creates a tracked file.
         /// </summary>
         /// <param name="path">Destination path for the build output.</param>
diff --git a/src/WixToolset.Extensibility/Services/IParseHelper.cs b/src/WixToolset.Extensibility/Services/IParseHelper.cs
index d64efecd..83c66540 100644
--- a/src/WixToolset.Extensibility/Services/IParseHelper.cs
+++ b/src/WixToolset.Extensibility/Services/IParseHelper.cs
@@ -108,17 +108,6 @@ namespace WixToolset.Extensibility.Services
         Identifier CreateRegistrySymbol(IntermediateSection section, SourceLineNumber sourceLineNumbers, RegistryRootType root, string key, string name, string value, string componentId, bool escapeLeadingHash);
 
         /// <summary>
-        /// Creates a short file/directory name using an identifier and long file/directory name as input.
-        /// </summary>
-        /// <param name="longName">The long file/directory name.</param>
-        /// <param name="keepExtension">The option to keep the extension on generated short names.</param>
-        /// <param name="allowWildcards">true if wildcards are allowed in the filename.</param>
-        /// <param name="args">Any additional information to include in the hash for the generated short name.</param>
-        /// <returns>The generated 8.3-compliant short file/directory name.</returns>
-        [Obsolete]
-        string CreateShortName(string longName, bool keepExtension, bool allowWildcards, params string[] args);
-
-        /// <summary>
         /// Create a WixSimpleReference symbol in the active section.
         /// </summary>
         /// <param name="section">Active section.</param>
@@ -394,9 +383,9 @@ namespace WixToolset.Extensibility.Services
         /// Verifies if a filename is a valid short filename.
         /// </summary>
         /// <param name="filename">Filename to verify.</param>
-        /// <param name="allowWildcards">true if wildcards are allowed in the filename.</param>
+        /// <param name="allowWildcards">Indicates whether wildcards are allowed in the filename.</param>
         /// <returns>True if the filename is a valid short filename</returns>
-        bool IsValidShortFilename(string filename, bool allowWildcards = false);
+        bool IsValidShortFilename(string filename, bool allowWildcards);
 
         /// <summary>
         /// Attempts to use an extension to parse the attribute.
diff --git a/src/WixToolset.Extensibility/Services/IPathResolver.cs b/src/WixToolset.Extensibility/Services/IPathResolver.cs
index 5be0c4d3..64362174 100644
--- a/src/WixToolset.Extensibility/Services/IPathResolver.cs
+++ b/src/WixToolset.Extensibility/Services/IPathResolver.cs
@@ -6,9 +6,10 @@ namespace WixToolset.Extensibility.Services
     using WixToolset.Data;
     using WixToolset.Extensibility.Data;
 
-#pragma warning disable 1591 // TODO: add documentation
+    /// <summary>
+    /// Support for processing paths.
+    /// </summary>
     public interface IPathResolver
-#pragma warning restore 1591
     {
         /// <summary>
         /// Get the canonical source path of a directory.
diff --git a/src/WixToolset.Extensibility/Services/IWindowsInstallerBackendHelper.cs b/src/WixToolset.Extensibility/Services/IWindowsInstallerBackendHelper.cs
index 80d49d54..81325131 100644
--- a/src/WixToolset.Extensibility/Services/IWindowsInstallerBackendHelper.cs
+++ b/src/WixToolset.Extensibility/Services/IWindowsInstallerBackendHelper.cs
@@ -17,7 +17,7 @@ namespace WixToolset.Extensibility.Services
         /// <param name="symbol">Symbol with line information for the row.</param>
         /// <param name="data">Windows Installer data.</param>
         /// <param name="tableDefinition">Table definition for the row.</param>
-        /// <returns></returns>
+        /// <returns>Row created in the <paramref name="data"/>.</returns>
         Row CreateRow(IntermediateSection section, IntermediateSymbol symbol, WindowsInstallerData data, TableDefinition tableDefinition);
 
         /// <summary>
diff --git a/src/WixToolset.Extensibility/Services/IWixBranding.cs b/src/WixToolset.Extensibility/Services/IWixBranding.cs
new file mode 100644
index 00000000..4bac9ccd
--- /dev/null
+++ b/src/WixToolset.Extensibility/Services/IWixBranding.cs
@@ -0,0 +1,26 @@
+// 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.Reflection;
+
+    /// <summary>
+    /// WiX branding interface.
+    /// </summary>
+    public interface IWixBranding
+    {
+        /// <summary>
+        /// Gets the value for CreatingApplication field (MSI Summary Information Stream).
+        /// </summary>
+        /// <returns>String for creating application.</returns>
+        string GetCreatingApplication();
+
+        /// <summary>
+        /// Replaces branding placeholders in original string.
+        /// </summary>
+        /// <param name="original">Original string containing placeholders to replace.</param>
+        /// <param name="assembly">Optional assembly with branding information, if not specified core branding is used.</param>
+        /// <returns></returns>
+        string ReplacePlaceholders(string original, Assembly assembly = null);
+    }
+}