Experimental Features

Relevant source files

The following files were used as context for generating this wiki page:

• src/System.Management.Automation/engine/ExperimentalFeature/ExperimentalFeature.cs
• src/System.Management.Automation/engine/ExperimentalFeature/GetExperimentalFeatureCommand.cs
• src/System.Management.Automation/engine/Modules/ModuleCmdletBase.cs
• test/powershell/engine/ExperimentalFeature/assets/ExpTest/ExpTest.cs
• test/powershell/engine/ExperimentalFeature/EnableDisable-ExperimentalFeature.Tests.ps1

Experimental Features in PowerShell provide a mechanism to introduce new functionality that is not yet considered stable or part of the core product's guaranteed contract. This system allows developers and users to test and provide feedback on upcoming features while ensuring that they do not interfere with the production environment unless explicitly enabled. These features can apply to both the PowerShell engine itself and individual modules.

Sources: src/System.Management.Automation/engine/ExperimentalFeature/ExperimentalFeature.cs:12-16, src/System.Management.Automation/engine/Modules/ModuleCmdletBase.cs:1342-1345

Core Architecture and Components

The Experimental Feature system is built around the ExperimentalFeature class, which defines the metadata for each feature, including its name, description, source, and current enablement status. Features are categorized into two primary sources: the PowerShell Engine (PSEngine) and external modules.

ExperimentalFeature Class

This class acts as the central data structure. It maintains a list of all available engine features and a map of enabled features retrieved from the configuration.

The diagram above shows the relationship between the feature metadata and the possible actions the engine can take based on feature status.

Sources: src/System.Management.Automation/engine/ExperimentalFeature/ExperimentalFeature.cs:17-105

Naming Conventions

The system enforces strict naming conventions to distinguish between different sources:

• Engine Features: Must start with the "PS" prefix (e.g., PSLoadAssemblyFromNativeCode) and cannot contain dots.
• Module Features: Follow the format ModuleName.FeatureName (e.g., ExpTest.FeatureOne).

Sources: src/System.Management.Automation/engine/ExperimentalFeature/ExperimentalFeature.cs:181-224

Feature Lifecycle and Discovery

The lifecycle of an experimental feature involves registration, discovery via configuration, and conditional execution.

Initialization Flow

During the startup of the PowerShell engine, the ExperimentalFeature static constructor initializes engine-specific features and reads the configuration file (powershell.config.json) to determine which features are enabled.

This flowchart illustrates the sequence of steps taken by the PowerShell engine to prepare the experimental feature environment.

Sources: src/System.Management.Automation/engine/ExperimentalFeature/ExperimentalFeature.cs:81-125, test/powershell/engine/ExperimentalFeature/EnableDisable-ExperimentalFeature.Tests.ps1:10-25

Command Discovery

Users can interact with features using the Get-ExperimentalFeature cmdlet. This command scans both the engine's internal list and available module manifests (.psd1 files) to aggregate all available features.

Component	Description
Name parameter	Supports wildcards for filtering features.
GetAvailableExperimentalFeatures	Internal method that yields engine and module-scoped features.
Sorting	Engine features are prioritized first, followed by module features, both alphabetically.

Sources: src/System.Management.Automation/engine/ExperimentalFeature/GetExperimentalFeatureCommand.cs:15-60

Module Integration

Modules declare their experimental features within the PrivateData section of their manifest.

Manifest Declaration

A module manifest must include feature metadata to participate in the experimental system. If a feature name is invalid or does not match the module name, an error is generated during import.

Sources: src/System.Management.Automation/engine/Modules/ModuleCmdletBase.cs:1342-1400

Code Snippet: Module Manifest Experimental Features

@{
    ModuleVersion = '1.0'
    PrivateData = @{
        PSData = @{
            ExperimentalFeatures = @(
                @{
                    Name = 'MyModule.NewFeature'
                    Description = 'A brief description of the feature'
                }
            )
        }
    }
}

Sources: src/System.Management.Automation/engine/Modules/ModuleCmdletBase.cs:1346-1360, test/powershell/engine/ExperimentalFeature/ExperimentalFeature.Basic.Tests.ps1:417-434

Conditional Logic and Attributes

The PowerShell engine uses attributes and specific logic to "Show" or "Hide" elements based on feature status.

ExperimentalAttribute

This attribute is applied to classes, fields, or properties. It defines the feature name it belongs to and the action (Show or Hide) to take when that feature is enabled.

Property	Type	Description
ExperimentName	String	The unique identifier for the feature.
ExperimentAction	Enum	Determines if the target should be shown or hidden when enabled.

Sources: src/System.Management.Automation/engine/ExperimentalFeature/ExperimentalFeature.cs:257-279

Implementation in Cmdlets

Developers can use these attributes to replace existing cmdlets or add experimental parameters.

[Experimental("ExpTest.FeatureOne", ExperimentAction.Hide)]
[Cmdlet("Invoke", "AzureFunction")]
public class InvokeAzureFunctionCommand : PSCmdlet { ... }

[Experimental("ExpTest.FeatureOne", ExperimentAction.Show)]
[Cmdlet("Invoke", "AzureFunction")]
public class InvokeAzureFunctionCommandV2 : PSCmdlet { ... }

In this example, Version TWO replaces Version ONE only when ExpTest.FeatureOne is enabled.

Sources: test/powershell/engine/ExperimentalFeature/assets/ExpTest/ExpTest.cs:10-40

Configuration and Management

Feature status is persisted in configuration files, with user-level settings taking precedence over system-wide settings.

Enable/Disable Cmdlets

The Enable-ExperimentalFeature and Disable-ExperimentalFeature cmdlets modify the powershell.config.json file. A warning is typically issued because changes to experimental features require a shell restart to take effect.

The sequence diagram demonstrates the user interaction flow for enabling a feature and the required follow-up action.

Sources: test/powershell/engine/ExperimentalFeature/EnableDisable-ExperimentalFeature.Tests.ps1:46-95

Conclusion

Experimental Features provide a robust framework for controlled feature rollout in PowerShell. By utilizing configuration files, manifest declarations, and C# attributes, the system ensures that experimental code paths remain isolated. This architecture supports both engine-level optimizations and module-level innovations, facilitating a feedback loop between developers and the community while maintaining environment stability.

Sources: src/System.Management.Automation/engine/ExperimentalFeature/ExperimentalFeature.cs:12-20, src/System.Management.Automation/engine/Modules/ModuleCmdletBase.cs:1418-1425