@joebigelow / wix-1 / commits / f4af6bf2

Minimize public surface area of Core

Part of wixtoolset/issues#6374

Rob Mensching committed Mar 14, 2021 at 07:30 UTC f4af6bf27abaaac7f0508ce2beafb31b5a64b53f
6 files changed +283 -16
src/WixToolset.Extensibility/Data/IFileFacade.cs new
+126
@@ -0,0 +1,126 @@
1 +// 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.
2 +
3 +namespace WixToolset.Extensibility.Data
4 +{
5 + using System.Collections.Generic;
6 + using WixToolset.Data;
7 + using WixToolset.Data.Symbols;
8 + using WixToolset.Data.WindowsInstaller.Rows;
9 +
10 + /// <summary>
11 + /// Interface that provides a common facade over <c>FileSymbol</c> and <c>FileRow</c>.
12 + /// </summary>
13 + public interface IFileFacade
14 + {
15 + /// <summary>
16 + /// Reference to assembly application for this file.
17 + /// </summary>
18 + string AssemblyApplicationFileRef { get; }
19 +
20 + /// <summary>
21 + /// Reference to assembly manifest for this file.
22 + /// </summary>
23 + string AssemblyManifestFileRef { get; }
24 +
25 + /// <summary>
26 + /// List of assembly name values in the file.
27 + /// </summary>
28 + List<MsiAssemblyNameSymbol> AssemblyNames { get; set; }
29 +
30 + /// <summary>
31 + /// Optionally indicates what sort of assembly the file is.
32 + /// </summary>
33 + AssemblyType? AssemblyType { get; }
34 +
35 + /// <summary>
36 + /// Component containing the file.
37 + /// </summary>
38 + string ComponentRef { get; }
39 +
40 + /// <summary>
41 + /// Indicates whether the file is compressed.
42 + /// </summary>
43 + bool Compressed { get; }
44 +
45 + /// <summary>
46 + /// Disk Id for the file.
47 + /// </summary>
48 + int DiskId { get; set; }
49 +
50 + /// <summary>
51 + /// Name of the file.
52 + /// </summary>
53 + string FileName { get; }
54 +
55 + /// <summary>
56 + /// Size of the file.
57 + /// </summary>
58 + int FileSize { get; set; }
59 +
60 + /// <summary>
61 + /// Indicates whether the file came from a merge module.
62 + /// </summary>
63 + bool FromModule { get; }
64 +
65 + /// <summary>
66 + /// Indicates whether the file came from a transform.
67 + /// </summary>
68 + bool FromTransform { get; }
69 +
70 + /// <summary>
71 + /// Hash symbol of the file.
72 + /// </summary>
73 + MsiFileHashSymbol Hash { get; set; }
74 +
75 + /// <summary>
76 + /// Underlying identifier of the file.
77 + /// </summary>
78 + Identifier Identifier { get; }
79 +
80 + /// <summary>
81 + /// Helper accessor for the Id of the Identifier.
82 + /// </summary>
83 + string Id { get; }
84 +
85 + /// <summary>
86 + /// Language of the file.
87 + /// </summary>
88 + string Language { get; set; }
89 +
90 + /// <summary>
91 + /// Optional patch group for the file.
92 + /// </summary>
93 + int? PatchGroup { get; }
94 +
95 + /// <summary>
96 + /// Sequence of the file.
97 + /// </summary>
98 + int Sequence { get; set; }
99 +
100 + /// <summary>
101 + /// Source line number that define the file.
102 + /// </summary>
103 + SourceLineNumber SourceLineNumber { get; }
104 +
105 + /// <summary>
106 + /// Source to the file.
107 + /// </summary>
108 + string SourcePath { get; }
109 +
110 + /// <summary>
111 + /// Indicates whether the file is to be uncompressed.
112 + /// </summary>
113 + bool Uncompressed { get; }
114 +
115 + /// <summary>
116 + /// Version of the file.
117 + /// </summary>
118 + string Version { get; set; }
119 +
120 + /// <summary>
121 + /// Gets the underlying <c>FileRow</c> if one is present.
122 + /// </summary>
123 + /// <returns><c>FileRow</c> if one is present, otherwise throws.</returns>
124 + FileRow GetFileRow();
125 + }
126 +}
src/WixToolset.Extensibility/Services/IBackendHelper.cs
+125
@@ -3,7 +3,10 @@
3 namespace WixToolset.Extensibility.Services
4 {
5 using System;
6 + using System.Collections.Generic;
7 using WixToolset.Data;
8 + using WixToolset.Data.Symbols;
9 + using WixToolset.Data.WindowsInstaller.Rows;
10 using WixToolset.Extensibility.Data;
11
12 /// <summary>
@@ -11,6 +14,28 @@ namespace WixToolset.Extensibility.Services
14 /// </summary>
15 public interface IBackendHelper
16 {
17 + /// <summary>
18 + /// Creates a file facade from a <c>FileSymbol</c> and possible <c>AssemblySymbol</c>.
19 + /// </summary>
20 + /// <param name="file"><c>FileSymbol</c> backing the facade.</param>
21 + /// <param name="assembly"><c>AssemblySymbol</c> backing the facade.</param>
22 + /// <returns></returns>
23 + IFileFacade CreateFileFacade(FileSymbol file, AssemblySymbol assembly);
24 +
25 + /// <summary>
26 + /// Creates a file facade from a File row.
27 + /// </summary>
28 + /// <param name="fileRow"><c>FileRow</c> </param>
29 + /// <returns>New <c>IFileFacade</c>.</returns>
30 + IFileFacade CreateFileFacade(FileRow fileRow);
31 +
32 + /// <summary>
33 + /// Creates a file facade from a Merge Module's File symbol.
34 + /// </summary>
35 + /// <param name="fileSymbol"><c>FileSymbol</c> created from a Merge Module.</param>
36 + /// <returns>New <c>IFileFacade</c>.</returns>
37 + IFileFacade CreateFileFacadeFromMergeModule(FileSymbol fileSymbol);
38 +
39 /// <summary>
40 /// Creates a file transfer and marks it redundant if the source and destination are identical.
41 /// </summary>
@@ -20,6 +45,12 @@ namespace WixToolset.Extensibility.Services
45 /// <param name="sourceLineNumbers">Optional source line numbers that requested the file transfer.</param>
46 IFileTransfer CreateFileTransfer(string source, string destination, bool move, SourceLineNumber sourceLineNumbers = null);
47
48 + /// <summary>
49 + /// Creates a MSI compatible GUID.
50 + /// </summary>
51 + /// <returns>Creates an uppercase GUID with braces.</returns>
52 + string CreateGuid();
53 +
54 /// <summary>
55 /// Creates a version 3 name-based UUID.
56 /// </summary>
@@ -36,6 +67,21 @@ namespace WixToolset.Extensibility.Services
67 /// <returns>Resolved directory.</returns>
68 IResolvedDirectory CreateResolvedDirectory(string directoryParent, string name);
69
70 + /// <summary>
71 + /// Extracts embedded files.
72 + /// </summary>
73 + /// <param name="embeddedFiles">Embedded files to extract.</param>
74 + /// <returns><c>ITrackedFile</c> for each embedded file extracted.</returns>
75 + IEnumerable<ITrackedFile> ExtractEmbeddedFiles(IEnumerable<IExpectedExtractFile> embeddedFiles);
76 +
77 + /// <summary>
78 + /// Generate an identifier by hashing data from the row.
79 + /// </summary>
80 + /// <param name="prefix">Three letter or less prefix for generated row identifier.</param>
81 + /// <param name="args">Information to hash.</param>
82 + /// <returns>The generated identifier.</returns>
83 + string GenerateIdentifier(string prefix, params string[] args);
84 +
85 /// <summary>
86 /// Validates path is relative and canonicalizes it.
87 /// For example, "a\..\c\.\d.exe" => "c\d.exe".
@@ -47,6 +93,85 @@ namespace WixToolset.Extensibility.Services
93 /// <returns>The original value if not relative, otherwise the canonicalized relative path.</returns>
94 string GetCanonicalRelativePath(SourceLineNumber sourceLineNumbers, string elementName, string attributeName, string relativePath);
95
96 + /// <summary>
97 + /// Gets a valid code page from the given web name or integer value.
98 + /// </summary>
99 + /// <param name="value">A code page web name or integer value as a string.</param>
100 + /// <param name="allowNoChange">Whether to allow -1 which does not change the database code pages. This may be the case with wxl files.</param>
101 + /// <param name="onlyAnsi">Whether to allow Unicode (UCS) or UTF code pages.</param>
102 + /// <param name="sourceLineNumbers">Source line information for the current authoring.</param>
103 + /// <returns>A valid code page number.</returns>
104 + /// <exception cref="ArgumentOutOfRangeException">The value is an integer less than 0 or greater than 65535.</exception>
105 + /// <exception cref="ArgumentNullException"><paramref name="value"/> is null.</exception>
106 + /// <exception cref="NotSupportedException">The value doesn't not represent a valid code page name or integer value.</exception>
107 + /// <exception cref="WixException">The code page is invalid for summary information.</exception>
108 + int GetValidCodePage(string value, bool allowNoChange = false, bool onlyAnsi = false, SourceLineNumber sourceLineNumbers = null);
109 +
110 + /// <summary>
111 + /// Get a source/target and short/long file name from an MSI Filename column.
112 + /// </summary>
113 + /// <param name="value">The Filename value.</param>
114 + /// <param name="source">true to get a source name; false to get a target name</param>
115 + /// <param name="longName">true to get a long name; false to get a short name</param>
116 + /// <returns>The name.</returns>
117 + string GetMsiFileName(string value, bool source, bool longName);
118 +
119 + /// <summary>
120 + /// Verifies if an identifier is a valid binder variable name.
121 + /// </summary>
122 + /// <param name="variable">Binder variable name to verify.</param>
123 + /// <returns>True if the identifier is a valid binder variable name.</returns>
124 + bool IsValidBinderVariable(string variable);
125 +
126 + /// <summary>
127 + /// Verifies the given string is a valid 4-part version module or bundle version.
128 + /// </summary>
129 + /// <param name="version">The version to verify.</param>
130 + /// <returns>True if version is a valid module or bundle version.</returns>
131 + bool IsValidFourPartVersion(string version);
132 +
133 + /// <summary>
134 + /// Determines if value is a valid identifier.
135 + /// </summary>
136 + /// <param name="id">Identifier to validate.</param>
137 + /// <returns>True if valid identifier, otherwise false.</returns>
138 + bool IsValidIdentifier(string id);
139 +
140 + /// <summary>
141 + /// Verifies the given string is a valid long filename.
142 + /// </summary>
143 + /// <param name="filename">The filename to verify.</param>
144 + /// <param name="allowWildcards">Allow wildcards in the filename.</param>
145 + /// <param name="allowRelative">Allow long file name to be a relative path.</param>
146 + /// <returns>True if filename is a valid long filename.</returns>
147 + bool IsValidLongFilename(string filename, bool allowWildcards, bool allowRelative);
148 +
149 + /// <summary>
150 + /// Verifies the given string is a valid short filename.
151 + /// </summary>
152 + /// <param name="filename">The filename to verify.</param>
153 + /// <param name="allowWildcards">Allow wildcards in the filename.</param>
154 + /// <returns>True if filename is a valid short filename.</returns>
155 + bool IsValidShortFilename(string filename, bool allowWildcards);
156 +
157 + /// <summary>
158 + /// Resolve delayed fields.
159 + /// </summary>
160 + /// <param name="delayedFields">The fields which had resolution delayed.</param>
161 + /// <param name="variableCache">The cached variable values used when resolving delayed fields.</param>
162 + void ResolveDelayedFields(IEnumerable<IDelayedField> delayedFields, Dictionary<string, string> variableCache);
163 +
164 + /// <summary>
165 + /// Get the source/target and short/long file names from an MSI Filename column.
166 + /// </summary>
167 + /// <param name="value">The Filename value.</param>
168 + /// <returns>An array of strings of length 4. The contents are: short target, long target, short source, and long source.</returns>
169 + /// <remarks>
170 + /// If any particular file name part is not parsed, its set to null in the appropriate location of the returned array of strings.
171 + /// Thus the returned array will always be of length 4.
172 + /// </remarks>
173 + string[] SplitMsiFileName(string value);
174 +
175 /// <summary>
176 /// Creates a tracked file.
177 /// </summary>
src/WixToolset.Extensibility/Services/IParseHelper.cs
+2 -13
@@ -107,17 +107,6 @@ namespace WixToolset.Extensibility.Services
107 /// <param name="escapeLeadingHash">If true, "escape" leading '#' characters so the value is written as a REG_SZ.</param>
108 Identifier CreateRegistrySymbol(IntermediateSection section, SourceLineNumber sourceLineNumbers, RegistryRootType root, string key, string name, string value, string componentId, bool escapeLeadingHash);
109
110 - /// <summary>
111 - /// Creates a short file/directory name using an identifier and long file/directory name as input.
112 - /// </summary>
113 - /// <param name="longName">The long file/directory name.</param>
114 - /// <param name="keepExtension">The option to keep the extension on generated short names.</param>
115 - /// <param name="allowWildcards">true if wildcards are allowed in the filename.</param>
116 - /// <param name="args">Any additional information to include in the hash for the generated short name.</param>
117 - /// <returns>The generated 8.3-compliant short file/directory name.</returns>
118 - [Obsolete]
119 - string CreateShortName(string longName, bool keepExtension, bool allowWildcards, params string[] args);
120 -
110 /// <summary>
111 /// Create a WixSimpleReference symbol in the active section.
112 /// </summary>
@@ -394,9 +383,9 @@ namespace WixToolset.Extensibility.Services
383 /// Verifies if a filename is a valid short filename.
384 /// </summary>
385 /// <param name="filename">Filename to verify.</param>
397 - /// <param name="allowWildcards">true if wildcards are allowed in the filename.</param>
386 + /// <param name="allowWildcards">Indicates whether wildcards are allowed in the filename.</param>
387 /// <returns>True if the filename is a valid short filename</returns>
399 - bool IsValidShortFilename(string filename, bool allowWildcards = false);
388 + bool IsValidShortFilename(string filename, bool allowWildcards);
389
390 /// <summary>
391 /// Attempts to use an extension to parse the attribute.
src/WixToolset.Extensibility/Services/IPathResolver.cs
+3 -2
@@ -6,9 +6,10 @@ namespace WixToolset.Extensibility.Services
6 using WixToolset.Data;
7 using WixToolset.Extensibility.Data;
8
9 -#pragma warning disable 1591 // TODO: add documentation
9 + /// <summary>
10 + /// Support for processing paths.
11 + /// </summary>
12 public interface IPathResolver
11 -#pragma warning restore 1591
13 {
14 /// <summary>
15 /// Get the canonical source path of a directory.
src/WixToolset.Extensibility/Services/IWindowsInstallerBackendHelper.cs
+1 -1
@@ -17,7 +17,7 @@ namespace WixToolset.Extensibility.Services
17 /// <param name="symbol">Symbol with line information for the row.</param>
18 /// <param name="data">Windows Installer data.</param>
19 /// <param name="tableDefinition">Table definition for the row.</param>
20 - /// <returns></returns>
20 + /// <returns>Row created in the <paramref name="data"/>.</returns>
21 Row CreateRow(IntermediateSection section, IntermediateSymbol symbol, WindowsInstallerData data, TableDefinition tableDefinition);
22
23 /// <summary>
src/WixToolset.Extensibility/Services/IWixBranding.cs new
+26
@@ -0,0 +1,26 @@
1 +// 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.
2 +
3 +namespace WixToolset.Extensibility.Services
4 +{
5 + using System.Reflection;
6 +
7 + /// <summary>
8 + /// WiX branding interface.
9 + /// </summary>
10 + public interface IWixBranding
11 + {
12 + /// <summary>
13 + /// Gets the value for CreatingApplication field (MSI Summary Information Stream).
14 + /// </summary>
15 + /// <returns>String for creating application.</returns>
16 + string GetCreatingApplication();
17 +
18 + /// <summary>
19 + /// Replaces branding placeholders in original string.
20 + /// </summary>
21 + /// <param name="original">Original string containing placeholders to replace.</param>
22 + /// <param name="assembly">Optional assembly with branding information, if not specified core branding is used.</param>
23 + /// <returns></returns>
24 + string ReplacePlaceholders(string original, Assembly assembly = null);
25 + }
26 +}