MegaBites-AI/Windows-powershell

1// Copyright (c) Microsoft Corporation.2// Licensed under the MIT License.3 4using System.Collections;5using System.Xml;6 7namespace System.Management.Automation8{9    /// <summary>10    /// Class ProviderHelpInfo keeps track of help information to be returned by11    /// command help provider.12    /// </summary>13    internal sealed class ProviderHelpInfo : HelpInfo14    {15        /// <summary>16        /// Constructor for HelpProvider.17        /// </summary>18        private ProviderHelpInfo(XmlNode xmlNode)19        {20            MamlNode mamlNode = new MamlNode(xmlNode);21            _fullHelpObject = mamlNode.PSObject;22            this.Errors = mamlNode.Errors;23 24            _fullHelpObject.TypeNames.Clear();25            _fullHelpObject.TypeNames.Add("ProviderHelpInfo");26            _fullHelpObject.TypeNames.Add("HelpInfo");27        }28 29        #region Basic Help Properties / Methods30 31        /// <summary>32        /// Name of the provider for which this provider help info is for.33        /// </summary>34        /// <value>Name of the provider</value>35        internal override string Name36        {37            get38            {39                if (_fullHelpObject == null)40                    return string.Empty;41 42                if (_fullHelpObject.Properties["Name"] == null)43                    return string.Empty;44 45                if (_fullHelpObject.Properties["Name"].Value == null)46                    return string.Empty;47 48                string name = _fullHelpObject.Properties["Name"].Value.ToString();49                if (name == null)50                    return string.Empty;51 52                return name.Trim();53            }54        }55 56        /// <summary>57        /// Synopsis in the provider help info.58        /// </summary>59        /// <value>Synopsis in the provider help info</value>60        internal override string Synopsis61        {62            get63            {64                if (_fullHelpObject == null)65                    return string.Empty;66 67                if (_fullHelpObject.Properties["Synopsis"] == null)68                    return string.Empty;69 70                if (_fullHelpObject.Properties["Synopsis"].Value == null)71                    return string.Empty;72 73                string synopsis = _fullHelpObject.Properties["Synopsis"].Value.ToString();74                if (synopsis == null)75                    return string.Empty;76 77                return synopsis.Trim();78            }79        }80 81        /// <summary>82        /// Detailed description in the provider help info.83        /// </summary>84        /// <value>Detailed description in the provider help info</value>85        internal string DetailedDescription86        {87            get88            {89                if (this.FullHelp == null)90                    return string.Empty;91 92                if (this.FullHelp.Properties["DetailedDescription"] == null ||93                    this.FullHelp.Properties["DetailedDescription"].Value == null)94                {95                    return string.Empty;96                }97 98                IList descriptionItems = FullHelp.Properties["DetailedDescription"].Value as IList;99                if (descriptionItems == null || descriptionItems.Count == 0)100                {101                    return string.Empty;102                }103 104                // I think every provider description should at least have 400 characters...105                // so starting with this assumption..I did an average of all the help content106                // available at the time of writing this code and came up with this number.107                Text.StringBuilder result = new Text.StringBuilder(400);108                foreach (object descriptionItem in descriptionItems)109                {110                    PSObject descriptionObject = PSObject.AsPSObject(descriptionItem);111                    if ((descriptionObject == null) ||112                        (descriptionObject.Properties["Text"] == null) ||113                        (descriptionObject.Properties["Text"].Value == null))114                    {115                        continue;116                    }117 118                    string text = descriptionObject.Properties["Text"].Value.ToString();119                    result.Append(text);120                    result.Append(Environment.NewLine);121                }122 123                return result.ToString().Trim();124            }125        }126 127        /// <summary>128        /// Help category for this provider help info, which is constantly HelpCategory.Provider.129        /// </summary>130        /// <value>Help category for this provider help info</value>131        internal override HelpCategory HelpCategory132        {133            get134            {135                return HelpCategory.Provider;136            }137        }138 139        private readonly PSObject _fullHelpObject;140 141        /// <summary>142        /// Full help object for this provider help info.143        /// </summary>144        /// <value>Full help object for this provider help info</value>145        internal override PSObject FullHelp146        {147            get148            {149                return _fullHelpObject;150            }151        }152 153        /// <summary>154        /// Returns true if help content in help info matches the155        /// pattern contained in <paramref name="pattern"/>.156        /// The underlying code will usually run pattern.IsMatch() on157        /// content it wants to search.158        /// Provider help info looks for pattern in Synopsis and159        /// DetailedDescription.160        /// </summary>161        /// <param name="pattern"></param>162        /// <returns></returns>163        internal override bool MatchPatternInContent(WildcardPattern pattern)164        {165            Diagnostics.Assert(pattern != null, "pattern cannot be null");166 167            string synopsis = Synopsis;168            string detailedDescription = DetailedDescription;169 170            synopsis ??= string.Empty;171 172            detailedDescription ??= string.Empty;173 174            return pattern.IsMatch(synopsis) || pattern.IsMatch(detailedDescription);175        }176 177        #endregion178 179#if V2180        #region Cmdlet Help and Dynamic Parameter Help181 182        private Hashtable _cmdletHelps;183 184        /// <summary>185        /// Return the provider-specific cmdlet help based on input cmdletName.186        /// </summary>187        /// <param name="cmdletName">CmdletName on which to get provider-specific help.</param>188        /// <returns>An mshObject that contains provider-specific commandlet help.</returns>189        internal PSObject GetCmdletHelp(string cmdletName)190        {191            if (string.IsNullOrEmpty(cmdletName))192                return null;193 194            LoadCmdletHelps();195 196            if (_cmdletHelps == null)197                return null;198 199            return (PSObject)_cmdletHelps[cmdletName];200        }201 202        /// <summary>203        /// Load provider-specific commandlet helps from xmlNode stored in _fullHelpObject.204        /// Result will be stored in a hashtable.205        /// </summary>206        private void LoadCmdletHelps()207        {208            if (_cmdletHelps != null)209                return;210 211            if (_fullHelpObject == null)212                return;213 214            _cmdletHelps = new Hashtable();215 216            if (_fullHelpObject.Properties["Cmdlets"] == null)217                return;218 219            PSObject cmdlets = (PSObject)_fullHelpObject.Properties["Cmdlets"].Value;220 221            if (cmdlets == null)222                return;223 224            if (cmdlets.Properties["Cmdlet"] == null ||225                cmdlets.Properties["Cmdlet"].Value == null)226                return;227 228            if (cmdlets.Properties["Cmdlet"].Value.GetType().Equals(typeof(PSObject[])))229            {230                PSObject[] cmdletHelpItems = (PSObject[])cmdlets.Properties["Cmdlet"].Value;231 232                for (int i = 0; i < cmdletHelpItems.Length; i++)233                {234                    if (cmdletHelpItems[i].Properties["Name"] == null235                        || cmdletHelpItems[i].Properties["Name"].Value == null)236                        return;237 238                    string name = ((PSObject)cmdletHelpItems[i].Properties["Name"].Value).ToString();239 240                    _cmdletHelps[name] = cmdletHelpItems[i];241                }242            }243            else if (cmdlets.Properties["Cmdlet"].Value.GetType().Equals(typeof(PSObject[])))244            {245                PSObject cmdletHelpItem = (PSObject)cmdlets.Properties["Cmdlet"].Value;246 247                string name = ((PSObject)cmdletHelpItem.Properties["Name"].Value).ToString();248 249                _cmdletHelps[name] = cmdletHelpItem;250            }251        }252 253        private Hashtable _dynamicParameterHelps;254 255        /// <summary>256        /// Return the provider-specific dynamic parameter help based on input parameter name.257        /// </summary>258        /// <param name="parameters">An array of parameters to retrieve help.</param>259        /// <returns>An array of mshObject that contains the parameter help.</returns>260        internal PSObject[] GetDynamicParameterHelp(string[] parameters)261        {262            if (parameters == null || parameters.Length == 0)263                return null;264 265            LoadDynamicParameterHelps();266 267            if (_dynamicParameterHelps == null)268                return null;269 270            ArrayList result = new ArrayList();271 272            for (int i = 0; i < parameters.Length; i++)273            {274                PSObject entry = (PSObject)_dynamicParameterHelps[parameters[i].ToLower()];275 276                if (entry != null)277                    result.Add(entry);278            }279 280            return (PSObject[])result.ToArray(typeof(PSObject));281        }282 283        /// <summary>284        /// Load provider-specific dynamic parameter helps from xmlNode stored in _fullHelpObject.285        /// Result will be stored in a hashtable.286        /// </summary>287        private void LoadDynamicParameterHelps()288        {289            if (_dynamicParameterHelps != null)290                return;291 292            if (_fullHelpObject == null)293                return;294 295            _dynamicParameterHelps = new Hashtable();296 297            if (_fullHelpObject.Properties["DynamicParameters"] == null)298                return;299 300            PSObject dynamicParameters = (PSObject)_fullHelpObject.Properties["DynamicParameters"].Value;301 302            if (dynamicParameters == null)303                return;304 305            if (dynamicParameters.Properties["DynamicParameter"] == null306                || dynamicParameters.Properties["DynamicParameter"].Value == null)307                return;308 309            if (dynamicParameters.Properties["DynamicParameter"].Value.GetType().Equals(typeof(PSObject[])))310            {311                PSObject[] dynamicParameterHelpItems = (PSObject[])dynamicParameters.Properties["DynamicParameter"].Value;312 313                for (int i = 0; i < dynamicParameterHelpItems.Length; i++)314                {315                    if (dynamicParameterHelpItems[i].Properties["Name"] == null316                        || dynamicParameterHelpItems[i].Properties["Name"].Value == null)317                        return;318 319                    string name = ((PSObject)dynamicParameterHelpItems[i].Properties["Name"].Value).ToString();320 321                    _dynamicParameterHelps[name] = dynamicParameterHelpItems[i];322                }323            }324            else if (dynamicParameters.Properties["DynamicParameter"].Value.GetType().Equals(typeof(PSObject[])))325            {326                PSObject dynamicParameterHelpItem = (PSObject)dynamicParameters.Properties["DynamicParameter"].Value;327 328                string name = ((PSObject)dynamicParameterHelpItem.Properties["Name"].Value).ToString();329 330                _dynamicParameterHelps[name] = dynamicParameterHelpItem;331            }332        }333 334        #endregion335#endif336 337        #region Load Help338 339        /// <summary>340        /// Create providerHelpInfo from an xmlNode.341        /// </summary>342        /// <param name="xmlNode">Xml node that contains the provider help info.</param>343        /// <returns>The providerHelpInfo object created.</returns>344        internal static ProviderHelpInfo Load(XmlNode xmlNode)345        {346            ProviderHelpInfo providerHelpInfo = new ProviderHelpInfo(xmlNode);347 348            if (string.IsNullOrEmpty(providerHelpInfo.Name))349                return null;350 351            providerHelpInfo.AddCommonHelpProperties();352 353            return providerHelpInfo;354        }355 356        #endregion357    }358}359