CoreAdapter.cs

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.

using System.Collections.Concurrent;
using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.ComponentModel;
using System.Data;
using System.Diagnostics;
using System.Diagnostics.CodeAnalysis;
using System.Dynamic;
using System.Globalization;
using System.Linq;
using System.Linq.Expressions;
using System.Management.Automation.Language;
using System.Management.Automation.Runspaces;
using System.Reflection;
using System.Reflection.Emit;
using System.Text;
using System.Threading;
using System.Xml;

using System.Management.Automation.Internal;
using Microsoft.PowerShell;
using Dbg = System.Management.Automation.Diagnostics;

#pragma warning disable 1634, 1691 // Stops compiler from warning about unknown warnings

namespace System.Management.Automation
{
    /// <summary>
    /// Base class for all Adapters
    /// This is the place to look every time you create a new Adapter. Consider if you
    /// should implement each of the virtual methods here.
    /// The base class deals with errors and performs additional operations before and after
    /// calling the derived virtual methods.
    /// </summary>
    internal abstract class Adapter
    {
        /// <summary>
        /// Tracer for this and derivate classes.
        /// </summary>
        [TraceSource("ETS", "Extended Type System")]
        protected static PSTraceSource tracer = PSTraceSource.GetTracer("ETS", "Extended Type System");
        #region virtual

        #region member

        internal virtual bool CanSiteBinderOptimize(MemberTypes typeToOperateOn) { return false; }

        protected static IEnumerable<string> GetDotNetTypeNameHierarchy(Type type)
        {
            for (; type != null; type = type.BaseType)
            {
                yield return type.FullName;
            }
        }

        protected static IEnumerable<string> GetDotNetTypeNameHierarchy(object obj)
        {
            return GetDotNetTypeNameHierarchy(obj.GetType());
        }

        /// <summary>
        /// Returns the TypeNameHierarchy out of an object.
        /// </summary>
        /// <param name="obj">Object to get the TypeNameHierarchy from.</param>
        protected virtual IEnumerable<string> GetTypeNameHierarchy(object obj)
        {
            return GetDotNetTypeNameHierarchy(obj);
        }

        /// <summary>
        /// Returns the cached typename, if it can be cached, otherwise constructs a new typename.
        /// By default, we don't return interned values, adapters can override if they choose.
        /// </summary>
        /// <param name="obj">Object to get the TypeNameHierarchy from.</param>
        protected virtual ConsolidatedString GetInternedTypeNameHierarchy(object obj)
        {
            return new ConsolidatedString(GetTypeNameHierarchy(obj));
        }

        /// <summary>
        /// Returns null if memberName is not a member in the adapter or
        /// the corresponding PSMemberInfo.
        /// </summary>
        /// <param name="obj">Object to retrieve the PSMemberInfo from.</param>
        /// <param name="memberName">Name of the member to be retrieved.</param>
        /// <returns>The PSMemberInfo corresponding to memberName from obj.</returns>
        protected abstract T GetMember<T>(object obj, string memberName) where T : PSMemberInfo;

        /// <summary>
        /// Returns the first PSMemberInfo whose name matches the specified <see cref="MemberNamePredicate"/>.
        /// Otherwise, return null.
        /// </summary>
        /// <param name="obj">Object to retrieve the PSMemberInfo from.</param>
        /// <param name="predicate">The predicate to find the matching member.</param>
        /// <returns>The PSMemberInfo corresponding to the predicate match.</returns>
        protected abstract T GetFirstMemberOrDefault<T>(object obj, MemberNamePredicate predicate) where T : PSMemberInfo;

        /// <summary>
        /// Retrieves all the members available in the object.
        /// The adapter implementation is encouraged to cache all properties/methods available
        /// in the first call to GetMember and GetMembers so that subsequent
        /// calls can use the cache.
        /// In the case of the .NET adapter that would be a cache from the .NET type to
        /// the public properties and fields available in that type.
        /// In the case of the DirectoryEntry adapter, this could be a cache of the objectClass
        /// to the properties available in it.
        /// </summary>
        /// <param name="obj">Object to get all the member information from.</param>
        /// <returns>All members in obj.</returns>
        protected abstract PSMemberInfoInternalCollection<T> GetMembers<T>(object obj) where T : PSMemberInfo;

