InitialSessionState.cs

/********************************************************************++
Copyright (c) Microsoft Corporation.  All rights reserved.
--********************************************************************/

using System.Collections;
using System.Collections.Concurrent;
using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.Diagnostics.CodeAnalysis;
using System.Diagnostics.Tracing;
using System.IO;
using System.Linq;
using System.Management.Automation.Internal;
using System.Management.Automation.Provider;
using System.Management.Automation.Language;
using System.Reflection;
using System.Threading;
using Microsoft.PowerShell.Commands;
using Debug = System.Management.Automation.Diagnostics;
using System.Management.Automation.Host;
using System.Text;
using System.Threading.Tasks;

namespace System.Management.Automation.Runspaces
{
    internal class EarlyStartup
    {
        internal static void Init()
        {
            // Code added here should:
            //   * run every time we start PowerSHell
            //   * have high CPU cost
            //   * be ordered from most expensive to least expensive, or at least needed earliest
            //   * this method should return quickly, so all work should be run in one or more tasks.
            //   * code called from here should correctly handle being called twice, in case initialization
            //     is needed in the main code path before the task completes.
            //
            // Code added here should not:
            //   * count on running - not all hosts will call this method
            //   * have high disk cost

            // We shouldn't create too many tasks.

            // This task takes awhile, so it gets it's own task
            Task.Run(() =>
            {
                // Building the catalog is expensive, so force that to happen early on a background thread, and do so
                // on a file we are very likely to read anyway.
                var pshome = Utils.DefaultPowerShellAppBase;
                var unused = SecuritySupport.IsProductBinary(Path.Combine(pshome, "Modules", "Microsoft.PowerShell.Utility", "Microsoft.PowerShell.Utility.psm1"));
            });

            // One other task for other stuff that's faster, but still a little slow.
            Task.Run(() =>
            {
                // Loading the resources for System.Management.Automation can be expensive, so force that to
                // happen early on a background thread.
                var unused0 = RunspaceInit.OutputEncodingDescription;

                // Amsi initialize can also be a little slow
                if (Platform.IsWindows)
                {
                    AmsiUtils.Init();
                }

                // This will init some tables and could load some assemblies.
                var unused1 = TypeAccelerators.builtinTypeAccelerators;

                // This will init some tables and could load some assemblies.
                var unused2 = LanguagePrimitives.GetEnumerator(null);
            });
        }
    }

    /// <summary>
    /// Baseclass for defining elements that can be added
    /// to an InitialSessionState object.
    /// </summary>
    public abstract class InitialSessionStateEntry
    {
        /// <summary>
        /// ctor so that each derived class has a name
        /// </summary>
        /// <param name="name"></param>
        protected InitialSessionStateEntry(string name)
        {
            Name = name;
        }

        /// <summary>
        /// The name of this entry
        /// </summary>
        public string Name { get; internal set; }

        /// <summary>
        /// The SnapIn to load from initially
        /// </summary>
        public PSSnapInInfo PSSnapIn { get; private set; }

        internal void SetPSSnapIn(PSSnapInInfo psSnapIn)
        {
            PSSnapIn = psSnapIn;
        }

        /// <summary>
        /// The SnapIn to load from initially
        /// </summary>
        public PSModuleInfo Module { get; private set; }

        internal void SetModule(PSModuleInfo module)
        {
            Module = module;
        }

        /// <summary>
        /// Shallow-clone this object
        /// </summary>
        /// <returns>The cloned object...</returns>
        public abstract InitialSessionStateEntry Clone();
    }

    /// <summary>
    /// Class to constrain session state entries
    /// </summary>
    public abstract class ConstrainedSessionStateEntry : InitialSessionStateEntry
    {
        /// <summary>
        ///
        /// </summary>
        /// <param name="name"></param>
        /// <param name="visibility"></param>
        protected ConstrainedSessionStateEntry(string name, SessionStateEntryVisibility visibility)
            : base(name)
        {
            Visibility = visibility;
        }

        /// <summary>
        ///
        /// </summary>
        public SessionStateEntryVisibility Visibility { get; set; }
    }


