CoreAdapter.cs

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

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 SiteBinderCanOptimize { get { return false; } }

        protected static IEnumerable<string> GetDotNetTypeNameHierarchy(Type type)
        {
            for (; type != null; type = type.GetTypeInfo().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>
        /// 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 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)
        {
            if (argument == null)
            {
                return typeof(LanguagePrimitives.Null);
            }
            PSReference psref = argument as PSReference;
            if (psref != null)
            {
                return GetArgumentType(PSObject.Base(psref.Value));
            }
            return argument.GetType();
        }

        internal static ConversionRank GetArgumentConversionRank(object argument, Type parameterType)
        {
            Type fromType = GetArgumentType(argument);
            ConversionRank rank = LanguagePrimitives.GetConversionRank(fromType, parameterType);

            if (rank == ConversionRank.None)
            {
                fromType = GetArgumentType(PSObject.Base(argument));
                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)
                {
                    return -1;
                }
                else if (candidate2.expandedParameters != null)
                {
                    return 1;
                }


                // Apply tie breaking rules, related to specificity of parameters
                betterCount = CompareTypeSpecificity(candidate1, candidate2);
            }

            // The methods with fewer parameter wins
            //Need to revisit this if we support named arguments
            if (betterCount == 0)
            {
                if (candidate1.parameters.Length < candidate2.parameters.Length)
                {
                    return 1;
                }
                else if (candidate1.parameters.Length > candidate2.parameters.Length)
                {
                    return -1;
                }
            }

            return betterCount;
        }

        private static OverloadCandidate FindBestCandidate(List<OverloadCandidate> candidates, object[] arguments)
        {
            Dbg.Assert(candidates != null, "Caller should verify candidates != null");

            OverloadCandidate bestCandidateSoFar = null;
            bool multipleBestCandidates = false;

            for (int i = 0; i < candidates.Count; i++)
            {
                OverloadCandidate currentCandidate = candidates[i];
                if (bestCandidateSoFar == null) // first iteration
                {
                    bestCandidateSoFar = currentCandidate;
                    continue;
                }

                int comparisonResult = CompareOverloadCandidates(bestCandidateSoFar, currentCandidate, arguments);
                if (comparisonResult == 0)
                {
                    multipleBestCandidates = true;
                }
                else if (comparisonResult < 0)
                {
                    bestCandidateSoFar = currentCandidate;
                    multipleBestCandidates = false;
                }
            }

            Dbg.Assert(
                !candidates.Any(otherCandidate => otherCandidate != bestCandidateSoFar && CompareOverloadCandidates(otherCandidate, bestCandidateSoFar, arguments) > 0),
                "No other candidates are better than bestCandidateSoFar");

            return multipleBestCandidates ? null : bestCandidateSoFar;
        }

        private static OverloadCandidate FindBestCandidate(List<OverloadCandidate> candidates, object[] arguments, PSMethodInvocationConstraints invocationConstraints)
        {
            List<OverloadCandidate> filteredCandidates = candidates.Where(candidate => IsInvocationConstraintSatisfied(candidate, invocationConstraints)).ToList();
            if (filteredCandidates.Count > 0)
            {
                candidates = filteredCandidates;
            }

            OverloadCandidate bestCandidate = FindBestCandidate(candidates, arguments);
            return bestCandidate;
        }

        private static int CompareTypeSpecificity(Type type1, Type type2)
        {
            if (type1.IsGenericParameter || type2.IsGenericParameter)
            {
                int result = 0;
                if (type1.IsGenericParameter)
                {
                    result -= 1;
                }
                if (type2.IsGenericParameter)
                {
                    result += 1;
                }
                return result;
            }

            if (type1.IsArray)
            {
                Dbg.Assert(type2.IsArray, "Caller should verify that both overload candidates have the same parameter types");
                Dbg.Assert(type1.GetArrayRank() == type2.GetArrayRank(), "Caller should verify that both overload candidates have the same parameter types");
                return CompareTypeSpecificity(type1.GetElementType(), type2.GetElementType());
            }

            if (type1.GetTypeInfo().IsGenericType)
            {
                Dbg.Assert(type2.GetTypeInfo().IsGenericType, "Caller should verify that both overload candidates have the same parameter types");
                Dbg.Assert(type1.GetGenericTypeDefinition() == type2.GetGenericTypeDefinition(), "Caller should verify that both overload candidates have the same parameter types");
                return CompareTypeSpecificity(type1.GetGenericArguments(), type2.GetGenericArguments());
            }

            return 0;
        }

        private static int CompareTypeSpecificity(Type[] params1, Type[] params2)
        {
            Dbg.Assert(params1.Length == params2.Length, "Caller should verify that both overload candidates have the same number of parameters");

            bool candidate1hasAtLeastOneMoreSpecificParameter = false;
            bool candidate2hasAtLeastOneMoreSpecificParameter = false;
            for (int i = 0; i < params1.Length; ++i)
            {
                int specificityComparison = CompareTypeSpecificity(params1[i], params2[i]);
                if (specificityComparison > 0)
                {
                    candidate1hasAtLeastOneMoreSpecificParameter = true;
                }
                else if (specificityComparison < 0)
                {
                    candidate2hasAtLeastOneMoreSpecificParameter = true;
                }