        #endregion member

        #region property

        /// <summary>
        /// Returns the value from a property coming from a previous call to GetMember.
        /// </summary>
        /// <param name="property">PSProperty coming from a previous call to GetMember.</param>
        /// <returns>The value of the property.</returns>
        protected abstract object PropertyGet(PSProperty property);

        /// <summary>
        /// Sets the value of a property coming from a previous call to GetMember.
        /// </summary>
        /// <param name="property">PSProperty coming from a previous call to GetMember.</param>
        /// <param name="setValue">Value to set the property with.</param>
        /// <param name="convertIfPossible">Instructs the adapter to convert before setting, if the adapter supports conversion.</param>
        protected abstract void PropertySet(PSProperty property, object setValue, bool convertIfPossible);

        /// <summary>
        /// Returns true if the property is settable.
        /// </summary>
        /// <param name="property">Property to check.</param>
        /// <returns>True if the property is settable.</returns>
        protected abstract bool PropertyIsSettable(PSProperty property);

        /// <summary>
        /// Returns true if the property is gettable.
        /// </summary>
        /// <param name="property">Property to check.</param>
        /// <returns>True if the property is gettable.</returns>
        protected abstract bool PropertyIsGettable(PSProperty property);

        /// <summary>
        /// Returns the name of the type corresponding to the property's value.
        /// </summary>
        /// <param name="property">PSProperty obtained in a previous GetMember.</param>
        /// <param name="forDisplay">True if the result is for display purposes only.</param>
        /// <returns>The name of the type corresponding to the member.</returns>
        protected abstract string PropertyType(PSProperty property, bool forDisplay);

        /// <summary>
        /// Returns the string representation of the property in the object.
        /// </summary>
        /// <param name="property">Property obtained in a previous GetMember.</param>
        /// <returns>The string representation of the property in the object.</returns>
        protected abstract string PropertyToString(PSProperty property);

        /// <summary>
        /// Returns an array with the property attributes.
        /// </summary>
        /// <param name="property">Property we want the attributes from.</param>
        /// <returns>An array with the property attributes.</returns>
        protected abstract AttributeCollection PropertyAttributes(PSProperty property);

        #endregion property

        #region method

        /// <summary>
        /// Called after a non null return from GetMember to try to call
        /// the method with the arguments.
        /// </summary>
        /// <param name="method">The non empty return from GetMethods.</param>
        /// <param name="invocationConstraints">Invocation constraints.</param>
        /// <param name="arguments">The arguments to use.</param>
        /// <returns>The return value for the method.</returns>
        protected virtual object MethodInvoke(PSMethod method, PSMethodInvocationConstraints invocationConstraints, object[] arguments)
        {
            return this.MethodInvoke(method, arguments);
        }

        /// <summary>
        /// Called after a non null return from GetMember to try to call
        /// the method with the arguments.
        /// </summary>
        /// <param name="method">The non empty return from GetMethods.</param>
        /// <param name="arguments">The arguments to use.</param>
        /// <returns>The return value for the method.</returns>
        protected abstract object MethodInvoke(PSMethod method, object[] arguments);

        /// <summary>
        /// Called after a non null return from GetMember to return the overloads.
        /// </summary>
        /// <param name="method">The return of GetMember.</param>
        /// <returns></returns>
        protected abstract Collection<string> MethodDefinitions(PSMethod method);

        /// <summary>
        /// Returns the string representation of the method in the object.
        /// </summary>
        /// <returns>The string representation of the method in the object.</returns>
        protected virtual string MethodToString(PSMethod method)
        {
            StringBuilder returnValue = new StringBuilder();
            Collection<string> definitions = MethodDefinitions(method);
            for (int i = 0; i < definitions.Count; i++)
            {
                returnValue.Append(definitions[i]);
                returnValue.Append(", ");
            }

            returnValue.Remove(returnValue.Length - 2, 2);
            return returnValue.ToString();
        }

        #endregion method

        #region parameterized property