    /// <summary>
    /// Command class so that all the commands can derive off this one.
    /// Adds the flexibility of adding additional derived class,
    /// such as ProxyCommand for Exchange.
    /// Derived classes - Alias, Application, Cmdlet, Function, Script.
    /// </summary>
    public abstract class SessionStateCommandEntry : ConstrainedSessionStateEntry
    {
        /// <summary>
        /// Base constructor for all SessionState commands.
        /// </summary>
        /// <param name="name"></param>
        protected SessionStateCommandEntry(string name)
            : base(name, SessionStateEntryVisibility.Public)
        {
        }

        /// <summary>
        ///
        /// </summary>
        /// <param name="name"></param>
        /// <param name="visibility"></param>
        protected internal SessionStateCommandEntry(string name, SessionStateEntryVisibility visibility)
            : base(name, visibility)
        {
        }

        /// <summary>
        /// Returns the type of the command using an enum
        /// instead of requiring a full reflection type check.
        /// </summary>
        public CommandTypes CommandType { get; internal set; }

        /// <summary>
        /// Is internal so it can be set by the engine code...
        /// This is used to specify whether this command was imported or not
        /// If noClobber is specified during Import-Module, it is set to false
        /// </summary>
        internal bool _isImported = true;
    }

    /// <summary>
    /// Type file configuration entry...
    /// </summary>
    public sealed class SessionStateTypeEntry : InitialSessionStateEntry
    {
        /// <summary>
        /// Loads all entries from the types file.
        /// </summary>
        /// <param name="fileName"></param>
        public SessionStateTypeEntry(string fileName)
            : base(fileName)
        {
            if (String.IsNullOrEmpty(fileName) || fileName.Trim().Length == 0)
            {
                throw PSTraceSource.NewArgumentException("fileName");
            }

            FileName = fileName.Trim();
        }

        /// <summary>
        /// Loads all the types specified in the typeTable
        /// </summary>
        /// <param name="typeTable"></param>
        public SessionStateTypeEntry(TypeTable typeTable)
            : base("*")
        {
            if (typeTable == null)
            {
                throw PSTraceSource.NewArgumentNullException("typeTable");
            }
            TypeTable = typeTable;
        }

        /// <summary>
        /// Loads all entries from the typeData
        /// </summary>
        /// <param name="typeData"></param>
        /// <param name="isRemove"></param>
        public SessionStateTypeEntry(TypeData typeData, bool isRemove)
            : base("*")
        {
            if (typeData == null)
            {
                throw PSTraceSource.NewArgumentNullException("typeData");
            }
            TypeData = typeData;
            IsRemove = isRemove;
        }

        /// <summary>
        /// Shallow-clone this object
        /// </summary>
        /// <returns>The cloned object</returns>
        public override InitialSessionStateEntry Clone()
        {
            SessionStateTypeEntry entry;
            if (FileName != null)
            {
                entry = new SessionStateTypeEntry(FileName);
            }
            else if (TypeTable != null)
            {
                entry = new SessionStateTypeEntry(TypeTable);
            }
            else
            {
                entry = new SessionStateTypeEntry(TypeData, IsRemove);
            }

            entry.SetPSSnapIn(this.PSSnapIn);
            entry.SetModule(this.Module);
            return entry;
        }

        /// <summary>
        /// The pathname of the types.ps1xml file. This can be null if
        /// TypeTable constructor or TypeData constructor is used.
        /// </summary>
        public string FileName { get; }

        /// <summary>
        /// The TypeTable specified with constructor. This can be null if
        /// FileName constructor or TypeData constructor is used.
        /// </summary>
        public TypeTable TypeTable { get; }

        /// <summary>
        /// The TypeData we want to update with. This can be null if
        /// FileName constructor or TypeTable constructor is used.
        /// </summary>
        public TypeData TypeData { get; }

        /// <summary>
        /// The operation will be done on the typedata. This is only
        /// meaningful when the TypeData constructor is used.
        /// </summary>
        public bool IsRemove { get; }

        //So that we can specify the type information on the fly,
        //without using Types.ps1xml file
        //public SessionStateTypeEntry(string name, xmlreader definition);
        //public string Definition { get; }
    }

    /// <summary>
    /// Format file configuration entry...
    /// </summary>
    public sealed class SessionStateFormatEntry : InitialSessionStateEntry
    {
        /// <summary>
        /// Loads the entire formats file
        /// </summary>
        /// <param name="fileName"></param>
        public SessionStateFormatEntry(string fileName)
            : base("*")
        {
            if (String.IsNullOrEmpty(fileName) || fileName.Trim().Length == 0)
            {
                throw PSTraceSource.NewArgumentException("fileName");
            }

            FileName = fileName.Trim();
        }

