Add registration of custom emitters #2681

docs/CHANGELOG-v3.md

@@ -29,6 +29,9 @@ See [upgrade notes][1] for helpful information when upgrading from previous vers
 
 What's changed since pre-release v3.0.0-B0351:
 
+- General improvements:
+  - Added support for registering custom emitters by @BernieWhite.
+    [#2681](https://github.com/microsoft/PSRule/issues/2681)
 - Engineering:
   - Migrate samples into PSRule repository by @BernieWhite.
     [#2614](https://github.com/microsoft/PSRule/issues/2614)

docs/concepts/emitters.md

@@ -28,7 +28,11 @@ Name              | Default file extensions      | Configurable
 
 ## Custom emitters
 
-Custom emitters are a planned feature in PSRule v3.
+Custom emitters can be created by implementing the `PSRule.Emitters.IEmitter` interface available in `Microsoft.PSRule.Types`.
+This custom type implementation will be loaded by PSRule and used to process the input object.
+
+To use a custom emitter, it must be registered with PSRule as a service.
+This can be done by a convention within the `-Initialize` script block.
 
 ## Configuring formats
 

src/PSRule.Types/Emitters/IEmitter.cs

@@ -11,23 +11,16 @@ public interface IEmitter : IDisposable
     /// <summary>
     /// Visit an object and emit any input objects for processing.
     /// </summary>
-    /// <param name="context">A context object for the emitter.</param>
+    /// <param name="context">The current context for the emitter.</param>
     /// <param name="o">The object to visit.</param>
     /// <returns>Returns <c>true</c> when the emitter processed the object and <c>false</c> when it did not.</returns>
     bool Visit(IEmitterContext context, object o);
 
     /// <summary>
     /// Determines if the emitter accepts the specified object type.
     /// </summary>
-    /// <param name="context"></param>
-    /// <param name="type"></param>
-    /// <returns></returns>
+    /// <param name="context">The current context for the emitter.</param>
+    /// <param name="type">The type of object.</param>
+    /// <returns>Returns <c>true</c> if the emitter supports processing the object type and <c>false</c> if it does not.</returns>
     bool Accepts(IEmitterContext context, Type type);
-
-    ///// <summary>
-    ///// Configure the emitter using an options instance.
-    ///// </summary>
-    ///// <param name="option"></param>
-    ///// <returns></returns>
-    //bool Configure(PSRuleOption option);
 }

src/PSRule.Types/Runtime/IRuntimeServiceCollection.cs

@@ -0,0 +1,36 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace PSRule.Runtime;
+
+/// <summary>
+/// A context for registering scoped runtime services within a factory.
+/// </summary>
+public interface IRuntimeServiceCollection : IDisposable
+{
+    /// <summary>
+    /// The name of the scope.
+    /// </summary>
+    string ScopeName { get; }
+
+    /// <summary>
+    /// Access configuration values at runtime.
+    /// </summary>
+    IConfiguration Configuration { get; }
+
+    /// <summary>
+    /// Add a service.
+    /// </summary>
+    /// <typeparam name="TInterface">The specified interface type.</typeparam>
+    /// <typeparam name="TService">The concrete type to add.</typeparam>
+    void AddService<TInterface, TService>()
+        where TInterface : class
+        where TService : class, TInterface;
+
+    /// <summary>
+    /// Add a service.
+    /// </summary>
+    /// <param name="instanceName">A unique name of the service instance.</param>
+    /// <param name="instance">An instance of the service.</param>
+    void AddService(string instanceName, object instance);
+}

src/PSRule/Common/JsonConverters.cs

@@ -11,8 +11,8 @@
 using PSRule.Definitions;
 using PSRule.Definitions.Baselines;
 using PSRule.Definitions.Expressions;
+using PSRule.Emitters;
 using PSRule.Pipeline;
-using PSRule.Pipeline.Emitters;
 using PSRule.Resources;
 using PSRule.Runtime;
 

src/PSRule/Common/YamlConverters.cs

@@ -10,15 +10,16 @@
 using PSRule.Data;
 using PSRule.Definitions;
 using PSRule.Definitions.Expressions;
+using PSRule.Emitters;
 using PSRule.Host;
 using PSRule.Pipeline;
-using PSRule.Pipeline.Emitters;
 using YamlDotNet.Core;
 using YamlDotNet.Core.Events;
 using YamlDotNet.Serialization;
 using YamlDotNet.Serialization.NamingConventions;
 using YamlDotNet.Serialization.TypeInspectors;
 using YamlDotNet.Serialization.TypeResolvers;
+using IEmitter = YamlDotNet.Core.IEmitter;
 
 namespace PSRule;
 

src/PSRule/Pipeline/Emitters/BaseEmitterContext.cs → src/PSRule/Emitters/BaseEmitterContext.cs

@@ -4,11 +4,11 @@
 using System.Collections;
 using System.Management.Automation;
 using PSRule.Data;
-using PSRule.Emitters;
 using PSRule.Options;
+using PSRule.Pipeline;
 using PSRule.Runtime;
 
-namespace PSRule.Pipeline.Emitters;
+namespace PSRule.Emitters;
 
 /// <summary>
 /// 
@@ -45,7 +45,7 @@ public void Emit(ITargetObject value)
 
     protected abstract void Enqueue(ITargetObject value);
 
-    private static IEnumerable<ITargetObject> ReadObjectPath(ITargetObject targetObject, string objectPath, bool caseSensitive)
+    private static ITargetObject[] ReadObjectPath(ITargetObject targetObject, string objectPath, bool caseSensitive)
     {
         if (!ObjectHelper.GetPath(
             bindingContext: null,
@@ -59,10 +59,10 @@ private static IEnumerable<ITargetObject> ReadObjectPath(ITargetObject targetObj
         if (typeof(IEnumerable).IsAssignableFrom(nestedType))
         {
             var result = new List<TargetObject>();
-            foreach (var item in (nestedObject as IEnumerable))
+            foreach (var item in nestedObject as IEnumerable)
                 result.Add(new TargetObject(PSObject.AsPSObject(item)));
 
-            return result.ToArray();
+            return [.. result];
         }
         else
         {

src/PSRule/Pipeline/Emitters/EmitterBuilder.cs → src/PSRule/Emitters/EmitterBuilder.cs

@@ -3,11 +3,10 @@
 
 using Microsoft.Extensions.DependencyInjection;
 using PSRule.Definitions;
-using PSRule.Emitters;
 using PSRule.Options;
 using PSRule.Runtime;
 
-namespace PSRule.Pipeline.Emitters;
+namespace PSRule.Emitters;
 
 #nullable enable
 
@@ -29,6 +28,7 @@ public EmitterBuilder(ILanguageScopeSet? languageScopeSet = default, IFormatOpti
         _Services = new ServiceCollection();
         AddInternalServices();
         AddInternalEmitters();
+        AddEmittersFromLanguageScope();
     }
 
     /// <summary>
@@ -45,6 +45,20 @@ public void AddEmitter<T>(string scope) where T : class, IEmitter
         _Services.AddScoped(typeof(T));
     }
 
+    /// <summary>
+    /// Add an <see cref="IEmitter"/> implementation class.
+    /// </summary>
+    /// <param name="scope">The scope of the emitter.</param>
+    /// <param name="type">An emitter type that implements <see cref="IEmitter"/>.</param>
+    /// <exception cref="ArgumentNullException">The <paramref name="scope"/> parameter must not be a null or empty string.</exception>
+    public void AddEmitter(string scope, Type type)
+    {
+        if (string.IsNullOrEmpty(scope)) throw new ArgumentNullException(nameof(scope));
+
+        _EmitterTypes.Add(new KeyValuePair<string, Type>(scope, type));
+        _Services.AddScoped(type);
+    }
+
     /// <summary>
     /// Add an existing emitter instance that is already configured.
     /// </summary>
@@ -118,6 +132,22 @@ private void AddInternalEmitters()
         AddEmitter<PowerShellDataEmitter>(ResourceHelper.STANDALONE_SCOPE_NAME);
     }
 
+    /// <summary>
+    /// Add custom emitters from the language scope.
+    /// </summary>
+    private void AddEmittersFromLanguageScope()
+    {
+        if (_LanguageScopeSet == null) return;
+
+        foreach (var scope in _LanguageScopeSet.Get())
+        {
+            foreach (var emitterType in scope.GetEmitters())
+            {
+                AddEmitter(scope.Name, emitterType);
+            }
+        }
+    }
+
     /// <summary>
     /// Create a configuration for the emitter based on it's scope.
     /// </summary>

src/PSRule/Pipeline/Emitters/EmitterChain.cs → src/PSRule/Emitters/EmitterChain.cs

@@ -1,9 +1,11 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-using PSRule.Emitters;
 
-namespace PSRule.Pipeline.Emitters;
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace PSRule.Emitters;
 
 /// <summary>
 /// A chain of emitters.

src/PSRule/Pipeline/Emitters/EmitterCollection.cs → src/PSRule/Emitters/EmitterCollection.cs

@@ -4,9 +4,9 @@
 using System.Management.Automation;
 using Microsoft.Extensions.DependencyInjection;
 using PSRule.Data;
-using PSRule.Emitters;
+using PSRule.Pipeline;
 
-namespace PSRule.Pipeline.Emitters;
+namespace PSRule.Emitters;
 
 #nullable enable
 

src/PSRule/Pipeline/Emitters/EmitterContext.cs → src/PSRule/Emitters/EmitterContext.cs

@@ -4,10 +4,10 @@
 using System.Collections.Concurrent;
 using PSRule.Configuration;
 using PSRule.Data;
-using PSRule.Emitters;
 using PSRule.Options;
+using PSRule.Pipeline;
 
-namespace PSRule.Pipeline.Emitters;
+namespace PSRule.Emitters;
 
 #nullable enable
 

src/PSRule/Pipeline/Emitters/InternalEmitterConfiguration.cs → src/PSRule/Emitters/InternalEmitterConfiguration.cs

@@ -1,11 +1,10 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-using PSRule.Emitters;
 using PSRule.Options;
 using PSRule.Runtime;
 
-namespace PSRule.Pipeline.Emitters;
+namespace PSRule.Emitters;
 
 #nullable enable
 

src/PSRule/Pipeline/Emitters/InternalFileInfo.cs → src/PSRule/Emitters/InternalFileInfo.cs

@@ -4,7 +4,7 @@
 using System.Diagnostics;
 using PSRule.Data;
 
-namespace PSRule.Pipeline.Emitters;
+namespace PSRule.Emitters;
 
 [DebuggerDisplay("{Path}")]
 internal sealed class InternalFileInfo : IFileInfo, IDisposable

src/PSRule/Pipeline/Emitters/InternalFileStream.cs → src/PSRule/Emitters/InternalFileStream.cs

@@ -4,7 +4,7 @@
 using System.Text;
 using PSRule.Data;
 
-namespace PSRule.Pipeline.Emitters;
+namespace PSRule.Emitters;
 
 internal sealed class InternalFileStream : IFileStream
 {

src/PSRule/Pipeline/Emitters/JsonEmitter.cs → src/PSRule/Emitters/JsonEmitter.cs

@@ -5,10 +5,10 @@
 using System.Management.Automation;
 using Newtonsoft.Json;
 using PSRule.Data;
-using PSRule.Emitters;
+using PSRule.Pipeline;
 using PSRule.Runtime;
 
-namespace PSRule.Pipeline.Emitters;
+namespace PSRule.Emitters;
 
 /// <summary>
 /// An <seealso cref="IEmitter"/> for processing JSON.

src/PSRule/Pipeline/Emitters/JsonEmitterParser.cs → src/PSRule/Emitters/JsonEmitterParser.cs

@@ -4,7 +4,7 @@
 using Newtonsoft.Json;
 using PSRule.Data;
 
-namespace PSRule.Pipeline.Emitters;
+namespace PSRule.Emitters;
 
 internal sealed class JsonEmitterParser : JsonTextReader
 {

src/PSRule/Pipeline/Emitters/MarkdownEmitter.cs → src/PSRule/Emitters/MarkdownEmitter.cs

@@ -4,10 +4,10 @@
 using System.Collections.Immutable;
 using System.Management.Automation;
 using PSRule.Data;
-using PSRule.Emitters;
 using PSRule.Help;
+using PSRule.Pipeline;
 
-namespace PSRule.Pipeline.Emitters;
+namespace PSRule.Emitters;
 
 /// <summary>
 /// An <seealso cref="IEmitter"/> for processing Markdown.

src/PSRule/Pipeline/Emitters/PowerShellDataEmitter.cs → src/PSRule/Emitters/PowerShellDataEmitter.cs

@@ -4,9 +4,9 @@
 using System.Collections.Immutable;
 using System.Management.Automation;
 using PSRule.Data;
-using PSRule.Emitters;
+using PSRule.Pipeline;
 
-namespace PSRule.Pipeline.Emitters;
+namespace PSRule.Emitters;
 
 /// <summary>
 /// An <seealso cref="IEmitter"/> for processing PowerShell Data.

src/PSRule/Pipeline/Emitters/YamlEmitter.cs → src/PSRule/Emitters/YamlEmitter.cs

@@ -4,17 +4,17 @@
 using System.Collections.Immutable;
 using PSRule.Data;
 using PSRule.Definitions;
-using PSRule.Emitters;
+using PSRule.Pipeline;
 using PSRule.Runtime;
 using YamlDotNet.Core;
 using YamlDotNet.Core.Events;
 using YamlDotNet.Serialization;
 using YamlDotNet.Serialization.NodeDeserializers;
 
-namespace PSRule.Pipeline.Emitters;
+namespace PSRule.Emitters;
 
 /// <summary>
-/// An <seealso cref="PSRule.Emitters.IEmitter"/> for processing YAML.
+/// An <seealso cref="IEmitter"/> for processing YAML.
 /// </summary>
 internal sealed class YamlEmitter : FileEmitter
 {

src/PSRule/Pipeline/Emitters/YamlEmitterParser.cs → src/PSRule/Emitters/YamlEmitterParser.cs

@@ -4,7 +4,7 @@
 using PSRule.Data;
 using YamlDotNet.Core;
 
-namespace PSRule.Pipeline.Emitters;
+namespace PSRule.Emitters;
 
 /// <summary>
 /// A custom parser that implements source mapping.

src/PSRule/Pipeline/AssertPipelineBuilder.cs

@@ -201,9 +201,8 @@ public sealed override IPipeline Build(IPipelineWriter writer = null)
         return !RequireModules() || !RequireSources()
             ? null
             : (IPipeline)new InvokeRulePipeline(
-                context: PrepareContext(PipelineHookActions.Default),
+                context: PrepareContext(PipelineHookActions.Default, writer: HandleJobSummary(writer ?? PrepareWriter())),
                 source: Source,
-                writer: HandleJobSummary(writer ?? PrepareWriter()),
                 outcome: RuleOutcome.Processed);
     }
 

src/PSRule/Pipeline/ExportBaselinePipelineBuilder.cs

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