        /// <summary>
        /// Returns the name of the type corresponding to the property's value.
        /// </summary>
        /// <param name="property">Property obtained in a previous GetMember.</param>
        /// <returns>The name of the type corresponding to the member.</returns>
        /// <remarks>
        /// It is not necessary for derived methods to override this.
        /// This method is called only if ParameterizedProperties are present.
        /// </remarks>
        protected virtual string ParameterizedPropertyType(PSParameterizedProperty property)
        {
            Diagnostics.Assert(false, "adapter is not called for parameterized properties");
            throw PSTraceSource.NewNotSupportedException();
        }

        /// <summary>
        /// Returns true if the property is settable.
        /// </summary>
        /// <param name="property">Property to check.</param>
        /// <returns>True if the property is settable.</returns>
        /// <remarks>
        /// It is not necessary for derived methods to override this.
        /// This method is called only if ParameterizedProperties are present.
        /// </remarks>
        protected virtual bool ParameterizedPropertyIsSettable(PSParameterizedProperty property)
        {
            Diagnostics.Assert(false, "adapter is not called for parameterized properties");
            throw PSTraceSource.NewNotSupportedException();
        }

        /// <summary>
        /// Returns true if the property is gettable.
        /// </summary>
        /// <param name="property">Property to check.</param>
        /// <returns>True if the property is gettable.</returns>
        /// <remarks>
        /// It is not necessary for derived methods to override this.
        /// This method is called only if ParameterizedProperties are present.
        /// </remarks>
        protected virtual bool ParameterizedPropertyIsGettable(PSParameterizedProperty property)
        {
            Diagnostics.Assert(false, "adapter is not called for parameterized properties");
            throw PSTraceSource.NewNotSupportedException();
        }

        /// <summary>
        /// Called after a non null return from GetMember to return the overloads.
        /// </summary>
        /// <param name="property">The return of GetMember.</param>
        /// <remarks>
        /// It is not necessary for derived methods to override this.
        /// This method is called only if ParameterizedProperties are present.
        /// </remarks>
        protected virtual Collection<string> ParameterizedPropertyDefinitions(PSParameterizedProperty property)
        {
            Diagnostics.Assert(false, "adapter is not called for parameterized properties");
            throw PSTraceSource.NewNotSupportedException();
        }

        /// <summary>
        /// Called after a non null return from GetMember to get the property value.
        /// </summary>
        /// <param name="property">The non empty return from GetMember.</param>
        /// <param name="arguments">The arguments to use.</param>
        /// <returns>The return value for the property.</returns>
        /// <remarks>
        /// It is not necessary for derived methods to override this.
        /// This method is called only if ParameterizedProperties are present.
        /// </remarks>
        protected virtual object ParameterizedPropertyGet(PSParameterizedProperty property, object[] arguments)
        {
            Diagnostics.Assert(false, "adapter is not called for parameterized properties");
            throw PSTraceSource.NewNotSupportedException();
        }

        /// <summary>
        /// Called after a non null return from GetMember to set the property value.
        /// </summary>
        /// <param name="property">The non empty return from GetMember.</param>
        /// <param name="setValue">The value to set property with.</param>
        /// <param name="arguments">The arguments to use.</param>
        /// <remarks>
        /// It is not necessary for derived methods to override this.
        /// This method is called only if ParameterizedProperties are present.
        /// </remarks>
        protected virtual void ParameterizedPropertySet(PSParameterizedProperty property, object setValue, object[] arguments)
        {
            Diagnostics.Assert(false, "adapter is not called for parameterized properties");
            throw PSTraceSource.NewNotSupportedException();
        }

        /// <summary>
        /// Returns the string representation of the property in the object.
        /// </summary>
        /// <param name="property">Property obtained in a previous GetMember.</param>
        /// <returns>The string representation of the property in the object.</returns>
        /// <remarks>
        /// It is not necessary for derived methods to override this.
        /// This method is called only if ParameterizedProperties are present.
        /// </remarks>
        protected virtual string ParameterizedPropertyToString(PSParameterizedProperty property)
        {
            Diagnostics.Assert(false, "adapter is not called for parameterized properties");
            throw PSTraceSource.NewNotSupportedException();
        }

        #endregion parameterized property

        #endregion virtual

        #region base

        #region private