        /// <summary>
        /// Loads all the format data specified in the formatTable
        /// </summary>
        /// <param name="formattable"></param>
        public SessionStateFormatEntry(FormatTable formattable)
            : base("*")
        {
            if (formattable == null)
            {
                throw PSTraceSource.NewArgumentNullException("formattable");
            }
            Formattable = formattable;
        }

        /// <summary>
        /// Loads all the format data specified in the typeDefinition
        /// </summary>
        /// <param name="typeDefinition"></param>
        public SessionStateFormatEntry(ExtendedTypeDefinition typeDefinition)
            : base("*")
        {
            if (typeDefinition == null)
            {
                throw PSTraceSource.NewArgumentNullException("typeDefinition");
            }
            FormatData = typeDefinition;
        }

        /// <summary>
        /// Shallow-clone this object...
        /// </summary>
        /// <returns>The cloned object</returns>
        public override InitialSessionStateEntry Clone()
        {
            SessionStateFormatEntry entry;

            if (FileName != null)
            {
                entry = new SessionStateFormatEntry(FileName);
            }
            else if (Formattable != null)
            {
                entry = new SessionStateFormatEntry(Formattable);
            }
            else
            {
                entry = new SessionStateFormatEntry(FormatData);
            }

            entry.SetPSSnapIn(this.PSSnapIn);
            entry.SetModule(this.Module);
            return entry;
        }

        /// <summary>
        /// The name of the format file referenced by this entry...
        /// </summary>
        public string FileName { get; }

        /// <summary>
        /// The FormatTable specified with constructor. This can be null if
        /// FileName constructor is used.
        /// </summary>
        public FormatTable Formattable { get; }

        /// <summary>
        /// The FormatData specified with constructor. This can be null if
        /// FileName or FormatTable constructor is used
        /// </summary>
        public ExtendedTypeDefinition FormatData { get; }

        //So that we can specify the format information on the fly,
        //without using Format.ps1xml file
        //public SessionStateFormatEntry(string name, xmlreader definition);
        //public string Definition { get; }
    }

    /// <summary>
    /// An assembly to load for this sessionstate...
    /// </summary>
    public sealed class SessionStateAssemblyEntry : InitialSessionStateEntry
    {
        /// <summary>
        /// Create a named entry for the assembly to load with both the
        /// name and the path to the assembly as a backup.
        /// </summary>
        /// <param name="name">The name of the assembly to load</param>
        /// <param name="fileName">The path to the assembly to use as an alternative</param>
        public SessionStateAssemblyEntry(string name, string fileName)
            : base(name)
        {
            FileName = fileName;
        }

        /// <summary>
        /// Create a named entry for the assembly to load, specifying
        /// just the name
        /// </summary>
        /// <param name="name">The name of the assembly to load</param>
        public SessionStateAssemblyEntry(string name)
            : base(name)
        {
            ;
        }

        /// <summary>
        /// Shallow-clone this object
        /// </summary>
        /// <returns>The cloned object</returns>
        public override InitialSessionStateEntry Clone()
        {
            SessionStateAssemblyEntry entry = new SessionStateAssemblyEntry(Name, FileName);
            entry.SetPSSnapIn(this.PSSnapIn);
            entry.SetModule(this.Module);
            return entry;
        }

        /// <summary>
        /// Return the assembly file name...
        /// </summary>
        public string FileName { get; }
    }

    /// <summary>
    /// List a cmdlet to add to this session state entry
    /// </summary>
    public sealed class SessionStateCmdletEntry : SessionStateCommandEntry
    {
        /// <summary>
        ///
        /// </summary>
        /// <param name="name"></param>
        /// <param name="implementingType"></param>
        /// <param name="helpFileName"></param>
        public SessionStateCmdletEntry(string name, Type implementingType, string helpFileName)
            : base(name, SessionStateEntryVisibility.Public)
        {
            ImplementingType = implementingType;
            HelpFileName = helpFileName;
            CommandType = CommandTypes.Cmdlet;
        }


