/// <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);
}