        private static Exception NewException(
            Exception e,
            string errorId,
            string targetErrorId,
            string resourceString,
            params object[] parameters)
        {
            object[] newParameters = new object[parameters.Length + 1];
            for (int i = 0; i < parameters.Length; i++)
            {
                newParameters[i + 1] = parameters[i];
            }

            Exception ex = e as TargetInvocationException;
            if (ex != null)
            {
                Exception inner = ex.InnerException ?? ex;
                newParameters[0] = inner.Message;
                return new ExtendedTypeSystemException(
                    targetErrorId,
                    inner,
                    resourceString,
                    newParameters);
            }

            newParameters[0] = e.Message;
            return new ExtendedTypeSystemException(
                errorId,
                e,
                resourceString,
                newParameters);
        }

        #endregion private

        #region member

        internal ConsolidatedString BaseGetTypeNameHierarchy(object obj)
        {
            try
            {
                return GetInternedTypeNameHierarchy(obj);
            }
            catch (ExtendedTypeSystemException) { throw; }
            catch (Exception e)
            {
                throw NewException(
                    e,
                    "CatchFromBaseGetTypeNameHierarchy",
                    "CatchFromBaseGetTypeNameHierarchyTI",
                    ExtendedTypeSystem.ExceptionRetrievingTypeNameHierarchy);
            }
        }

        internal T BaseGetMember<T>(object obj, string memberName) where T : PSMemberInfo
        {
            try
            {
                return this.GetMember<T>(obj, memberName);
            }
            catch (ExtendedTypeSystemException) { throw; }
            catch (Exception e)
            {
                throw NewException(
                    e,
                    "CatchFromBaseGetMember",
                    "CatchFromBaseGetMemberTI",
                    ExtendedTypeSystem.ExceptionGettingMember,
                    memberName);
            }
        }

        internal T BaseGetFirstMemberOrDefault<T>(object obj, MemberNamePredicate predicate) where T : PSMemberInfo
        {
            try
            {
                return this.GetFirstMemberOrDefault<T>(obj, predicate);
            }
            catch (ExtendedTypeSystemException) { throw; }
            catch (Exception e)
            {
                throw NewException(
                    e,
                    "CatchFromBaseGetMember",
                    "CatchFromBaseGetMemberTI",
                    ExtendedTypeSystem.ExceptionGettingMember,
                    nameof(predicate));
            }
        }

        internal PSMemberInfoInternalCollection<T> BaseGetMembers<T>(object obj) where T : PSMemberInfo
        {
            try
            {
                return this.GetMembers<T>(obj);
            }
            catch (ExtendedTypeSystemException) { throw; }
            catch (Exception e)
            {
                throw NewException(
                    e,
                    "CatchFromBaseGetMembers",
                    "CatchFromBaseGetMembersTI",
                    ExtendedTypeSystem.ExceptionGettingMembers);
            }
        }

        #endregion member

        #region property

        internal object BasePropertyGet(PSProperty property)
        {
            try
            {
                return PropertyGet(property);
            }
            catch (TargetInvocationException ex)
            {
                Exception inner = ex.InnerException ?? ex;
                throw new GetValueInvocationException(
                    "CatchFromBaseAdapterGetValueTI",
                    inner,
                    ExtendedTypeSystem.ExceptionWhenGetting,
                    property.Name, inner.Message);
            }
            catch (GetValueException) { throw; }
            catch (Exception e)
            {
                throw new GetValueInvocationException(
                    "CatchFromBaseAdapterGetValue",
                    e,
                    ExtendedTypeSystem.ExceptionWhenGetting,
                    property.Name, e.Message);
            }
        }

        internal void BasePropertySet(PSProperty property, object setValue, bool convert)
        {
            try
            {
                PropertySet(property, setValue, convert);
            }
            catch (TargetInvocationException ex)
            {
                Exception inner = ex.InnerException ?? ex;
                throw new SetValueInvocationException(
                    "CatchFromBaseAdapterSetValueTI",
                    inner,
                    ExtendedTypeSystem.ExceptionWhenSetting,
                    property.Name, inner.Message);
            }
            catch (SetValueException) { throw; }
            catch (Exception e)
            {
                throw new SetValueInvocationException(
                    "CatchFromBaseAdapterSetValue",
                    e,
                    ExtendedTypeSystem.ExceptionWhenSetting,
                    property.Name, e.Message);
            }
        }