        /// <summary>
        ///
        /// </summary>
        /// <param name="name"></param>
        /// <param name="implementingType"></param>
        /// <param name="helpFileName"></param>
        /// <param name="visibility"></param>
        internal SessionStateCmdletEntry(string name, Type implementingType, string helpFileName, SessionStateEntryVisibility visibility)
            : base(name, visibility)
        {
            ImplementingType = implementingType;
            HelpFileName = helpFileName;
            CommandType = CommandTypes.Cmdlet;
        }

        /// <summary>
        /// Shallow-clone this object...
        /// </summary>
        /// <returns></returns>
        public override InitialSessionStateEntry Clone()
        {
            SessionStateCmdletEntry entry = new SessionStateCmdletEntry(Name, ImplementingType, HelpFileName, Visibility);
            entry.SetPSSnapIn(this.PSSnapIn);
            entry.SetModule(this.Module);
            return entry;
        }

        /// <summary>
        ///
        /// </summary>
        public Type ImplementingType { get; }

        /// <summary>
        ///
        /// </summary>
        public string HelpFileName { get; }
    }

    /// <summary>
    ///
    /// </summary>
    public sealed class SessionStateProviderEntry : ConstrainedSessionStateEntry
    {
        /// <summary>
        ///
        /// </summary>
        /// <param name="name"></param>
        /// <param name="implementingType"></param>
        /// <param name="helpFileName"></param>
        public SessionStateProviderEntry(string name, Type implementingType, string helpFileName)
            : base(name, SessionStateEntryVisibility.Public)
        {
            ImplementingType = implementingType;
            HelpFileName = helpFileName;
        }

        internal SessionStateProviderEntry(string name, Type implementingType, string helpFileName, SessionStateEntryVisibility visibility)
            : base(name, visibility)
        {
            ImplementingType = implementingType;
            HelpFileName = helpFileName;
        }


        /// <summary>
        /// Shallow-clone this object...
        /// </summary>
        /// <returns>The cloned object</returns>
        public override InitialSessionStateEntry Clone()
        {
            SessionStateProviderEntry entry = new SessionStateProviderEntry(Name, ImplementingType, HelpFileName, this.Visibility);
            entry.SetPSSnapIn(this.PSSnapIn);
            entry.SetModule(this.Module);
            return entry;
        }

        /// <summary>
        ///
        /// </summary>
        public Type ImplementingType { get; }

        /// <summary>
        ///
        /// </summary>
        public string HelpFileName { get; }
    }

    /// <summary>
    ///
    /// </summary>
    public sealed class SessionStateScriptEntry : SessionStateCommandEntry
    {
        /// <summary>
        /// Create a session state command entry instance.
        /// </summary>
        /// <param name="path">The path to the script</param>
        public SessionStateScriptEntry(string path)
            : base(path, SessionStateEntryVisibility.Public)
        {
            Path = path;
            CommandType = CommandTypes.ExternalScript;
        }

        /// <summary>
        /// Create a session state command entry instance with the specified visibility.
        /// </summary>
        /// <param name="path">The path to the script</param>
        /// <param name="visibility">Visibility of the script.</param>
        internal SessionStateScriptEntry(string path, SessionStateEntryVisibility visibility)
            : base(path, visibility)
        {
            Path = path;
            CommandType = CommandTypes.ExternalScript;
        }

        /// <summary>
        /// Shallow-clone this object...
        /// </summary>
        /// <returns>The cloned object</returns>
        public override InitialSessionStateEntry Clone()
        {
            SessionStateScriptEntry entry = new SessionStateScriptEntry(Path, Visibility);
            entry.SetModule(this.Module);
            return entry;
        }

        /// <summary>
        ///
        /// </summary>
        public string Path { get; }
    }

    /// <summary>
    ///
    /// </summary>
    public sealed class SessionStateAliasEntry : SessionStateCommandEntry
    {
        /// <summary>
        ///  Define an alias entry to add to the initial session state
        /// </summary>
        /// <param name="name">Name of the alias</param>
        /// <param name="definition">The name of the command it resolves to</param>
        public SessionStateAliasEntry(string name, string definition)
            : base(name, SessionStateEntryVisibility.Public)
        {
            Definition = definition;
            CommandType = CommandTypes.Alias;
        }

        /// <summary>
        ///  Define an alias entry to add to the initial session state
        /// </summary>
        /// <param name="name">Name of the alias</param>
        /// <param name="definition">The name of the command it resolves to</param>
        /// <param name="description">A description of the purpose of the alias.</param>
        public SessionStateAliasEntry(string name, string definition, string description)
            : base(name, SessionStateEntryVisibility.Public)
        {
            Definition = definition;
            CommandType = CommandTypes.Alias;
            Description = description;
        }

