/
ExperimentalFeature.cs
388 lines (337 loc) · 16.3 KB
/
ExperimentalFeature.cs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.
using System.Collections;
using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.Linq;
using System.Management.Automation.Configuration;
using System.Management.Automation.Internal;
using System.Management.Automation.Tracing;
using System.Runtime.CompilerServices;
using Microsoft.PowerShell.Telemetry;
namespace System.Management.Automation
{
/// <summary>
/// Support experimental features in PowerShell.
/// </summary>
public class ExperimentalFeature
{
#region Const Members
internal const string EngineSource = "PSEngine";
internal const string PSNativeCommandArgumentPassingFeatureName = "PSNativeCommandArgumentPassing";
internal const string PSNativeCommandErrorActionPreferenceFeatureName = "PSNativeCommandErrorActionPreference";
internal const string PSCleanBlockFeatureName = "PSCleanBlock";
#endregion
#region Instance Members
/// <summary>
/// Name of an experimental feature.
/// </summary>
public string Name { get; }
/// <summary>
/// Description of an experimental feature.
/// </summary>
public string Description { get; }
/// <summary>
/// Source of an experimental feature.
/// </summary>
public string Source { get; }
/// <summary>
/// Indicate whether the feature is enabled.
/// </summary>
public bool Enabled { get; private set; }
/// <summary>
/// Initializes a new instance of the <see cref="ExperimentalFeature"/> class.
/// </summary>
/// <param name="name">The name of the experimental feature.</param>
/// <param name="description">A description of the experimental feature.</param>
/// <param name="source">The source where the experimental feature is defined.</param>
/// <param name="isEnabled">Indicate whether the experimental feature is enabled.</param>
internal ExperimentalFeature(string name, string description, string source, bool isEnabled)
{
Name = name;
Description = description;
Source = source;
Enabled = isEnabled;
}
/// <summary>
/// Initializes a new instance of the <see cref="ExperimentalFeature"/> class.
/// This is a private constructor only for declaring new experimental features within this type.
/// </summary>
/// <param name="name">The name of the experimental feature.</param>
/// <param name="description">A description of the experimental feature.</param>
private ExperimentalFeature(string name, string description)
: this(name, description, source: EngineSource, isEnabled: false)
{
}
#endregion
#region Static Members
/// <summary>
/// All available engine experimental features.
/// </summary>
internal static readonly ReadOnlyCollection<ExperimentalFeature> EngineExperimentalFeatures;
/// <summary>
/// A dictionary of all available engine experimental features. Feature name is the key.
/// </summary>
internal static readonly ReadOnlyDictionary<string, ExperimentalFeature> EngineExperimentalFeatureMap;
/// <summary>
/// Experimental feature names that are enabled in the config file.
/// </summary>
internal static readonly ReadOnlyBag<string> EnabledExperimentalFeatureNames;
/// <summary>
/// Type initializer. Initialize the engine experimental feature list.
/// </summary>
static ExperimentalFeature()
{
// Initialize the readonly collection 'EngineExperimentalFeatures'.
var engineFeatures = new ExperimentalFeature[] {
/* Register engine experimental features here. Follow the same pattern as the example:
new ExperimentalFeature(
name: "PSFileSystemProviderV2",
description: "Replace the old FileSystemProvider with cleaner design and faster code"),
*/
new ExperimentalFeature(
name: "PSCommandNotFoundSuggestion",
description: "Recommend potential commands based on fuzzy search on a CommandNotFoundException"),
new ExperimentalFeature(
name: "PSNativePSPathResolution",
description: "Convert PSPath to filesystem path, if possible, for native commands"),
new ExperimentalFeature(
name: "PSSubsystemPluginModel",
description: "A plugin model for registering and un-registering PowerShell subsystems"),
new ExperimentalFeature(
name: PSNativeCommandArgumentPassingFeatureName,
description: "Use ArgumentList when invoking a native command"),
new ExperimentalFeature(
name: "PSLoadAssemblyFromNativeCode",
description: "Expose an API to allow assembly loading from native code"),
new ExperimentalFeature(
name: "PSAnsiRenderingFileInfo",
description: "Enable coloring for FileInfo objects"),
new ExperimentalFeature(
name: PSNativeCommandErrorActionPreferenceFeatureName,
description: "Native commands with non-zero exit codes issue errors according to $ErrorActionPreference when $PSNativeCommandUseErrorActionPreference is $true"),
new ExperimentalFeature(
name: PSCleanBlockFeatureName,
description: "Add support of a 'Clean' block to functions and script cmdlets for easy resource cleanup"),
};
EngineExperimentalFeatures = new ReadOnlyCollection<ExperimentalFeature>(engineFeatures);
// Initialize the readonly dictionary 'EngineExperimentalFeatureMap'.
var engineExpFeatureMap = engineFeatures.ToDictionary(static f => f.Name, StringComparer.OrdinalIgnoreCase);
EngineExperimentalFeatureMap = new ReadOnlyDictionary<string, ExperimentalFeature>(engineExpFeatureMap);
// Initialize the readonly hashset 'EnabledExperimentalFeatureNames'.
// The initialization of 'EnabledExperimentalFeatureNames' is deliberately made in the type initializer so that:
// 1. 'EnabledExperimentalFeatureNames' can be declared as readonly;
// 2. No need to deal with initialization from multiple threads;
// 3. We don't need to decide where/when to read the config file for the enabled experimental features,
// instead, it will be done when the type is used for the first time, which is always earlier than
// any experimental features take effect.
string[] enabledFeatures = Array.Empty<string>();
try
{
enabledFeatures = PowerShellConfig.Instance.GetExperimentalFeatures();
}
catch (Exception e) when (LogException(e)) { }
EnabledExperimentalFeatureNames = ProcessEnabledFeatures(enabledFeatures);
}
/// <summary>
/// Process the array of enabled feature names retrieved from configuration.
/// Ignore invalid feature names and unavailable engine feature names, and
/// return an ReadOnlyBag of the valid enabled feature names.
/// </summary>
private static ReadOnlyBag<string> ProcessEnabledFeatures(string[] enabledFeatures)
{
if (enabledFeatures.Length == 0) { return ReadOnlyBag<string>.Empty; }
var list = new List<string>(enabledFeatures.Length);
foreach (string name in enabledFeatures)
{
if (IsModuleFeatureName(name))
{
list.Add(name);
ApplicationInsightsTelemetry.SendTelemetryMetric(TelemetryType.ExperimentalModuleFeatureActivation, name);
}
else if (IsEngineFeatureName(name))
{
if (EngineExperimentalFeatureMap.TryGetValue(name, out ExperimentalFeature feature))
{
feature.Enabled = true;
list.Add(name);
ApplicationInsightsTelemetry.SendTelemetryMetric(TelemetryType.ExperimentalEngineFeatureActivation, name);
}
else
{
string message = StringUtil.Format(Logging.EngineExperimentalFeatureNotFound, name);
LogError(PSEventId.ExperimentalFeature_InvalidName, name, message);
}
}
else
{
string message = StringUtil.Format(Logging.InvalidExperimentalFeatureName, name);
LogError(PSEventId.ExperimentalFeature_InvalidName, name, message);
}
}
return new ReadOnlyBag<string>(new HashSet<string>(list, StringComparer.OrdinalIgnoreCase));
}
/// <summary>
/// Log the exception without rewinding the stack.
/// </summary>
private static bool LogException(Exception e)
{
LogError(PSEventId.ExperimentalFeature_ReadConfig_Error, e.GetType().FullName, e.Message, e.StackTrace);
return false;
}
/// <summary>
/// Log an error message.
/// </summary>
private static void LogError(PSEventId eventId, params object[] args)
{
PSEtwLog.LogOperationalError(eventId, PSOpcode.Constructor, PSTask.ExperimentalFeature, PSKeyword.UseAlwaysOperational, args);
}
/// <summary>
/// Check if the name follows the engine experimental feature name convention.
/// Convention: prefix 'PS' to the feature name -- 'PSFeatureName'.
/// </summary>
internal static bool IsEngineFeatureName(string featureName)
{
return featureName.Length > 2 && !featureName.Contains('.') && featureName.StartsWith("PS", StringComparison.Ordinal);
}
/// <summary>
/// Check if the name follows the module experimental feature name convention.
/// Convention: prefix the module name to the feature name -- 'ModuleName.FeatureName'.
/// </summary>
/// <param name="featureName">The feature name to check.</param>
/// <param name="moduleName">When specified, we check if the feature name matches the module name.</param>
internal static bool IsModuleFeatureName(string featureName, string moduleName = null)
{
// Feature names cannot start with a dot
if (featureName.StartsWith('.'))
{
return false;
}
// Feature names must contain a dot, but not at the end
int lastDotIndex = featureName.LastIndexOf('.');
if (lastDotIndex == -1 || lastDotIndex == featureName.Length - 1)
{
return false;
}
if (moduleName == null)
{
return true;
}
// If the module name is given, it must match the prefix of the feature name (up to the last dot).
var moduleNamePart = featureName.AsSpan(0, lastDotIndex);
return moduleNamePart.Equals(moduleName.AsSpan(), StringComparison.OrdinalIgnoreCase);
}
/// <summary>
/// Determine the action to take for the specified experiment name and action.
/// </summary>
internal static ExperimentAction GetActionToTake(string experimentName, ExperimentAction experimentAction)
{
if (experimentName == null || experimentAction == ExperimentAction.None)
{
// If either the experiment name or action is not defined, then return 'Show' by default.
// This could happen to 'ParameterAttribute' when no experimental related field is declared.
return ExperimentAction.Show;
}
ExperimentAction action = experimentAction;
if (!IsEnabled(experimentName))
{
action = (action == ExperimentAction.Hide) ? ExperimentAction.Show : ExperimentAction.Hide;
}
return action;
}
/// <summary>
/// Check if the specified experimental feature has been enabled.
/// </summary>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static bool IsEnabled(string featureName)
{
return EnabledExperimentalFeatureNames.Contains(featureName);
}
#endregion
}
/// <summary>
/// Indicates the action to take on the cmdlet/parameter that has the attribute declared.
/// </summary>
public enum ExperimentAction
{
/// <summary>
/// Represent an undefined action, used as the default value.
/// </summary>
None = 0,
/// <summary>
/// Hide the cmdlet/parameter when the corresponding experimental feature is enabled.
/// </summary>
Hide = 1,
/// <summary>
/// Show the cmdlet/parameter when the corresponding experimental feature is enabled.
/// </summary>
Show = 2
}
/// <summary>
/// The attribute that applies to cmdlet/function/parameter to define what the engine should do with it.
/// </summary>
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Field | AttributeTargets.Property)]
public sealed class ExperimentalAttribute : ParsingBaseAttribute
{
/// <summary>
/// Get name of the experimental feature this attribute is associated with.
/// </summary>
public string ExperimentName { get; }
/// <summary>
/// Get action for engine to take when the experimental feature is enabled.
/// </summary>
public ExperimentAction ExperimentAction { get; }
/// <summary>
/// Initializes a new instance of the ExperimentalAttribute class.
/// </summary>
public ExperimentalAttribute(string experimentName, ExperimentAction experimentAction)
{
ValidateArguments(experimentName, experimentAction);
ExperimentName = experimentName;
ExperimentAction = experimentAction;
}
/// <summary>
/// Initialize an instance that represents the none-value.
/// </summary>
private ExperimentalAttribute() { }
/// <summary>
/// An instance that represents the none-value.
/// </summary>
internal static readonly ExperimentalAttribute None = new ExperimentalAttribute();
/// <summary>
/// Validate arguments for the constructor.
/// </summary>
internal static void ValidateArguments(string experimentName, ExperimentAction experimentAction)
{
if (string.IsNullOrEmpty(experimentName))
{
const string paramName = nameof(experimentName);
throw PSTraceSource.NewArgumentNullException(paramName, Metadata.ArgumentNullOrEmpty, paramName);
}
if (experimentAction == ExperimentAction.None)
{
const string paramName = nameof(experimentAction);
const string invalidMember = nameof(ExperimentAction.None);
string validMembers = StringUtil.Format("{0}, {1}", ExperimentAction.Hide, ExperimentAction.Show);
throw PSTraceSource.NewArgumentException(paramName, Metadata.InvalidEnumArgument, invalidMember, paramName, validMembers);
}
}
internal bool ToHide => EffectiveAction == ExperimentAction.Hide;
internal bool ToShow => EffectiveAction == ExperimentAction.Show;
/// <summary>
/// Get effective action to take at run time.
/// </summary>
private ExperimentAction EffectiveAction
{
get
{
if (_effectiveAction == ExperimentAction.None)
{
_effectiveAction = ExperimentalFeature.GetActionToTake(ExperimentName, ExperimentAction);
}
return _effectiveAction;
}
}
private ExperimentAction _effectiveAction = ExperimentAction.None;
}
}