        internal bool BasePropertyIsSettable(PSProperty property)
        {
            try
            {
                return this.PropertyIsSettable(property);
            }
            catch (ExtendedTypeSystemException) { throw; }
            catch (Exception e)
            {
                throw NewException(
                    e,
                    "CatchFromBasePropertyIsSettable",
                    "CatchFromBasePropertyIsSettableTI",
                    ExtendedTypeSystem.ExceptionRetrievingPropertyWriteState,
                    property.Name);
            }
        }

        internal bool BasePropertyIsGettable(PSProperty property)
        {
            try
            {
                return this.PropertyIsGettable(property);
            }
            catch (ExtendedTypeSystemException) { throw; }
            catch (Exception e)
            {
                throw NewException(
                    e,
                    "CatchFromBasePropertyIsGettable",
                    "CatchFromBasePropertyIsGettableTI",
                    ExtendedTypeSystem.ExceptionRetrievingPropertyReadState,
                    property.Name);
            }
        }

        internal string BasePropertyType(PSProperty property)
        {
            try
            {
                return this.PropertyType(property, forDisplay: false);
            }
            catch (ExtendedTypeSystemException) { throw; }
            catch (Exception e)
            {
                throw NewException(
                    e,
                    "CatchFromBasePropertyType",
                    "CatchFromBasePropertyTypeTI",
                    ExtendedTypeSystem.ExceptionRetrievingPropertyType,
                    property.Name);
            }
        }

        internal string BasePropertyToString(PSProperty property)
        {
            try
            {
                return this.PropertyToString(property);
            }
            catch (ExtendedTypeSystemException) { throw; }
            catch (Exception e)
            {
                throw NewException(
                    e,
                    "CatchFromBasePropertyToString",
                    "CatchFromBasePropertyToStringTI",
                    ExtendedTypeSystem.ExceptionRetrievingPropertyString,
                    property.Name);
            }
        }

        internal AttributeCollection BasePropertyAttributes(PSProperty property)
        {
            try
            {
                return this.PropertyAttributes(property);
            }
            catch (ExtendedTypeSystemException) { throw; }
            catch (Exception e)
            {
                throw NewException(
                    e,
                    "CatchFromBasePropertyAttributes",
                    "CatchFromBasePropertyAttributesTI",
                    ExtendedTypeSystem.ExceptionRetrievingPropertyAttributes,
                    property.Name);
            }
        }

        #endregion property

        #region method
        internal object BaseMethodInvoke(PSMethod method, PSMethodInvocationConstraints invocationConstraints, params object[] arguments)
        {
            try
            {
                return this.MethodInvoke(method, invocationConstraints, arguments);
            }
            catch (TargetInvocationException ex)
            {
                Exception inner = ex.InnerException ?? ex;
                throw new MethodInvocationException(
                    "CatchFromBaseAdapterMethodInvokeTI",
                    inner,
                    ExtendedTypeSystem.MethodInvocationException,
                    method.Name,
                    arguments.Length,
                    inner.Message);
            }
            catch (FlowControlException) { throw; }
            catch (ScriptCallDepthException) { throw; }
            catch (PipelineStoppedException) { throw; }
            catch (MethodException) { throw; }
            catch (Exception e)
            {
                if (method.baseObject is SteppablePipeline
                    && (method.Name.Equals("Begin", StringComparison.OrdinalIgnoreCase) ||
                        method.Name.Equals("Process", StringComparison.OrdinalIgnoreCase) ||
                        method.Name.Equals("End", StringComparison.OrdinalIgnoreCase)))
                {
                    throw;
                }

                throw new MethodInvocationException(
                    "CatchFromBaseAdapterMethodInvoke",
                    e,
                    ExtendedTypeSystem.MethodInvocationException,
                    method.Name,
                    arguments.Length,
                    e.Message);
            }
        }