        /// <summary>
        ///  Define an alias entry to add to the initial session state
        /// </summary>
        /// <param name="name">Name of the alias</param>
        /// <param name="definition">The name of the command it resolves to</param>
        /// <param name="description">A description of the purpose of the alias.</param>
        /// <param name="options">Options defining the scope visibility, readonly and constant</param>
        public SessionStateAliasEntry(string name, string definition, string description, ScopedItemOptions options)
            : base(name, SessionStateEntryVisibility.Public)
        {
            Definition = definition;
            CommandType = CommandTypes.Alias;
            Description = description;
            Options = options;
        }

        /// <summary>
        ///  Define an alias entry to add to the initial session state
        /// </summary>
        /// <param name="name">Name of the alias</param>
        /// <param name="definition">The name of the command it resolves to</param>
        /// <param name="description">A description of the purpose of the alias.</param>
        /// <param name="options">Options defining the scope visibility, readonly and constant</param>
        /// <param name="visibility"></param>
        internal SessionStateAliasEntry(string name, string definition, string description,
            ScopedItemOptions options, SessionStateEntryVisibility visibility)
            : base(name, visibility)
        {
            Definition = definition;
            CommandType = CommandTypes.Alias;
            Description = description;
            Options = options;
        }
        /// <summary>
        /// Shallow-clone this object...
        /// </summary>
        /// <returns>The cloned object</returns>
        public override InitialSessionStateEntry Clone()
        {
            SessionStateAliasEntry entry = new SessionStateAliasEntry(Name, Definition, Description, Options, Visibility);
            entry.SetModule(this.Module);
            return entry;
        }

        /// <summary>
        /// The string defining the body of this alias...
        /// </summary>
        public string Definition { get; }

        /// <summary>
        /// A string describing this alias...
        /// </summary>
        public string Description { get; } = String.Empty;

        /// <summary>
        /// Options controling scope visibility and setability for this entry.
        /// </summary>
        public ScopedItemOptions Options { get; } = ScopedItemOptions.None;
    }

    /// <summary>
    ///
    /// </summary>
    public sealed class SessionStateApplicationEntry : SessionStateCommandEntry
    {
        /// <summary>
        /// Used to define a permitted script in this session state. If the path is
        /// "*", then any path is permitted.
        /// </summary>
        /// <param name="path">The full path to the application</param>
        public SessionStateApplicationEntry(string path)
            : base(path, SessionStateEntryVisibility.Public)
        {
            Path = path;
            CommandType = CommandTypes.Application;
        }

        /// <summary>
        /// Used to define a permitted script in this session state. If the path is
        /// "*", then any path is permitted.
        /// </summary>
        /// <param name="path">The full path to the application</param>
        /// <param name="visibility">Sets the external visibility of the path.</param>
        internal SessionStateApplicationEntry(string path, SessionStateEntryVisibility visibility)
            : base(path, visibility)
        {
            Path = path;
            CommandType = CommandTypes.Application;
        }

        /// <summary>
        /// Shallow-clone this object...
        /// </summary>
        /// <returns>The cloned object</returns>
        public override InitialSessionStateEntry Clone()
        {
            SessionStateApplicationEntry entry = new SessionStateApplicationEntry(Path, Visibility);
            entry.SetModule(this.Module);
            return entry;
        }

        /// <summary>
        /// The path to this application...
        /// </summary>
        public string Path { get; }
    }

    /// <summary>
    ///
    /// </summary>
    public sealed class SessionStateFunctionEntry : SessionStateCommandEntry
    {
        /// <summary>
        /// Represents a function definition in an Initial session state object.
        /// </summary>
        /// <param name="name">The name of the function</param>
        /// <param name="definition">The definition of the function</param>
        /// <param name="options">Options controlling scope-related elements of this object</param>
        /// <param name="helpFile">The name of the help file associated with the function</param>
        public SessionStateFunctionEntry(string name, string definition, ScopedItemOptions options, string helpFile)
            : base(name, SessionStateEntryVisibility.Public)
        {
            Definition = definition;
            CommandType = CommandTypes.Function;
            Options = options;
            ScriptBlock = ScriptBlock.Create(Definition);
            ScriptBlock.LanguageMode = PSLanguageMode.FullLanguage;

            HelpFile = helpFile;
        }

