/// <summary> /// Adds the help notes segment /// </summary> /// <param name="setting">true if it should add the segment</param> /// <param name="sectionTitle">title of the section</param> private void AddNotes(bool setting, string sectionTitle) { if (!setting) { return; } PSObject rootObject = HelpParagraphBuilder.GetPropertyObject(this.psObj, "alertSet") as PSObject; if (rootObject == null) { return; } string note = GetTextFromArray(rootObject, "alert"); if (note == null) { return; } this.AddText(sectionTitle, true); this.AddText("\r\n", false); this.AddText(HelpParagraphBuilder.AddIndent(note), false); this.AddText("\r\n\r\n", false); }
/// <summary> /// Gets the text from a property of type PSObject[] where the first object has a text property /// </summary> /// <param name="psObj">object to get text from</param> /// <param name="propertyText">property with PSObject[] containing text</param> /// <returns>the text from a property of type PSObject[] where the first object has a text property</returns> private static string GetTextFromArray(PSObject psObj, string propertyText) { PSObject[] introductionObjects = HelpParagraphBuilder.GetPropertyObject(psObj, propertyText) as PSObject[]; if (introductionObjects != null && introductionObjects.Length > 0) { return(GetPropertyString(introductionObjects[0], "text")); } return(null); }
/// <summary> /// Adds the help input or output segment /// </summary> /// <param name="setting">true if it should add the segment</param> /// <param name="sectionTitle">title of the section</param> /// <param name="inputOrOutputProperty">property with the outer object</param> /// <param name="inputOrOutputInnerProperty">property with the inner object</param> private void AddInputOrOutputEntries(bool setting, string sectionTitle, string inputOrOutputProperty, string inputOrOutputInnerProperty) { if (!setting) { return; } PSObject rootObject = HelpParagraphBuilder.GetPropertyObject(this.psObj, inputOrOutputProperty) as PSObject; if (rootObject == null) { return; } object[] inputOrOutputObjs; inputOrOutputObjs = HelpParagraphBuilder.GetPropertyObjectArray(rootObject, inputOrOutputInnerProperty); if (inputOrOutputObjs == null || inputOrOutputObjs.Length == 0) { return; } this.AddText(sectionTitle, true); this.AddText("\r\n", false); foreach (object inputOrOutputObj in inputOrOutputObjs) { PSObject inputOrOutput = inputOrOutputObj as PSObject; if (inputOrOutput == null) { continue; } string type = HelpParagraphBuilder.GetInnerPSObjectPropertyString(inputOrOutput, "type", "name"); string description = GetTextFromArray(inputOrOutput, "description"); this.AddText(HelpParagraphBuilder.AddIndent(type), false); this.AddText("\r\n", false); if (description != null) { this.AddText(HelpParagraphBuilder.AddIndent(description), false); this.AddText("\r\n", false); } } this.AddText("\r\n", false); }
/// <summary> /// Get the object array value of a property. /// </summary> /// <param name="obj">Object containing the property.</param> /// <param name="propertyName">Property with the array value.</param> /// <returns>The object array value of a property.</returns> private static object[] GetPropertyObjectArray(PSObject obj, string propertyName) { object innerObject; if ((innerObject = HelpParagraphBuilder.GetPropertyObject(obj, propertyName)) == null) { return(null); } if (innerObject is PSObject) { return(new[] { innerObject }); } object[] innerObjectArray = innerObject as object[]; return(innerObjectArray); }
/// <summary> /// Adds the help navigation links segment /// </summary> /// <param name="setting">true if it should add the segment</param> /// <param name="sectionTitle">title of the section</param> private void AddNavigationLink(bool setting, string sectionTitle) { if (!setting) { return; } PSObject linkRootObject = HelpParagraphBuilder.GetPropertyObject(this.psObj, "RelatedLinks") as PSObject; if (linkRootObject == null) { return; } PSObject[] linkObjects; if ((linkObjects = HelpParagraphBuilder.GetPropertyObject(linkRootObject, "navigationLink") as PSObject[]) == null || linkObjects.Length == 0) { return; } this.AddText(sectionTitle, true); this.AddText("\r\n", false); foreach (PSObject linkObject in linkObjects) { string text = GetPropertyString(linkObject, "linkText"); string uri = GetPropertyString(linkObject, "uri"); string linkLine = String.IsNullOrEmpty(uri) ? text : String.Format( CultureInfo.CurrentCulture, HelpWindowResources.LinkTextFormat, text, uri); this.AddText(HelpParagraphBuilder.AddIndent(linkLine), false); this.AddText("\r\n", false); } this.AddText("\r\n\r\n", false); }
/// <summary> /// Adds the help description segment /// </summary> /// <param name="setting">true if it should add the segment</param> /// <param name="sectionTitle">title of the section</param> /// <param name="propertyName">propertyName that has description</param> private void AddDescription(bool setting, string sectionTitle, string propertyName) { PSObject[] descriptionObjects; if (!setting || (descriptionObjects = HelpParagraphBuilder.GetPropertyObject(this.psObj, propertyName) as PSObject[]) == null || descriptionObjects.Length == 0) { return; } this.AddText(sectionTitle, true); this.AddText("\r\n", false); foreach (PSObject description in descriptionObjects) { string descriptionText = GetPropertyString(description, "text"); this.AddText(HelpParagraphBuilder.AddIndent(descriptionText), false); this.AddText("\r\n", false); } this.AddText("\r\n\r\n", false); }
/// <summary> /// Adds the help parameters segment /// </summary> /// <param name="setting">true if it should add the segment</param> /// <param name="sectionTitle">title of the section</param> /// <param name="paramPropertyName">name of the property which has properties</param> /// <param name="helpCategory">category of help</param> private void AddParameters(bool setting, string sectionTitle, string paramPropertyName, HelpCategory helpCategory) { if (!setting) { return; } PSObject parameterRootObject = HelpParagraphBuilder.GetPropertyObject(this.psObj, paramPropertyName) as PSObject; if (parameterRootObject == null) { return; } object[] parameterObjects = null; //Root object for Class has members not parameters. if (helpCategory != HelpCategory.Class) { parameterObjects = HelpParagraphBuilder.GetPropertyObjectArray(parameterRootObject, "parameter"); } if (parameterObjects == null || parameterObjects.Length == 0) { return; } this.AddText(sectionTitle, true); this.AddText("\r\n", false); foreach (object parameterObj in parameterObjects) { PSObject parameter = parameterObj as PSObject; if (parameter == null) { continue; } string parameterValue = GetPropertyString(parameter, "parameterValue"); string name = GetPropertyString(parameter, "name"); string description = GetTextFromArray(parameter, "description"); string required = GetPropertyString(parameter, "required"); string position = GetPropertyString(parameter, "position"); string pipelineinput = GetPropertyString(parameter, "pipelineInput"); string defaultValue = GetPropertyString(parameter, "defaultValue"); string acceptWildcard = GetPropertyString(parameter, "globbing"); if (String.IsNullOrEmpty(name)) { continue; } // This syntax string is not localized if (helpCategory == HelpCategory.DscResource) { this.AddText(HelpParagraphBuilder.AddIndent(""), false); } else { this.AddText(HelpParagraphBuilder.AddIndent("-"), false); } this.AddText(name, true); string parameterText = String.Format( CultureInfo.CurrentCulture, " <{0}>\r\n", parameterValue); this.AddText(parameterText, false); if (description != null) { this.AddText(HelpParagraphBuilder.AddIndent(description, 2), false); this.AddText("\r\n", false); } this.AddText("\r\n", false); int largestSize = HelpParagraphBuilder.LargestSize( HelpWindowResources.ParameterRequired, HelpWindowResources.ParameterPosition, HelpWindowResources.ParameterDefautValue, HelpWindowResources.ParameterPipelineInput, HelpWindowResources.ParameterAcceptWildcard); // justification of parameter values is not localized string formatString = String.Format( CultureInfo.CurrentCulture, "{{0,-{0}}}{{1}}", largestSize + 2); string tableLine; tableLine = String.Format( CultureInfo.CurrentCulture, formatString, HelpWindowResources.ParameterRequired, required); this.AddText(HelpParagraphBuilder.AddIndent(tableLine, 2), false); this.AddText("\r\n", false); //these are not applicable for Dsc Resource help if (helpCategory != HelpCategory.DscResource) { tableLine = String.Format( CultureInfo.CurrentCulture, formatString, HelpWindowResources.ParameterPosition, position); this.AddText(HelpParagraphBuilder.AddIndent(tableLine, 2), false); this.AddText("\r\n", false); tableLine = String.Format( CultureInfo.CurrentCulture, formatString, HelpWindowResources.ParameterDefautValue, defaultValue); this.AddText(HelpParagraphBuilder.AddIndent(tableLine, 2), false); this.AddText("\r\n", false); tableLine = String.Format( CultureInfo.CurrentCulture, formatString, HelpWindowResources.ParameterPipelineInput, pipelineinput); this.AddText(HelpParagraphBuilder.AddIndent(tableLine, 2), false); this.AddText("\r\n", false); tableLine = String.Format( CultureInfo.CurrentCulture, formatString, HelpWindowResources.ParameterAcceptWildcard, acceptWildcard); this.AddText(HelpParagraphBuilder.AddIndent(tableLine, 2), false); } this.AddText("\r\n\r\n", false); } this.AddText("\r\n\r\n", false); }
private void FormatMethodData(PSObject member, string name, out string memberText, out string description) { memberText = null; description = null; if (member == null || String.IsNullOrEmpty(name)) { return; } string returnType = null; StringBuilder parameterText = new StringBuilder(); //Get method return type PSObject returnTypeObject = HelpParagraphBuilder.GetPropertyObject(member, "returnValue") as PSObject; if (returnTypeObject != null) { PSObject returnTypeData = HelpParagraphBuilder.GetPropertyObject(returnTypeObject, "type") as PSObject; if (returnTypeData != null) { returnType = GetPropertyString(returnTypeData, "name"); } } //Get method description. PSObject[] methodDescriptions = HelpParagraphBuilder.GetPropertyObject(member, "introduction") as PSObject[]; if (methodDescriptions != null) { foreach (var methodDescription in methodDescriptions) { description = GetPropertyString(methodDescription, "Text"); //If we get an text we do not need to iterate more. if (!String.IsNullOrEmpty(description)) { break; } } } //Get method parameters. PSObject parametersObject = HelpParagraphBuilder.GetPropertyObject(member, "parameters") as PSObject; if (parametersObject != null) { PSObject[] paramObject = HelpParagraphBuilder.GetPropertyObject(parametersObject, "parameter") as PSObject[]; if (paramObject != null) { foreach (var param in paramObject) { string parameterName = GetPropertyString(param, "name"); string parameterType = null; PSObject parameterTypeData = HelpParagraphBuilder.GetPropertyObject(param, "type") as PSObject; if (parameterTypeData != null) { parameterType = GetPropertyString(parameterTypeData, "name"); //If there is no type for the parameter, we expect it is System.Object if (String.IsNullOrEmpty(parameterType)) { parameterType = "object"; } } string paramString = String.Format(CultureInfo.CurrentCulture, "[{0}] ${1},", parameterType, parameterName); parameterText.Append(paramString); } if (String.Compare(parameterText[parameterText.Length - 1].ToString(), ",", StringComparison.OrdinalIgnoreCase) == 0) { parameterText = parameterText.Remove(parameterText.Length - 1, 1); } } } memberText = String.Format(CultureInfo.CurrentCulture, " [{0}] {1}({2})\r\n", returnType, name, parameterText.ToString()); }
private void AddMembers(bool setting, string sectionTitle) { if (!setting || String.IsNullOrEmpty(sectionTitle)) { return; } PSObject memberRootObject = HelpParagraphBuilder.GetPropertyObject(this.psObj, "Members") as PSObject; if (memberRootObject == null) { return; } object[] memberObjects = HelpParagraphBuilder.GetPropertyObjectArray(memberRootObject, "member"); if (memberObjects == null) { return; } this.AddText(sectionTitle, true); this.AddText("\r\n", false); foreach (object memberObj in memberObjects) { string description = null; string memberText = null; PSObject member = memberObj as PSObject; if (member == null) { continue; } string name = GetPropertyString(member, "title"); string type = GetPropertyString(member, "type"); string propertyType = null; if (String.Compare("field", type, StringComparison.OrdinalIgnoreCase) == 0) { PSObject fieldData = HelpParagraphBuilder.GetPropertyObject(member, "fieldData") as PSObject; if (fieldData != null) { PSObject propertyTypeObject = HelpParagraphBuilder.GetPropertyObject(fieldData, "type") as PSObject; if (propertyTypeObject != null) { propertyType = GetPropertyString(propertyTypeObject, "name"); description = GetPropertyString(propertyTypeObject, "description"); } memberText = String.Format(CultureInfo.CurrentCulture, " [{0}] {1}\r\n", propertyType, name); } } else if (String.Compare("method", type, StringComparison.OrdinalIgnoreCase) == 0) { FormatMethodData(member, name, out memberText, out description); } if (!String.IsNullOrEmpty(memberText)) { this.AddText(HelpParagraphBuilder.AddIndent(""), false); this.AddText(memberText, true); if (description != null) { this.AddText(HelpParagraphBuilder.AddIndent(description, 2), false); this.AddText("\r\n", false); } this.AddText("\r\n", false); } } }
/// <summary> /// Adds the help examples segment /// </summary> /// <param name="setting">true if it should add the segment</param> /// <param name="sectionTitle">title of the section</param> private void AddExamples(bool setting, string sectionTitle) { if (!setting) { return; } PSObject exampleRootObject = HelpParagraphBuilder.GetPropertyObject(this.psObj, "Examples") as PSObject; if (exampleRootObject == null) { return; } object[] exampleObjects = HelpParagraphBuilder.GetPropertyObjectArray(exampleRootObject, "example"); if (exampleObjects == null || exampleObjects.Length == 0) { return; } this.AddText(sectionTitle, true); this.AddText("\r\n", false); foreach (object exampleObj in exampleObjects) { PSObject example = exampleObj as PSObject; if (example == null) { continue; } string introductionText = null; introductionText = GetTextFromArray(example, "introduction"); string codeText = GetPropertyString(example, "code"); string title = GetPropertyString(example, "title"); if (codeText == null) { continue; } if (title != null) { this.AddText(HelpParagraphBuilder.AddIndent(title), false); this.AddText("\r\n", false); } string codeLine = String.Format( CultureInfo.CurrentCulture, "{0}{1}\r\n\r\n", introductionText, codeText); this.AddText(HelpParagraphBuilder.AddIndent(codeLine), false); PSObject[] remarks = HelpParagraphBuilder.GetPropertyObject(example, "remarks") as PSObject[]; if (remarks == null) { continue; } foreach (PSObject remark in remarks) { string remarkText = GetPropertyString(remark, "text"); if (remarkText == null) { continue; } this.AddText(remarkText, false); this.AddText("\r\n", false); } } this.AddText("\r\n\r\n", false); }
/// <summary> /// Adds the help syntax segment /// </summary> /// <param name="setting">true if it should add the segment</param> /// <param name="sectionTitle">title of the section</param> private void AddSyntax(bool setting, string sectionTitle) { PSObject syntaxObject; if (!setting || (syntaxObject = HelpParagraphBuilder.GetPropertyObject(this.psObj, "Syntax") as PSObject) == null) { return; } object[] syntaxItemsObj = HelpParagraphBuilder.GetPropertyObjectArray(syntaxObject, "syntaxItem"); if (syntaxItemsObj == null || syntaxItemsObj.Length == 0) { return; } this.AddText(sectionTitle, true); this.AddText("\r\n", false); foreach (object syntaxItemObj in syntaxItemsObj) { PSObject syntaxItem = syntaxItemObj as PSObject; if (syntaxItem == null) { continue; } string commandName = GetPropertyString(syntaxItem, "name"); object[] parameterObjs = HelpParagraphBuilder.GetPropertyObjectArray(syntaxItem, "parameter"); if (commandName == null || parameterObjs == null || parameterObjs.Length == 0) { continue; } string commandStart = String.Format(CultureInfo.CurrentCulture, "{0} ", commandName); this.AddText(HelpParagraphBuilder.AddIndent(commandStart), false); foreach (object parameterObj in parameterObjs) { PSObject parameter = parameterObj as PSObject; if (parameter == null) { continue; } string parameterValue = GetPropertyString(parameter, "parameterValue"); string position = GetPropertyString(parameter, "position"); string required = GetPropertyString(parameter, "required"); string parameterName = GetPropertyString(parameter, "name"); if (position == null || required == null || parameterName == null) { continue; } string parameterType = parameterValue == null ? String.Empty : String.Format(CultureInfo.CurrentCulture, "<{0}>", parameterValue); string parameterOptionalOpenBrace, parameterOptionalCloseBrace; if (String.Equals(required, "true", StringComparison.OrdinalIgnoreCase)) { parameterOptionalOpenBrace = parameterOptionalCloseBrace = String.Empty; } else { parameterOptionalOpenBrace = "["; parameterOptionalCloseBrace = "]"; } string parameterNameOptionalOpenBrace, parameterNameOptionalCloseBrace; if (String.Equals(position, "named", StringComparison.OrdinalIgnoreCase)) { parameterNameOptionalOpenBrace = parameterNameOptionalCloseBrace = String.Empty; } else { parameterNameOptionalOpenBrace = "["; parameterNameOptionalCloseBrace = "]"; } string parameterPrefix = String.Format( CultureInfo.CurrentCulture, "{0}{1}-", parameterOptionalOpenBrace, parameterNameOptionalOpenBrace); this.AddText(parameterPrefix, false); this.AddText(parameterName, true); string parameterSuffix = String.Format( CultureInfo.CurrentCulture, "{0} {1}{2} ", parameterNameOptionalCloseBrace, parameterType, parameterOptionalCloseBrace); this.AddText(parameterSuffix, false); } string commonParametersText = String.Format( CultureInfo.CurrentCulture, "[<{0}>]\r\n\r\n", HelpWindowResources.CommonParameters); this.AddText(commonParametersText, false); } this.AddText("\r\n", false); }