        internal Collection<string> BaseMethodDefinitions(PSMethod method)
        {
            try
            {
                return this.MethodDefinitions(method);
            }
            catch (ExtendedTypeSystemException) { throw; }
            catch (Exception e)
            {
                throw NewException(
                    e,
                    "CatchFromBaseMethodDefinitions",
                    "CatchFromBaseMethodDefinitionsTI",
                    ExtendedTypeSystem.ExceptionRetrievingMethodDefinitions,
                    method.Name);
            }
        }

        internal string BaseMethodToString(PSMethod method)
        {
            try
            {
                return this.MethodToString(method);
            }
            catch (ExtendedTypeSystemException) { throw; }
            catch (Exception e)
            {
                throw NewException(
                    e,
                    "CatchFromBaseMethodToString",
                    "CatchFromBaseMethodToStringTI",
                    ExtendedTypeSystem.ExceptionRetrievingMethodString,
                    method.Name);
            }
        }
        #endregion method

        #region parameterized property
        internal string BaseParameterizedPropertyType(PSParameterizedProperty property)
        {
            try
            {
                return this.ParameterizedPropertyType(property);
            }
            catch (ExtendedTypeSystemException) { throw; }
            catch (Exception e)
            {
                throw NewException(
                    e,
                    "CatchFromBaseParameterizedPropertyType",
                    "CatchFromBaseParameterizedPropertyTypeTI",
                    ExtendedTypeSystem.ExceptionRetrievingParameterizedPropertytype,
                    property.Name);
            }
        }

        internal bool BaseParameterizedPropertyIsSettable(PSParameterizedProperty property)
        {
            try
            {
                return this.ParameterizedPropertyIsSettable(property);
            }
            catch (ExtendedTypeSystemException) { throw; }
            catch (Exception e)
            {
                throw NewException(
                    e,
                    "CatchFromBaseParameterizedPropertyIsSettable",
                    "CatchFromBaseParameterizedPropertyIsSettableTI",
                    ExtendedTypeSystem.ExceptionRetrievingParameterizedPropertyWriteState,
                    property.Name);
            }
        }

        internal bool BaseParameterizedPropertyIsGettable(PSParameterizedProperty property)
        {
            try
            {
                return this.ParameterizedPropertyIsGettable(property);
            }
            catch (ExtendedTypeSystemException) { throw; }
            catch (Exception e)
            {
                throw NewException(
                    e,
                    "CatchFromBaseParameterizedPropertyIsGettable",
                    "CatchFromBaseParameterizedPropertyIsGettableTI",
                    ExtendedTypeSystem.ExceptionRetrievingParameterizedPropertyReadState,
                    property.Name);
            }
        }

        internal Collection<string> BaseParameterizedPropertyDefinitions(PSParameterizedProperty property)
        {
            try
            {
                return this.ParameterizedPropertyDefinitions(property);
            }
            catch (ExtendedTypeSystemException) { throw; }
            catch (Exception e)
            {
                throw NewException(
                    e,
                    "CatchFromBaseParameterizedPropertyDefinitions",
                    "CatchFromBaseParameterizedPropertyDefinitionsTI",
                    ExtendedTypeSystem.ExceptionRetrievingParameterizedPropertyDefinitions,
                    property.Name);
            }
        }

        internal object BaseParameterizedPropertyGet(PSParameterizedProperty property, params object[] arguments)
        {
            try
            {
                return this.ParameterizedPropertyGet(property, arguments);
            }
            catch (TargetInvocationException ex)
            {
                Exception inner = ex.InnerException ?? ex;
                throw new GetValueInvocationException(
                    "CatchFromBaseAdapterParameterizedPropertyGetValueTI",
                    inner,
                    ExtendedTypeSystem.ExceptionWhenGetting,
                    property.Name,
                    inner.Message);
            }
            catch (GetValueException) { throw; }
            catch (Exception e)
            {
                throw new GetValueInvocationException(
                    "CatchFromBaseParameterizedPropertyAdapterGetValue",
                    e,
                    ExtendedTypeSystem.ExceptionWhenGetting,
                    property.Name,
                    e.Message);
            }
        }

