MegaBites-AI/Windows-powershell

1// Copyright (c) Microsoft Corporation.2// Licensed under the MIT License.3 4using System;5using System.Diagnostics;6using System.Globalization;7using System.Management.Automation;8using System.Text;9using System.Windows.Documents;10 11namespace Microsoft.Management.UI.Internal12{13    /// <summary>14    /// Builds a help paragraph for a cmdlet.15    /// </summary>16    internal class HelpParagraphBuilder : ParagraphBuilder17    {18        /// <summary>19        /// Indentation size.20        /// </summary>21        internal const int IndentSize = 4;22 23        /// <summary>24        /// new line separators.25        /// </summary>26        private static readonly string[] Separators = new[] { "\r\n", "\n" };27 28        /// <summary>29        /// Object with the cmdelt.30        /// </summary>31        private readonly PSObject psObj;32 33        /// <summary>34        /// Initializes a new instance of the HelpParagraphBuilder class.35        /// </summary>36        /// <param name="paragraph">Paragraph being built.</param>37        /// <param name="psObj">Object with help information.</param>38        internal HelpParagraphBuilder(Paragraph paragraph, PSObject psObj)39            : base(paragraph)40        {41            this.psObj = psObj;42            this.AddTextToParagraphBuilder();43        }44 45        /// <summary>46        /// Enum for category of Help.47        /// </summary>48        private enum HelpCategory49        {50            Default,51            DscResource,52            Class53        }54 55        /// <summary>56        /// Gets the string value of a property or null if it could not be retrieved.57        /// </summary>58        /// <param name="psObj">Object with the property.</param>59        /// <param name="propertyName">Property name.</param>60        /// <returns>The string value of a property or null if it could not be retrieved.</returns>61        internal static string GetPropertyString(PSObject psObj, string propertyName)62        {63            Debug.Assert(psObj != null, "ensured by caller");64            object value = GetPropertyObject(psObj, propertyName);65 66            if (value == null)67            {68                return null;69            }70 71            return value.ToString();72        }73 74        /// <summary>75        /// Adds the help text to the paragraph.76        /// </summary>77        internal void AddTextToParagraphBuilder()78        {79            this.ResetAllText();80 81            string strCategory = HelpParagraphBuilder.GetProperty(this.psObj, "Category").Value.ToString();82 83            HelpCategory category = HelpCategory.Default;84 85            if (string.Equals(strCategory, "DscResource", StringComparison.OrdinalIgnoreCase))86            {87                category = HelpCategory.DscResource;88            }89            else if (string.Equals(strCategory, "Class", StringComparison.OrdinalIgnoreCase))90            {91                category = HelpCategory.Class;92            }93 94            if (HelpParagraphBuilder.GetProperty(this.psObj, "Syntax") == null)95            {96                if (category == HelpCategory.Default)97                {98                    // if there is no syntax, this is not the standard help99                    // it might be an about page100                    this.AddText(this.psObj.ToString(), false);101                    return;102                }103            }104 105            switch (category)106            {107                case HelpCategory.Class:108                    this.AddDescription(HelpWindowSettings.Default.HelpSynopsysDisplayed, HelpWindowResources.SynopsisTitle, "Introduction");109                    this.AddMembers(HelpWindowSettings.Default.HelpParametersDisplayed, HelpWindowResources.PropertiesTitle);110                    this.AddMembers(HelpWindowSettings.Default.HelpParametersDisplayed, HelpWindowResources.MethodsTitle);111                    break;112                case HelpCategory.DscResource:113                    this.AddStringSection(HelpWindowSettings.Default.HelpSynopsysDisplayed, "Synopsis", HelpWindowResources.SynopsisTitle);114                    this.AddDescription(HelpWindowSettings.Default.HelpDescriptionDisplayed, HelpWindowResources.DescriptionTitle, "Description");115                    this.AddParameters(HelpWindowSettings.Default.HelpParametersDisplayed, HelpWindowResources.PropertiesTitle, "Properties", HelpCategory.DscResource);116                    break;117                default:118                    this.AddStringSection(HelpWindowSettings.Default.HelpSynopsysDisplayed, "Synopsis", HelpWindowResources.SynopsisTitle);119                    this.AddDescription(HelpWindowSettings.Default.HelpDescriptionDisplayed, HelpWindowResources.DescriptionTitle, "Description");120                    this.AddParameters(HelpWindowSettings.Default.HelpParametersDisplayed, HelpWindowResources.ParametersTitle, "Parameters", HelpCategory.Default);121                    this.AddSyntax(HelpWindowSettings.Default.HelpSyntaxDisplayed, HelpWindowResources.SyntaxTitle);122                    break;123            }124 125            this.AddInputOrOutputEntries(HelpWindowSettings.Default.HelpInputsDisplayed, HelpWindowResources.InputsTitle, "inputTypes", "inputType");126            this.AddInputOrOutputEntries(HelpWindowSettings.Default.HelpOutputsDisplayed, HelpWindowResources.OutputsTitle, "returnValues", "returnValue");127            this.AddNotes(HelpWindowSettings.Default.HelpNotesDisplayed, HelpWindowResources.NotesTitle);128            this.AddExamples(HelpWindowSettings.Default.HelpExamplesDisplayed, HelpWindowResources.ExamplesTitle);129            this.AddNavigationLink(HelpWindowSettings.Default.HelpRelatedLinksDisplayed, HelpWindowResources.RelatedLinksTitle);130            this.AddStringSection(HelpWindowSettings.Default.HelpRemarksDisplayed, "Remarks", HelpWindowResources.RemarksTitle);131        }132 133        /// <summary>134        /// Gets the object property or null if it could not be retrieved.135        /// </summary>136        /// <param name="psObj">Object with the property.</param>137        /// <param name="propertyName">Property name.</param>138        /// <returns>The object property or null if it could not be retrieved.</returns>139        private static PSPropertyInfo GetProperty(PSObject psObj, string propertyName)140        {141            Debug.Assert(psObj != null, "ensured by caller");142            return psObj.Properties[propertyName];143        }144 145        /// <summary>146        /// Gets a PSObject and then a value from it or null if the value could not be retrieved.147        /// </summary>148        /// <param name="psObj">PSObject that contains another PSObject as a property.</param>149        /// <param name="psObjectName">Property name that contains the PSObject.</param>150        /// <param name="propertyName">Property name in the inner PSObject.</param>151        /// <returns>The string from the inner psObject property or null if it could not be retrieved.</returns>152        private static string GetInnerPSObjectPropertyString(PSObject psObj, string psObjectName, string propertyName)153        {154            Debug.Assert(psObj != null, "ensured by caller");155            PSObject innerPsObj = GetPropertyObject(psObj, psObjectName) as PSObject;156 157            if (innerPsObj == null)158            {159                return null;160            }161 162            object value = GetPropertyObject(innerPsObj, propertyName);163 164            if (value == null)165            {166                return null;167            }168 169            return value.ToString();170        }171 172        /// <summary>173        /// Gets the value of a property or null if the value could not be retrieved.174        /// </summary>175        /// <param name="psObj">Object with the property.</param>176        /// <param name="propertyName">Property name.</param>177        /// <returns>The value of a property or null if the value could not be retrieved.</returns>178        private static object GetPropertyObject(PSObject psObj, string propertyName)179        {180            Debug.Assert(psObj != null, "ensured by caller");181            PSPropertyInfo property = HelpParagraphBuilder.GetProperty(psObj, propertyName);182            if (property == null)183            {184                return null;185            }186 187            object value = null;188            try189            {190                value = property.Value;191            }192            catch (ExtendedTypeSystemException)193            {194                // ignore this exception195            }196 197            return value;198        }199 200        /// <summary>201        /// Gets the text from a property of type PSObject[] where the first object has a text property.202        /// </summary>203        /// <param name="psObj">Objhect to get text from.</param>204        /// <param name="propertyText">Property with PSObject[] containing text.</param>205        /// <returns>The text from a property of type PSObject[] where the first object has a text property.</returns>206        private static string GetTextFromArray(PSObject psObj, string propertyText)207        {208            PSObject[] introductionObjects = HelpParagraphBuilder.GetPropertyObject(psObj, propertyText) as PSObject[];209            if (introductionObjects != null && introductionObjects.Length > 0)210            {211                return GetPropertyString(introductionObjects[0], "text");212            }213 214            return null;215        }216 217        /// <summary>218        /// Returns the largest size of a group of strings.219        /// </summary>220        /// <param name="strs">Strings to evaluate the largest size from.</param>221        /// <returns>The largest size of a group of strings.</returns>222        private static int LargestSize(params string[] strs)223        {224            int returnValue = 0;225 226            foreach (string str in strs)227            {228                if (str != null && str.Length > returnValue)229                {230                    returnValue = str.Length;231                }232            }233 234            return returnValue;235        }236 237        /// <summary>238        /// Splits the string adding indentation before each line.239        /// </summary>240        /// <param name="str">String to add indentation to.</param>241        /// <returns>The string indented.</returns>242        private static string AddIndent(string str)243        {244            return HelpParagraphBuilder.AddIndent(str, 1);245        }246 247        /// <summary>248        /// Splits the string adding indentation before each line.249        /// </summary>250        /// <param name="str">String to add indentation to.</param>251        /// <param name="numberOfIdents">Number of indentations.</param>252        /// <returns>The string indented.</returns>253        private static string AddIndent(string str, int numberOfIdents)254        {255            StringBuilder indent = new StringBuilder();256            indent.Append(' ', numberOfIdents * HelpParagraphBuilder.IndentSize);257            return HelpParagraphBuilder.AddIndent(str, indent.ToString());258        }259 260        /// <summary>261        /// Splits the string adding indentation before each line.262        /// </summary>263        /// <param name="str">String to add indentation to.</param>264        /// <param name="indentString">Indentation string.</param>265        /// <returns>The string indented.</returns>266        private static string AddIndent(string str, string indentString)267        {268            if (str == null)269            {270                return string.Empty;271            }272 273            string[] lines = str.Split(Separators, StringSplitOptions.None);274 275            StringBuilder returnValue = new StringBuilder();276            foreach (string line in lines)277            {278                // Indentation is not localized279                returnValue.Append($"{indentString}{line}\r\n");280            }281 282            if (returnValue.Length > 2)283            {284                // remove the last \r\n285                returnValue.Remove(returnValue.Length - 2, 2);286            }287 288            return returnValue.ToString();289        }290 291        /// <summary>292        /// Get the object array value of a property.293        /// </summary>294        /// <param name="obj">Object containing the property.</param>295        /// <param name="propertyName">Property with the array value.</param>296        /// <returns>The object array value of a property.</returns>297        private static object[] GetPropertyObjectArray(PSObject obj, string propertyName)298        {299            object innerObject;300            if ((innerObject = HelpParagraphBuilder.GetPropertyObject(obj, propertyName)) == null)301            {302                return null;303            }304 305            if (innerObject is PSObject)306            {307                return new[] { innerObject };308            }309 310            object[] innerObjectArray = innerObject as object[];311            return innerObjectArray;312        }313 314        /// <summary>315        /// Adds a section that contains only a string.316        /// </summary>317        /// <param name="setting">True if it should add the segment.</param>318        /// <param name="sectionName">Name of the section to add.</param>319        /// <param name="sectionTitle">Title of the section.</param>320        private void AddStringSection(bool setting, string sectionName, string sectionTitle)321        {322            string propertyValue;323            if (!setting || (propertyValue = HelpParagraphBuilder.GetPropertyString(this.psObj, sectionName)) == null)324            {325                return;326            }327 328            this.AddText(sectionTitle, true);329            this.AddText("\r\n", false);330            this.AddText(HelpParagraphBuilder.AddIndent(propertyValue), false);331            this.AddText("\r\n\r\n", false);332        }333 334        /// <summary>335        /// Adds the help syntax segment.336        /// </summary>337        /// <param name="setting">True if it should add the segment.</param>338        /// <param name="sectionTitle">Title of the section.</param>339        private void AddSyntax(bool setting, string sectionTitle)340        {341            PSObject syntaxObject;342            if (!setting || (syntaxObject = HelpParagraphBuilder.GetPropertyObject(this.psObj, "Syntax") as PSObject) == null)343            {344                return;345            }346 347            object[] syntaxItemsObj = HelpParagraphBuilder.GetPropertyObjectArray(syntaxObject, "syntaxItem");348            if (syntaxItemsObj == null || syntaxItemsObj.Length == 0)349            {350                return;351            }352 353            this.AddText(sectionTitle, true);354            this.AddText("\r\n", false);355 356            foreach (object syntaxItemObj in syntaxItemsObj)357            {358                PSObject syntaxItem = syntaxItemObj as PSObject;359                if (syntaxItem == null)360                {361                    continue;362                }363 364                string commandName = GetPropertyString(syntaxItem, "name");365 366                object[] parameterObjs = HelpParagraphBuilder.GetPropertyObjectArray(syntaxItem, "parameter");367                if (commandName == null || parameterObjs == null || parameterObjs.Length == 0)368                {369                    continue;370                }371 372                string commandStart = string.Create(CultureInfo.CurrentCulture, $"{commandName} ");373                this.AddText(HelpParagraphBuilder.AddIndent(commandStart), false);374 375                foreach (object parameterObj in parameterObjs)376                {377                    PSObject parameter = parameterObj as PSObject;378                    if (parameter == null)379                    {380                        continue;381                    }382 383                    string parameterValue = GetPropertyString(parameter, "parameterValue");384                    string position = GetPropertyString(parameter, "position");385                    string required = GetPropertyString(parameter, "required");386                    string parameterName = GetPropertyString(parameter, "name");387                    if (position == null || required == null || parameterName == null)388                    {389                        continue;390                    }391 392                    string parameterType = parameterValue == null ? string.Empty : string.Create(CultureInfo.CurrentCulture, $"<{parameterValue}>");393 394                    string parameterOptionalOpenBrace, parameterOptionalCloseBrace;395 396                    if (string.Equals(required, "true", StringComparison.OrdinalIgnoreCase))397                    {398                        parameterOptionalOpenBrace = string.Empty;399                        parameterOptionalCloseBrace = string.Empty;400                    }401                    else402                    {403                        parameterOptionalOpenBrace = "[";404                        parameterOptionalCloseBrace = "]";405                    }406 407                    string parameterNameOptionalOpenBrace, parameterNameOptionalCloseBrace;408 409                    if (string.Equals(position, "named", StringComparison.OrdinalIgnoreCase))410                    {411                        parameterNameOptionalOpenBrace = parameterNameOptionalCloseBrace = string.Empty;412                    }413                    else414                    {415                        parameterNameOptionalOpenBrace = "[";416                        parameterNameOptionalCloseBrace = "]";417                    }418 419                    string paramterPrefix = string.Format(420                        CultureInfo.CurrentCulture,421                        "{0}{1}-",422                        parameterOptionalOpenBrace,423                        parameterNameOptionalOpenBrace);424 425                    this.AddText(paramterPrefix, false);426                    this.AddText(parameterName, true);427 428                    string paramterSuffix = string.Format(429                        CultureInfo.CurrentCulture,430                        "{0} {1}{2} ",431                        parameterNameOptionalCloseBrace,432                        parameterType,433                        parameterOptionalCloseBrace);434                    this.AddText(paramterSuffix, false);435                }436 437                string commonParametersText = string.Format(438                    CultureInfo.CurrentCulture,439                    "[<{0}>]\r\n\r\n",440                    HelpWindowResources.CommonParameters);441 442                this.AddText(commonParametersText, false);443            }444 445            this.AddText("\r\n", false);446        }447 448        /// <summary>449        /// Adds the help description segment.450        /// </summary>451        /// <param name="setting">True if it should add the segment.</param>452        /// <param name="sectionTitle">Title of the section.</param>453        /// <param name="propertyName">PropertyName that has description.</param>454        private void AddDescription(bool setting, string sectionTitle, string propertyName)455        {456            PSObject[] descriptionObjects;457            if (!setting ||458                 (descriptionObjects = HelpParagraphBuilder.GetPropertyObject(this.psObj, propertyName) as PSObject[]) == null ||459                 descriptionObjects.Length == 0)460            {461                return;462            }463 464            this.AddText(sectionTitle, true);465            this.AddText("\r\n", false);466 467            foreach (PSObject description in descriptionObjects)468            {469                string descriptionText = GetPropertyString(description, "text");470                this.AddText(HelpParagraphBuilder.AddIndent(descriptionText), false);471                this.AddText("\r\n", false);472            }473 474            this.AddText("\r\n\r\n", false);475        }476 477        /// <summary>478        /// Adds the help examples segment.479        /// </summary>480        /// <param name="setting">True if it should add the segment.</param>481        /// <param name="sectionTitle">Title of the section.</param>482        private void AddExamples(bool setting, string sectionTitle)483        {484            if (!setting)485            {486                return;487            }488 489            PSObject exampleRootObject = HelpParagraphBuilder.GetPropertyObject(this.psObj, "Examples") as PSObject;490            if (exampleRootObject == null)491            {492                return;493            }494 495            object[] exampleObjects = HelpParagraphBuilder.GetPropertyObjectArray(exampleRootObject, "example");496            if (exampleObjects == null || exampleObjects.Length == 0)497            {498                return;499            }500 501            this.AddText(sectionTitle, true);502            this.AddText("\r\n", false);503 504            foreach (object exampleObj in exampleObjects)505            {506                PSObject example = exampleObj as PSObject;507                if (example == null)508                {509                    continue;510                }511 512                string introductionText = null;513                introductionText = GetTextFromArray(example, "introduction");514 515                string codeText = GetPropertyString(example, "code");516                string title = GetPropertyString(example, "title");517 518                if (codeText == null)519                {520                    continue;521                }522 523                if (title != null)524                {525                    this.AddText(HelpParagraphBuilder.AddIndent(title), false);526                    this.AddText("\r\n", false);527                }528 529                string codeLine = string.Format(530                    CultureInfo.CurrentCulture,531                    "{0}{1}\r\n\r\n",532                    introductionText,533                    codeText);534 535                this.AddText(HelpParagraphBuilder.AddIndent(codeLine), false);536 537                PSObject[] remarks = HelpParagraphBuilder.GetPropertyObject(example, "remarks") as PSObject[];538                if (remarks == null)539                {540                    continue;541                }542 543                foreach (PSObject remark in remarks)544                {545                    string remarkText = GetPropertyString(remark, "text");546                    if (remarkText == null)547                    {548                        continue;549                    }550 551                    this.AddText(remarkText, false);552                    this.AddText("\r\n", false);553                }554            }555 556            this.AddText("\r\n\r\n", false);557        }558 559        private void AddMembers(bool setting, string sectionTitle)560        {561            if (!setting || string.IsNullOrEmpty(sectionTitle))562            {563                return;564            }565 566            PSObject memberRootObject = HelpParagraphBuilder.GetPropertyObject(this.psObj, "Members") as PSObject;567            if (memberRootObject == null)568            {569                return;570            }571 572            object[] memberObjects = HelpParagraphBuilder.GetPropertyObjectArray(memberRootObject, "member");573 574            if (memberObjects == null)575            {576                return;577            }578 579            this.AddText(sectionTitle, true);580            this.AddText("\r\n", false);581 582            foreach (object memberObj in memberObjects)583            {584                string description = null;585                string memberText = null;586 587                PSObject member = memberObj as PSObject;588                if (member == null)589                {590                    continue;591                }592 593                string name = GetPropertyString(member, "title");594                string type = GetPropertyString(member, "type");595                string propertyType = null;596 597                if (string.Equals("field", type, StringComparison.OrdinalIgnoreCase))598                {599                    PSObject fieldData = HelpParagraphBuilder.GetPropertyObject(member, "fieldData") as PSObject;600 601                    if (fieldData != null)602                    {603                        PSObject propertyTypeObject = HelpParagraphBuilder.GetPropertyObject(fieldData, "type") as PSObject;604                        if (propertyTypeObject != null)605                        {606                            propertyType = GetPropertyString(propertyTypeObject, "name");607                            description = GetPropertyString(propertyTypeObject, "description");608                        }609 610                        memberText = string.Create(CultureInfo.CurrentCulture, $" [{propertyType}] {name}\r\n");611                    }612                }613                else if (string.Equals("method", type, StringComparison.OrdinalIgnoreCase))614                {615                    FormatMethodData(member, name, out memberText, out description);616                }617 618                if (!string.IsNullOrEmpty(memberText))619                {620                    this.AddText(HelpParagraphBuilder.AddIndent(string.Empty), false);621                    this.AddText(memberText, true);622 623                    if (description != null)624                    {625                        this.AddText(HelpParagraphBuilder.AddIndent(description, 2), false);626                        this.AddText("\r\n", false);627                    }628 629                    this.AddText("\r\n", false);630                }631            }632        }633 634        private static void FormatMethodData(PSObject member, string name, out string memberText, out string description)635        {636            memberText = null;637            description = null;638 639            if (member == null || string.IsNullOrEmpty(name))640            {641                return;642            }643 644            string returnType = null;645            StringBuilder parameterText = new StringBuilder();646 647            // Get method return type648            PSObject returnTypeObject = HelpParagraphBuilder.GetPropertyObject(member, "returnValue") as PSObject;649            if (returnTypeObject != null)650            {651                PSObject returnTypeData = HelpParagraphBuilder.GetPropertyObject(returnTypeObject, "type") as PSObject;652                if (returnTypeData != null)653                {654                    returnType = GetPropertyString(returnTypeData, "name");655                }656            }657 658            // Get method description.659            PSObject[] methodDescriptions = HelpParagraphBuilder.GetPropertyObject(member, "introduction") as PSObject[];660            if (methodDescriptions != null)661            {662                foreach (var methodDescription in methodDescriptions)663                {664                    description = GetPropertyString(methodDescription, "Text");665 666                    // If we get an text we do not need to iterate more.667                    if (!string.IsNullOrEmpty(description))668                    {669                        break;670                    }671                }672            }673 674            // Get method parameters.675            PSObject parametersObject = HelpParagraphBuilder.GetPropertyObject(member, "parameters") as PSObject;676            if (parametersObject != null)677            {678                PSObject[] paramObject = HelpParagraphBuilder.GetPropertyObject(parametersObject, "parameter") as PSObject[];679 680                if (paramObject != null)681                {682                    foreach (var param in paramObject)683                    {684                        string parameterName = GetPropertyString(param, "name");685                        string parameterType = null;686 687                        PSObject parameterTypeData = HelpParagraphBuilder.GetPropertyObject(param, "type") as PSObject;688 689                        if (parameterTypeData != null)690                        {691                            parameterType = GetPropertyString(parameterTypeData, "name");692 693                            // If there is no type for the parameter, we expect it is System.Object694                            if (string.IsNullOrEmpty(parameterType))695                            {696                                parameterType = "object";697                            }698                        }699 700                        string paramString = string.Create(CultureInfo.CurrentCulture, $"[{parameterType}] ${parameterName},");701 702                        parameterText.Append(paramString);703                    }704 705                    if (string.Equals(parameterText[parameterText.Length - 1].ToString(), ",", StringComparison.OrdinalIgnoreCase))706                    {707                        parameterText = parameterText.Remove(parameterText.Length - 1, 1);708                    }709                }710            }711 712            memberText = string.Create(CultureInfo.CurrentCulture, $" [{returnType}] {name}({parameterText})\r\n");713        }714 715        /// <summary>716        /// Adds the help parameters segment.717        /// </summary>718        /// <param name="setting">True if it should add the segment.</param>719        /// <param name="sectionTitle">Title of the section.</param>720        /// <param name="paramPropertyName">Name of the property which has properties.</param>721        /// <param name="helpCategory">Category of help.</param>722        private void AddParameters(bool setting, string sectionTitle, string paramPropertyName, HelpCategory helpCategory)723        {724            if (!setting)725            {726                return;727            }728 729            PSObject parameterRootObject = HelpParagraphBuilder.GetPropertyObject(this.psObj, paramPropertyName) as PSObject;730            if (parameterRootObject == null)731            {732                return;733            }734 735            object[] parameterObjects = null;736 737            // Root object for Class has members not parameters.738            if (helpCategory != HelpCategory.Class)739            {740                parameterObjects = HelpParagraphBuilder.GetPropertyObjectArray(parameterRootObject, "parameter");741            }742 743            if (parameterObjects == null || parameterObjects.Length == 0)744            {745                return;746            }747 748            this.AddText(sectionTitle, true);749            this.AddText("\r\n", false);750 751            foreach (object parameterObj in parameterObjects)752            {753                PSObject parameter = parameterObj as PSObject;754                if (parameter == null)755                {756                    continue;757                }758 759                string parameterValue = GetPropertyString(parameter, "parameterValue");760                string name = GetPropertyString(parameter, "name");761                string description = GetTextFromArray(parameter, "description");762                string required = GetPropertyString(parameter, "required");763                string position = GetPropertyString(parameter, "position");764                string pipelineinput = GetPropertyString(parameter, "pipelineInput");765                string defaultValue = GetPropertyString(parameter, "defaultValue");766                string acceptWildcard = GetPropertyString(parameter, "globbing");767 768                if (string.IsNullOrEmpty(name))769                {770                    continue;771                }772 773                if (helpCategory == HelpCategory.DscResource)774                {775                    this.AddText(HelpParagraphBuilder.AddIndent(string.Empty), false);776                }777                else778                {779                    this.AddText(HelpParagraphBuilder.AddIndent("-"), false);780                }781 782                this.AddText(name, true);783                string parameterText = string.Format(784                    CultureInfo.CurrentCulture,785                    " <{0}>\r\n",786                    parameterValue);787 788                this.AddText(parameterText, false);789 790                if (description != null)791                {792                    this.AddText(HelpParagraphBuilder.AddIndent(description, 2), false);793                    this.AddText("\r\n", false);794                }795 796                this.AddText("\r\n", false);797 798                int largestSize = HelpParagraphBuilder.LargestSize(799                    HelpWindowResources.ParameterRequired,800                    HelpWindowResources.ParameterPosition,801                    HelpWindowResources.ParameterDefaultValue,802                    HelpWindowResources.ParameterPipelineInput,803                    HelpWindowResources.ParameterAcceptWildcard);804 805                // justification of parameter values is not localized806                string formatString = string.Format(807                    CultureInfo.CurrentCulture,808                    "{{0,-{0}}}{{1}}",809                    largestSize + 2);810 811                string tableLine;812 813                tableLine = string.Format(814                    CultureInfo.CurrentCulture,815                    formatString,816                    HelpWindowResources.ParameterRequired,817                    required);818                this.AddText(HelpParagraphBuilder.AddIndent(tableLine, 2), false);819                this.AddText("\r\n", false);820 821                // these are not applicable for Dsc Resource help822                if (helpCategory != HelpCategory.DscResource)823                {824                    tableLine = string.Format(825                        CultureInfo.CurrentCulture,826                        formatString,827                        HelpWindowResources.ParameterPosition,828                        position);829                    this.AddText(HelpParagraphBuilder.AddIndent(tableLine, 2), false);830                    this.AddText("\r\n", false);831 832                    tableLine = string.Format(833                        CultureInfo.CurrentCulture,834                        formatString,835                        HelpWindowResources.ParameterDefaultValue,836                        defaultValue);837                    this.AddText(HelpParagraphBuilder.AddIndent(tableLine, 2), false);838                    this.AddText("\r\n", false);839 840                    tableLine = string.Format(841                        CultureInfo.CurrentCulture,842                        formatString,843                        HelpWindowResources.ParameterPipelineInput,844                        pipelineinput);845                    this.AddText(HelpParagraphBuilder.AddIndent(tableLine, 2), false);846                    this.AddText("\r\n", false);847 848                    tableLine = string.Format(849                        CultureInfo.CurrentCulture,850                        formatString,851                        HelpWindowResources.ParameterAcceptWildcard,852                        acceptWildcard);853                    this.AddText(HelpParagraphBuilder.AddIndent(tableLine, 2), false);854                }855 856                this.AddText("\r\n\r\n", false);857            }858 859            this.AddText("\r\n\r\n", false);860        }861 862        /// <summary>863        /// Adds the help navigation links segment.864        /// </summary>865        /// <param name="setting">True if it should add the segment.</param>866        /// <param name="sectionTitle">Title of the section.</param>867        private void AddNavigationLink(bool setting, string sectionTitle)868        {869            if (!setting)870            {871                return;872            }873 874            PSObject linkRootObject = HelpParagraphBuilder.GetPropertyObject(this.psObj, "RelatedLinks") as PSObject;875            if (linkRootObject == null)876            {877                return;878            }879 880            PSObject[] linkObjects;881 882            if ((linkObjects = HelpParagraphBuilder.GetPropertyObject(linkRootObject, "navigationLink") as PSObject[]) == null ||883                linkObjects.Length == 0)884            {885                return;886            }887 888            this.AddText(sectionTitle, true);889            this.AddText("\r\n", false);890 891            foreach (PSObject linkObject in linkObjects)892            {893                string text = GetPropertyString(linkObject, "linkText");894                string uri = GetPropertyString(linkObject, "uri");895 896                string linkLine = string.IsNullOrEmpty(uri) ? text : string.Format(897                    CultureInfo.CurrentCulture,898                    HelpWindowResources.LinkTextFormat,899                    text,900                    uri);901 902                this.AddText(HelpParagraphBuilder.AddIndent(linkLine), false);903                this.AddText("\r\n", false);904            }905 906            this.AddText("\r\n\r\n", false);907        }908 909        /// <summary>910        /// Adds the help input or output segment.911        /// </summary>912        /// <param name="setting">True if it should add the segment.</param>913        /// <param name="sectionTitle">Title of the section.</param>914        /// <param name="inputOrOutputProperty">Property with the outter object.</param>915        /// <param name="inputOrOutputInnerProperty">Property with the inner object.</param>916        private void AddInputOrOutputEntries(bool setting, string sectionTitle, string inputOrOutputProperty, string inputOrOutputInnerProperty)917        {918            if (!setting)919            {920                return;921            }922 923            PSObject rootObject = HelpParagraphBuilder.GetPropertyObject(this.psObj, inputOrOutputProperty) as PSObject;924            if (rootObject == null)925            {926                return;927            }928 929            object[] inputOrOutputObjs;930            inputOrOutputObjs = HelpParagraphBuilder.GetPropertyObjectArray(rootObject, inputOrOutputInnerProperty);931 932            if (inputOrOutputObjs == null || inputOrOutputObjs.Length == 0)933            {934                return;935            }936 937            this.AddText(sectionTitle, true);938            this.AddText("\r\n", false);939 940            foreach (object inputOrOutputObj in inputOrOutputObjs)941            {942                PSObject inputOrOutput = inputOrOutputObj as PSObject;943                if (inputOrOutput == null)944                {945                    continue;946                }947 948                string type = HelpParagraphBuilder.GetInnerPSObjectPropertyString(inputOrOutput, "type", "name");949                string description = GetTextFromArray(inputOrOutput, "description");950 951                this.AddText(HelpParagraphBuilder.AddIndent(type), false);952                this.AddText("\r\n", false);953                if (description != null)954                {955                    this.AddText(HelpParagraphBuilder.AddIndent(description), false);956                    this.AddText("\r\n", false);957                }958            }959 960            this.AddText("\r\n", false);961        }962 963        /// <summary>964        /// Adds the help notes segment.965        /// </summary>966        /// <param name="setting">True if it should add the segment.</param>967        /// <param name="sectionTitle">Title of the section.</param>968        private void AddNotes(bool setting, string sectionTitle)969        {970            if (!setting)971            {972                return;973            }974 975            PSObject rootObject = HelpParagraphBuilder.GetPropertyObject(this.psObj, "alertSet") as PSObject;976            if (rootObject == null)977            {978                return;979            }980 981            string note = GetTextFromArray(rootObject, "alert");982 983            if (note == null)984            {985                return;986            }987 988            this.AddText(sectionTitle, true);989            this.AddText("\r\n", false);990            this.AddText(HelpParagraphBuilder.AddIndent(note), false);991            this.AddText("\r\n\r\n", false);992        }993    }994}995