Minor pipeline refactor (microsoft#2530)

docs/CHANGELOG-v3.md

@@ -38,8 +38,11 @@ What's changed since pre-release v3.0.0-B0203:
     - If a rule fails with a severity level equal or higher than the configured level the pipeline will break.
 - General improvements:
   - **Breaking change**: Improve scope handling for correctly handling cases with multiple module by @BernieWhite.
-    - As a result of this change the `binding` property can no longer be used within baselines.
-    - Use module configuration or workspace options instead.
+    [#1215](https://github.com/microsoft/PSRule/issues/1215)
+    - As a result of this change:
+      - The `binding` property can no longer be used within baselines.
+      - Custom inline script blocks can no longer be used for custom binding.
+    - Use module configuration or workspace to configure binding options instead.
   - Added support for native logging within emitters by @BernieWhite.
     [#1837](https://github.com/microsoft/PSRule/issues/1837)
 - Engineering:

docs/commands/PSRule/en-US/New-PSRuleOption.md

@@ -17,8 +17,8 @@ Create options to configure PSRule execution.
 
 ```text
 New-PSRuleOption [[-Path] <String>] [-Configuration <ConfigurationOption>]
- [-SuppressTargetName <SuppressionOption>] [-BindTargetName <BindTargetName[]>]
- [-BindTargetType <BindTargetName[]>] [-BaselineGroup <Hashtable>] [-BindingIgnoreCase <Boolean>]
+ [-SuppressTargetName <SuppressionOption>]
+ [-BaselineGroup <Hashtable>] [-BindingIgnoreCase <Boolean>]
  [-BindingField <Hashtable>] [-BindingNameSeparator <String>] [-BindingPreferTargetInfo <Boolean>]
  [-TargetName <String[]>] [-TargetType <String[]>] [-BindingUseQualifiedName <Boolean>]
  [-Convention <String[]>] [-DuplicateResourceId <ExecutionActionPreference>]
@@ -44,8 +44,8 @@ New-PSRuleOption [[-Path] <String>] [-Configuration <ConfigurationOption>]
 
 ```text
 New-PSRuleOption [-Option] <PSRuleOption> [-Configuration <ConfigurationOption>]
- [-SuppressTargetName <SuppressionOption>] [-BindTargetName <BindTargetName[]>]
- [-BindTargetType <BindTargetName[]>] [-BaselineGroup <Hashtable>] [-BindingIgnoreCase <Boolean>]
+ [-SuppressTargetName <SuppressionOption>]
+ [-BaselineGroup <Hashtable>] [-BindingIgnoreCase <Boolean>]
  [-BindingField <Hashtable>] [-BindingNameSeparator <String>] [-BindingPreferTargetInfo <Boolean>]
  [-TargetName <String[]>] [-TargetType <String[]>] [-BindingUseQualifiedName <Boolean>]
  [-Convention <String[]>] [-DuplicateResourceId <ExecutionActionPreference>]
@@ -71,7 +71,7 @@ New-PSRuleOption [-Option] <PSRuleOption> [-Configuration <ConfigurationOption>]
 
 ```text
 New-PSRuleOption [-Default] [-Configuration <ConfigurationOption>] [-SuppressTargetName <SuppressionOption>]
- [-BindTargetName <BindTargetName[]>] [-BindTargetType <BindTargetName[]>] [-BaselineGroup <Hashtable>]
+ [-BaselineGroup <Hashtable>]
  [-BindingIgnoreCase <Boolean>] [-BindingField <Hashtable>] [-BindingNameSeparator <String>]
  [-BindingPreferTargetInfo <Boolean>] [-TargetName <String[]>] [-TargetType <String[]>]
  [-BindingUseQualifiedName <Boolean>] [-Convention <String[]>]
@@ -118,28 +118,6 @@ Create an options object that suppresses `TestObject1` and `TestObject3` for a r
 
 ### Example 3
 
-```powershell
-# Create a custom function that returns a TargetName string
-$bindFn = {
-    param ($TargetObject)
-
-    $otherName = $TargetObject.PSObject.Properties['OtherName'];
-
-    if ($otherName -eq $Null) {
-        return $Null
-    }
-
-    return $otherName.Value;
-}
-
-# Specify the binding function script block code to execute
-$option = New-PSRuleOption -BindTargetName $bindFn;
-```
-
-Creates an options object that uses a custom function to bind the _TargetName_ of an object.
-
-### Example 4
-
 ```powershell
 $option = New-PSRuleOption -Configuration @{ 'appServiceMinInstanceCount' = 2 };
 ```
@@ -221,23 +199,6 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -BindTargetName
-
-Configures a custom function to use to bind TargetName of an object.
-See about_PSRule_Options for more information.
-
-```yaml
-Type: BindTargetName[]
-Parameter Sets: (All)
-Aliases:
-
-Required: False
-Position: Named
-Default value: None
-Accept pipeline input: False
-Accept wildcard characters: False
-```
-
 ### -Configuration
 
 Configures a set of baseline configuration values that can be used in rule definitions instead of using hard coded values.
@@ -274,23 +235,6 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -BindTargetType
-
-Configures a custom function to use to bind TargetType of an object.
-See about_PSRule_Options for more information.
-
-```yaml
-Type: BindTargetName[]
-Parameter Sets: (All)
-Aliases:
-
-Required: False
-Position: Named
-Default value: None
-Accept pipeline input: False
-Accept wildcard characters: False
-```
-
 ### -BindingIgnoreCase
 
 Sets the option `Binding.IgnoreCase`.

docs/deprecations.md

@@ -106,6 +106,13 @@ This existed to support scenarios before a module configuration and language sco
 
 Configuring binding configuration on a baseline is removed from PSRule v3.
 
+### Binding hooks
+
+Prior to v3, a custom binding PowerShell script block could be used to perform custom binding inline.
+This feature was hard to use and obsolete for most common use cases.
+
+Alternatively, configure `Binding.TargetName` and `Binding.TargetType` options to use the built-in binder.
+
 ## Deprecations for v2
 
 ### Default baseline by module manifest

src/PSRule/Configuration/PSRuleOption.cs

@@ -58,7 +58,6 @@ public PSRuleOption()
         Input = new InputOption();
         Logging = new LoggingOption();
         Output = new OutputOption();
-        Pipeline = new PipelineHook();
         Repository = new RepositoryOption();
         Requires = new RequiresOption();
         Rule = new RuleOption();
@@ -79,7 +78,6 @@ private PSRuleOption(string sourcePath, PSRuleOption option)
         Input = new InputOption(option?.Input);
         Logging = new LoggingOption(option?.Logging);
         Output = new OutputOption(option?.Output);
-        Pipeline = new PipelineHook(option?.Pipeline);
         Repository = new RepositoryOption(option?.Repository);
         Requires = new RequiresOption(option?.Requires);
         Rule = new RuleOption(option?.Rule);
@@ -131,13 +129,6 @@ private PSRuleOption(string sourcePath, PSRuleOption option)
     /// </summary>
     public OutputOption Output { get; set; }
 
-    /// <summary>
-    /// Configures pipeline hooks.
-    /// </summary>
-    [YamlIgnore]
-    [JsonIgnore]
-    public PipelineHook Pipeline { get; set; }
-
     /// <summary>
     /// Options for repository properties that are used by PSRule.
     /// </summary>
@@ -438,7 +429,6 @@ public bool Equals(PSRuleOption other)
             Logging == other.Logging &&
             Output == other.Output &&
             Suppression == other.Suppression &&
-            Pipeline == other.Pipeline &&
             Repository == other.Repository &&
             Rule == other.Rule;
     }
@@ -459,7 +449,6 @@ public override int GetHashCode()
             hash = hash * 23 + (Logging != null ? Logging.GetHashCode() : 0);
             hash = hash * 23 + (Output != null ? Output.GetHashCode() : 0);
             hash = hash * 23 + (Suppression != null ? Suppression.GetHashCode() : 0);
-            hash = hash * 23 + (Pipeline != null ? Pipeline.GetHashCode() : 0);
             hash = hash * 23 + (Repository != null ? Repository.GetHashCode() : 0);
             hash = hash * 23 + (Rule != null ? Rule.GetHashCode() : 0);
             return hash;

src/PSRule/Configuration/PipelineHook.cs

@@ -10,38 +10,3 @@ namespace PSRule.Configuration;
 
 internal delegate string BindTargetMethod(string[] propertyNames, bool caseSensitive, bool preferTargetInfo, object targetObject, out string path);
 internal delegate string BindTargetFunc(string[] propertyNames, bool caseSensitive, bool preferTargetInfo, object targetObject, BindTargetMethod next, out string path);
-
-/// <summary>
-/// Hooks that provide customize pipeline execution.
-/// </summary>
-public sealed class PipelineHook
-{
-    /// <summary>
-    /// Create an empty set of pipeline hooks.
-    /// </summary>
-    public PipelineHook()
-    {
-        BindTargetName = new List<BindTargetName>();
-        BindTargetType = new List<BindTargetName>();
-    }
-
-    /// <summary>
-    /// Create pipeline hooks based on an existing option instance.
-    /// </summary>
-    /// <param name="option">An existing pipeline hook option.</param>
-    public PipelineHook(PipelineHook option)
-    {
-        BindTargetName = option?.BindTargetName ?? new List<BindTargetName>();
-        BindTargetType = option?.BindTargetType ?? new List<BindTargetName>();
-    }
-
-    /// <summary>
-    /// One or more custom functions to use to bind TargetName of a pipeline object.
-    /// </summary>
-    public List<BindTargetName> BindTargetName { get; set; }
-
-    /// <summary>
-    /// One or more custom functions to use to bind TargetType of a pipeline object.
-    /// </summary>
-    public List<BindTargetName> BindTargetType { get; set; }
-}

src/PSRule/PSRule.psm1

@@ -1116,12 +1116,6 @@ function New-PSRuleOption {
         [Parameter(Mandatory = $False)]
         [PSRule.Configuration.SuppressionOption]$SuppressTargetName,
 
-        [Parameter(Mandatory = $False)]
-        [PSRule.Configuration.BindTargetName[]]$BindTargetName,
-
-        [Parameter(Mandatory = $False)]
-        [PSRule.Configuration.BindTargetName[]]$BindTargetType,
-
         # Options
 
         # Sets the Baseline.Group option
@@ -1371,12 +1365,6 @@ function New-PSRuleOption {
         if ($optionParams.ContainsKey('SuppressTargetName')) {
             $optionParams.Remove('SuppressTargetName');
         }
-        if ($optionParams.ContainsKey('BindTargetName')) {
-            $optionParams.Remove('BindTargetName');
-        }
-        if ($optionParams.ContainsKey('BindTargetType')) {
-            $optionParams.Remove('BindTargetType');
-        }
         if ($PSBoundParameters.ContainsKey('Option')) {
             $Option = [PSRule.Configuration.PSRuleOption]::FromFileOrEmpty($Option, $Path);
         }
@@ -1400,14 +1388,6 @@ function New-PSRuleOption {
         if ($PSBoundParameters.ContainsKey('SuppressTargetName')) {
             $Option.Suppression = $SuppressTargetName;
         }
-        if ($PSBoundParameters.ContainsKey('BindTargetName')) {
-            Write-Verbose -Message 'Set BindTargetName pipeline hook';
-            $Option.Pipeline.BindTargetName.AddRange($BindTargetName);
-        }
-        if ($PSBoundParameters.ContainsKey('BindTargetType')) {
-            Write-Verbose -Message 'Set BindTargetType pipeline hook';
-            $Option.Pipeline.BindTargetType.AddRange($BindTargetType);
-        }
 
         # Options
         $Option | SetOptions @optionParams -Verbose:$VerbosePreference;

src/PSRule/Pipeline/AssertPipelineBuilder.cs

@@ -201,10 +201,7 @@ public sealed override IPipeline Build(IPipelineWriter writer = null)
         return !RequireModules() || !RequireSources()
             ? null
             : (IPipeline)new InvokeRulePipeline(
-                context: PrepareContext(
-                    bindTargetName: BindTargetNameHook,
-                    bindTargetType: BindTargetTypeHook,
-                    bindField: BindFieldHook),
+                context: PrepareContext(PipelineHookActions.Default),
                 source: Source,
                 writer: HandleJobSummary(writer ?? PrepareWriter()),
                 outcome: RuleOutcome.Processed);

src/PSRule/Pipeline/ExportBaselinePipelineBuilder.cs

@@ -43,11 +43,7 @@ public override IPipeline Build(IPipelineWriter writer = null)
     {
         var filter = new BaselineFilter(_Name);
         return new GetBaselinePipeline(
-            pipeline: PrepareContext(
-                bindTargetName: null,
-                bindTargetType: null,
-                bindField: null
-            ),
+            pipeline: PrepareContext(PipelineHookActions.Empty),
             source: Source,
             reader: PrepareReader(),
             writer: writer ?? PrepareWriter(),

src/PSRule/Pipeline/GetBaselinePipelineBuilder.cs

@@ -41,11 +41,7 @@ public override IPipeline Build(IPipelineWriter writer = null)
     {
         var filter = new BaselineFilter(ResolveBaselineGroup(_Name));
         return new GetBaselinePipeline(
-            pipeline: PrepareContext(
-                bindTargetName: null,
-                bindTargetType: null,
-                bindField: null
-            ),
+            pipeline: PrepareContext(PipelineHookActions.Empty),
             source: Source,
             reader: PrepareReader(),
             writer: writer ?? PrepareWriter(),

src/PSRule/Pipeline/GetRuleHelpPipeline.cs

@@ -50,10 +50,7 @@ public void Online()
     public override IPipeline Build(IPipelineWriter writer = null)
     {
         return new GetRuleHelpPipeline(
-            pipeline: PrepareContext(
-                bindTargetName: null,
-                bindTargetType: null,
-                bindField: null),
+            pipeline: PrepareContext(PipelineHookActions.Empty),
             source: Source,
             reader: PrepareReader(),
             writer: writer ?? PrepareWriter());

src/PSRule/Pipeline/GetRulePipelineBuilder.cs

@@ -45,11 +45,7 @@ public override IPipeline Build(IPipelineWriter writer = null)
         return !RequireModules() || !RequireSources()
             ? null
             : (IPipeline)new GetRulePipeline(
-                pipeline: PrepareContext(
-                    bindTargetName: null,
-                    bindTargetType: null,
-                    bindField: null
-                ),
+                pipeline: PrepareContext(PipelineHookActions.Empty),
                 source: Source,
                 reader: PrepareReader(),
                 writer: writer ?? PrepareWriter(),

src/PSRule/Pipeline/GetTargetPipelineBuilder.cs

@@ -57,7 +57,7 @@ public void InputPath(string[] path)
     /// <inheritdoc/>
     public override IPipeline Build(IPipelineWriter writer = null)
     {
-        return new GetTargetPipeline(PrepareContext(null, null, null), PrepareReader(), writer ?? PrepareWriter());
+        return new GetTargetPipeline(PrepareContext(PipelineHookActions.Empty), PrepareReader(), writer ?? PrepareWriter());
     }
 
     /// <inheritdoc/>

src/PSRule/Pipeline/InvokePipelineBuilderBase.cs

@@ -4,10 +4,12 @@
 using PSRule.Configuration;
 using PSRule.Definitions;
 using PSRule.Host;
-using PSRule.Options;
 
 namespace PSRule.Pipeline;
 
+/// <summary>
+/// A pipeline builder for any pipelines that test objects against rules.
+/// </summary>
 internal abstract class InvokePipelineBuilderBase : PipelineBuilderBase, IInvokePipelineBuilder
 {
     protected InputPathBuilder _InputPath;
@@ -91,7 +93,7 @@ public override IPipeline Build(IPipelineWriter writer = null)
         Unblock(writer);
         return !RequireModules() || !RequireSources()
             ? null
-            : (IPipeline)new InvokeRulePipeline(PrepareContext(BindTargetNameHook, BindTargetTypeHook, BindFieldHook), Source, writer, Option.Output.Outcome.Value);
+            : (IPipeline)new InvokeRulePipeline(PrepareContext(PipelineHookActions.Default), Source, writer, Option.Output.Outcome.Value);
     }
 
     protected void Unblock(IPipelineWriter writer)