        internal void BaseParameterizedPropertySet(PSParameterizedProperty property, object setValue, params object[] arguments)
        {
            try
            {
                this.ParameterizedPropertySet(property, setValue, arguments);
            }
            catch (TargetInvocationException ex)
            {
                Exception inner = ex.InnerException ?? ex;
                throw new SetValueInvocationException(
                    "CatchFromBaseAdapterParameterizedPropertySetValueTI",
                    inner,
                    ExtendedTypeSystem.ExceptionWhenSetting,
                    property.Name,
                    inner.Message);
            }
            catch (SetValueException) { throw; }
            catch (Exception e)
            {
                throw new SetValueInvocationException(
                    "CatchFromBaseAdapterParameterizedPropertySetValue",
                    e,
                    ExtendedTypeSystem.ExceptionWhenSetting,
                    property.Name,
                    e.Message);
            }
        }

        internal string BaseParameterizedPropertyToString(PSParameterizedProperty property)
        {
            try
            {
                return this.ParameterizedPropertyToString(property);
            }
            catch (ExtendedTypeSystemException) { throw; }
            catch (Exception e)
            {
                throw NewException(
                    e,
                    "CatchFromBaseParameterizedPropertyToString",
                    "CatchFromBaseParameterizedPropertyToStringTI",
                    ExtendedTypeSystem.ExceptionRetrievingParameterizedPropertyString,
                    property.Name);
            }
        }

        #endregion parameterized property

        #region Internal Helper Methods

        private static Type GetArgumentType(object argument, bool isByRefParameter)
        {
            if (argument == null)
            {
                return typeof(LanguagePrimitives.Null);
            }

            if (isByRefParameter && argument is PSReference psref)
            {
                return GetArgumentType(PSObject.Base(psref.Value), isByRefParameter: false);
            }

            return argument.GetType();
        }

        internal static ConversionRank GetArgumentConversionRank(object argument, Type parameterType, bool isByRef, bool allowCastingToByRefLikeType)
        {
            Type fromType = null;
            ConversionRank rank = ConversionRank.None;

            if (allowCastingToByRefLikeType && parameterType.IsByRefLike)
            {
                // When resolving best method for use in binders, we can accept implicit/explicit casting conversions to
                // a ByRef-like target type, because when generating IL from a call site with the binder, the IL includes
                // the casting operation. However, we don't accept such conversions when it's for invoking the method via
                // reflection, because reflection just doesn't support ByRef-like type.
                fromType = GetArgumentType(PSObject.Base(argument), isByRefParameter: false);
                if (fromType != typeof(LanguagePrimitives.Null))
                {
                    LanguagePrimitives.FigureCastConversion(fromType, parameterType, ref rank);
                }

                return rank;
            }

            fromType = GetArgumentType(argument, isByRef);
            rank = LanguagePrimitives.GetConversionRank(fromType, parameterType);

            if (rank == ConversionRank.None)
            {
                fromType = GetArgumentType(PSObject.Base(argument), isByRef);
                rank = LanguagePrimitives.GetConversionRank(fromType, parameterType);
            }

            return rank;
        }

        private static ParameterInformation[] ExpandParameters(int argCount, ParameterInformation[] parameters, Type elementType)
        {
            Diagnostics.Assert(parameters[parameters.Length - 1].isParamArray, "ExpandParameters shouldn't be called on non-param method");

            ParameterInformation[] newParameters = new ParameterInformation[argCount];
            Array.Copy(parameters, newParameters, parameters.Length - 1);
            for (int i = parameters.Length - 1; i < argCount; ++i)
            {
                newParameters[i] = new ParameterInformation(elementType, false, null, false);
            }

            return newParameters;
        }