        /// <summary>
        /// Represents a function definition in an Initial session state object.
        /// </summary>
        /// <param name="name">The name of the function</param>
        /// <param name="definition">The definition of the function</param>
        /// <param name="helpFile">The name of the help file associated with the function</param>
        public SessionStateFunctionEntry(string name, string definition, string helpFile)
            : this(name, definition, ScopedItemOptions.None, helpFile)
        {
        }

        /// <summary>
        /// Represents a function definition in an Initial session state object.
        /// </summary>
        /// <param name="name">The name of the function</param>
        /// <param name="definition">The definition of the function</param>
        public SessionStateFunctionEntry(string name, string definition)
            : this(name, definition, ScopedItemOptions.None, null)
        {
        }

        /// <summary>
        /// This is an internal copy constructor.
        /// </summary>
        internal SessionStateFunctionEntry(string name, string definition, ScopedItemOptions options,
            SessionStateEntryVisibility visibility, ScriptBlock scriptBlock, string helpFile)
            : base(name, visibility)
        {
            Definition = definition;
            CommandType = CommandTypes.Function;
            Options = options;
            ScriptBlock = scriptBlock;
            HelpFile = helpFile;
        }

        internal static SessionStateFunctionEntry GetDelayParsedFunctionEntry(string name, string definition, bool isProductCode)
        {
            var sb = ScriptBlock.CreateDelayParsedScriptBlock(definition, isProductCode);
            return new SessionStateFunctionEntry(name, definition, ScopedItemOptions.None,
                SessionStateEntryVisibility.Public, sb, null);
        }

        internal static SessionStateFunctionEntry GetDelayParsedFunctionEntry(string name, string definition, ScriptBlock sb)
        {
            return new SessionStateFunctionEntry(name, definition, ScopedItemOptions.None,
                SessionStateEntryVisibility.Public, sb, null);
        }

        /// <summary>
        /// Shallow-clone this object...
        /// </summary>
        /// <returns>The cloned object</returns>
        public override InitialSessionStateEntry Clone()
        {
            SessionStateFunctionEntry entry = new SessionStateFunctionEntry(Name, Definition, Options, Visibility, ScriptBlock, HelpFile);
            entry.SetModule(this.Module);
            return entry;
        }

        /// <summary>
        /// Sets the name of the help file associated with the function.
        /// </summary>
        internal void SetHelpFile(string help)
        {
            HelpFile = help;
        }

        /// <summary>
        /// The string to use to define this function...
        /// </summary>
        public string Definition { get; }

        /// <summary>
        /// The script block for this function.
        /// </summary>
        internal ScriptBlock ScriptBlock { get; set; }

        /// <summary>
        /// Options controling scope visibility and setability for this entry.
        /// </summary>
        public ScopedItemOptions Options { get; } = ScopedItemOptions.None;

        /// <summary>
        /// The name of the help file associated with the function.
        /// </summary>
        public string HelpFile { get; private set; }
    }

    /// <summary>
    ///
    /// </summary>
    public sealed class SessionStateVariableEntry : ConstrainedSessionStateEntry
    {
        /// <summary>
        /// Is used to define a variable that should be created when
        /// the runspace is opened. Note - if this object is cloned,
        /// then the clone will contain a reference to the original object
        /// not a clone of it.
        /// </summary>
        /// <param name="name">The name of the variable</param>
        /// <param name="value">The value to set the variable to</param>
        /// <param name="description">A descriptive string to attach to the variable.</param>
        public SessionStateVariableEntry(string name, object value, string description)
            : base(name, SessionStateEntryVisibility.Public)
        {
            Value = value;
            Description = description;
        }

        /// <summary>
        /// Is used to define a variable that should be created when
        /// the runspace is opened. Note - if this object is cloned,
        /// then the clone will contain a reference to the original object
        /// not a clone of it.
        /// </summary>
        /// <param name="name">The name of the variable</param>
        /// <param name="value">The value to set the variable to</param>
        /// <param name="description">A descriptive string to attach to the variable.</param>
        /// <param name="options">Options like readonly, constant, allscope, etc.</param>
        public SessionStateVariableEntry(string name, object value, string description, ScopedItemOptions options)
            : base(name, SessionStateEntryVisibility.Public)
        {
            Value = value;
            Description = description;
            Options = options;
        }

        /// <summary>
        /// Is used to define a variable that should be created when
        /// the runspace is opened. Note - if this object is cloned,
        /// then the clone will contain a reference to the original object
        /// not a clone of it.
        /// </summary>
        /// <param name="name">The name of the variable</param>
        /// <param name="value">The value to set the variable to</param>
        /// <param name="description">A descriptive string to attach to the variable.</param>
        /// <param name="options">Options like readonly, constant, allscope, etc.</param>
        /// <param name="attributes">A list of attributes to attach to the variable.</param>
        public SessionStateVariableEntry(string name, object value, string description,
            ScopedItemOptions options, Collection<Attribute> attributes)
            : base(name, SessionStateEntryVisibility.Public)
        {
            Value = value;
            Description = description;
            Options = options;
            _attributes = attributes;
        }

        /// <summary>
        /// Is used to define a variable that should be created when
        /// the runspace is opened. Note - if this object is cloned,
        /// then the clone will contain a reference to the original object
        /// not a clone of it.
        /// </summary>
        /// <param name="name">The name of the variable</param>
        /// <param name="value">The value to set the variable to</param>
        /// <param name="description">A descriptive string to attach to the variable.</param>
        /// <param name="options">Options like readonly, constant, allscope, etc.</param>
        /// <param name="attribute">A single attribute to attach to the variable.</param>
        public SessionStateVariableEntry(string name, object value, string description,
            ScopedItemOptions options, Attribute attribute)
            : base(name, SessionStateEntryVisibility.Public)
        {
            Value = value;
            Description = description;
            Options = options;
            _attributes = new Collection<Attribute>();
            _attributes.Add(attribute);
        }

        /// <summary>
        /// Is used to define a variable that should be created when
        /// the runspace is opened. Note - if this object is cloned,
        /// then the clone will contain a reference to the original object
        /// not a clone of it.
        /// </summary>
        /// <param name="name">The name of the variable</param>
        /// <param name="value">The value to set the variable to</param>
        /// <param name="description">A descriptive string to attach to the variable.</param>
        /// <param name="options">Options like readonly, constant, allscope, etc.</param>
        /// <param name="attributes">A single attribute to attach to the variable.</param>
        /// <param name="visibility"></param>
        internal SessionStateVariableEntry(string name, object value, string description,
            ScopedItemOptions options, Collection<Attribute> attributes, SessionStateEntryVisibility visibility)
            : base(name, visibility)
        {
            Value = value;
            Description = description;
            Options = options;
            _attributes = attributes;
        }

        /// <summary>
        /// Shallow-clone this object...
        /// </summary>
        /// <returns>The cloned object</returns>
        public override InitialSessionStateEntry Clone()
        {
            // Copy the attribute collection if necessary...
            Collection<Attribute> attrs = null;
            if (_attributes != null && _attributes.Count > 0)
                attrs = new Collection<Attribute>(_attributes);
            return new SessionStateVariableEntry(Name, Value, Description, Options, attrs, Visibility);
        }

        /// <summary>
        /// The value to bind to this variable.
        /// </summary>
        public object Value { get; }

        /// <summary>
        /// The description associated with this variable.
        /// </summary>
        public string Description { get; } = String.Empty;

        /// <summary>
        /// The options associated with this variable (e.g. readonly, allscope, etc.)
        /// </summary>
        public ScopedItemOptions Options { get; } = ScopedItemOptions.None;

        /// <summary>
        /// The attributes that will be attached to this object.
        /// </summary>
        public Collection<Attribute> Attributes
        {
            get { return _attributes ?? (_attributes = new Collection<Attribute>()); }
        }
        private Collection<Attribute> _attributes;
    }


    /// <summary>
    ///
    /// </summary>
    /// <typeparam name="T"></typeparam>
    public sealed class InitialSessionStateEntryCollection<T> : IEnumerable<T> where T : InitialSessionStateEntry
    {
        /// <summary>
        /// Create an empty collection...
        /// </summary>
        public InitialSessionStateEntryCollection()
        {
            _internalCollection = new Collection<T>();
        }

        /// <summary>
        /// Create an new collection, copying in the passed items...
        /// </summary>
        /// <param name="items"></param>
        public InitialSessionStateEntryCollection(IEnumerable<T> items)
        {
            if (items == null)
            {