        /// <summary>
        /// Compare the 2 methods, determining which method is better.
        /// </summary>
        /// <returns>1 if method1 is better, -1 if method2 is better, 0 otherwise.</returns>
        private static int CompareOverloadCandidates(OverloadCandidate candidate1, OverloadCandidate candidate2, object[] arguments)
        {
            Diagnostics.Assert(candidate1.conversionRanks.Length == candidate2.conversionRanks.Length,
                               "should have same number of conversions regardless of the number of parameters - default arguments are not included here");

            ParameterInformation[] params1 = candidate1.expandedParameters ?? candidate1.parameters;
            ParameterInformation[] params2 = candidate2.expandedParameters ?? candidate2.parameters;

            int betterCount = 0;
            int multiplier = candidate1.conversionRanks.Length;
            for (int i = 0; i < candidate1.conversionRanks.Length; ++i, --multiplier)
            {
                if (candidate1.conversionRanks[i] < candidate2.conversionRanks[i])
                {
                    betterCount -= multiplier;
                }
                else if (candidate1.conversionRanks[i] > candidate2.conversionRanks[i])
                {
                    betterCount += multiplier;
                }
                else if (candidate1.conversionRanks[i] == ConversionRank.UnrelatedArrays)
                {
                    // If both are unrelated arrays, then use the element type conversions instead.
                    Type argElemType = EffectiveArgumentType(arguments[i]).GetElementType();
                    ConversionRank rank1 = LanguagePrimitives.GetConversionRank(argElemType, params1[i].parameterType.GetElementType());
                    ConversionRank rank2 = LanguagePrimitives.GetConversionRank(argElemType, params2[i].parameterType.GetElementType());
                    if (rank1 < rank2)
                    {
                        betterCount -= multiplier;
                    }
                    else if (rank1 > rank2)
                    {
                        betterCount += multiplier;
                    }
                }
            }

            if (betterCount == 0)
            {
                multiplier = candidate1.conversionRanks.Length;
                for (int i = 0; i < candidate1.conversionRanks.Length; ++i, multiplier = Math.Abs(multiplier) - 1)
                {
                    // The following rather tricky logic tries to pick the best method in 2 very different cases -
                    //   - Pick the most specific method when conversions aren't losing information
                    //   - Pick the most general method when conversions will lose information.
                    // Consider:
                    //    f(uint32), f(decimal), call with f([byte]$i)
                    //        in this case, we want to call f(uint32) because it is more specific
                    //        while not losing information
                    //    f(byte), f(int16), call with f([int]$i)
                    //        in this case, we want to call f(int16) because it is more general,
                    //        we know we could lose information with either call, but we will lose
                    //        less information calling f(int16).
                    ConversionRank rank1 = candidate1.conversionRanks[i];
                    ConversionRank rank2 = candidate2.conversionRanks[i];
                    if (rank1 < ConversionRank.NullToValue || rank2 < ConversionRank.NullToValue)
                    {
                        // The tie breaking rules here do not apply to conversions that are not
                        // numeric or inheritance related.
                        continue;
                    }

                    if ((rank1 >= ConversionRank.NumericImplicit) != (rank2 >= ConversionRank.NumericImplicit))
                    {
                        // Skip trying to break ties when argument conversions are not both implicit or both
                        // explicit.  If we have that situation, there are multiple arguments and an
                        // ambiguity is probably the best choice.
                        continue;
                    }

                    // We will now compare the parameter types, ignoring the actual argument type.  To choose
                    // the right method, we need to know if we want the "most specific" or the "most general".
                    // If we have implicit argument conversions, we'll want the most specific, so invert the multiplier.
                    if (rank1 >= ConversionRank.NumericImplicit)
                    {
                        multiplier = -multiplier;
                    }

                    // With a positive multiplier, we'll choose the "most general" type, and a negative
                    // multiplier will choose the "most specific".
                    rank1 = LanguagePrimitives.GetConversionRank(params1[i].parameterType, params2[i].parameterType);
                    rank2 = LanguagePrimitives.GetConversionRank(params2[i].parameterType, params1[i].parameterType);
                    if (rank1 < rank2)
                    {
                        betterCount += multiplier;
                    }
                    else if (rank1 > rank2)
                    {
                        betterCount -= multiplier;
                    }
                }
            }

            if (betterCount == 0)
            {
                // Check if parameters are the same.  If so, we have a few tiebreakering rules down below.
                for (int i = 0; i < candidate1.conversionRanks.Length; ++i)
                {
                    if (params1[i].parameterType != params2[i].parameterType)
                    {
                        return 0;
                    }
                }

                // Apply tie breaking rules, related to expanded parameters
                if (candidate1.expandedParameters != null && candidate2.expandedParameters != null)
                {
                    // Both are using expanded parameters.  The one with more parameters is better
                    return (candidate1.parameters.Length > candidate2.parameters.Length) ? 1 : -1;
                }
                else if (candidate1.expandedParameters != null)
                {