private static void AppendSyntaxChart(string cmdletName, string setName, CmdletParameterSetPartitions parameterSetPartitioning, StringBuilder sb)
{
var isCustomNamedSet = !setName.Equals(CmdletParameterSetPartitions.AllSetsKey);
var isDefaultSet = isCustomNamedSet && setName.Equals(parameterSetPartitioning.DefaultParameterSetName, StringComparison.Ordinal);
var setParameterNames = parameterSetPartitioning.ParameterNamesForSet(setName, parameterSetPartitioning.HasNamedParameterSets);
if (isCustomNamedSet)
{
sb.AppendFormat(
isDefaultSet
? "<div class=\"paramsetname\"><h4>{0} (Default)</h4>"
: "<div class=\"paramsetname\"><h4>{0}</h4>", setName);
}
sb.Append("<div class=\"syntaxblock\">");
// Microsoft cmdlets show params in syntax in defined but non-alpha order. Use the ordering we found
// during reflection here in the hope the sdk has them in 'most important' order. Also, if there is
// four or less params, keep the syntax on one line.
sb.AppendFormat("<div class=\"cmdlet\">{0}</div>", cmdletName);
var allParameters = parameterSetPartitioning.Parameters;
var paramCount = setParameterNames.Count;
if (paramCount > 0)
{
sb.Append("<div class=\"paramlist\">");
foreach (var p in allParameters)
{
if (!setParameterNames.Contains(p.CmdletParameterName))
{
continue;
}
sb.AppendFormat("<div class=\"{0}\">-{1} <{2}></div>",
paramCount < 5 ? "inlineParam" : "wrappedParam",
p.CmdletParameterName,
GetTypeDisplayName(p.PropertyType, false));
}
sb.Append("</div>");
}
sb.Append("</div>");
if (isCustomNamedSet)
{
sb.Append("</div>");
}
}
private static void WriteSyntax(XmlWriter writer, string cmdletName, CmdletParameterSetPartitions parameterSetPartitioning)
{
writer.WriteStartElement("syntax");
if (parameterSetPartitioning.HasNamedParameterSets)
{
var sets = parameterSetPartitioning.NamedParameterSets;
foreach (var set in sets)
{
WriteSyntaxItem(writer, cmdletName, set, parameterSetPartitioning);
}
}
else
{
WriteSyntaxItem(writer, cmdletName, CmdletParameterSetPartitions.AllSetsKey, parameterSetPartitioning);
}
writer.WriteEndElement();
}
private static void WriteSyntax(CmdletPageWriter writer, string cmdletName, CmdletParameterSetPartitions parameterSetPartitioning)
{
var sb = new StringBuilder();
if (parameterSetPartitioning.HasNamedParameterSets)
{
var sets = parameterSetPartitioning.NamedParameterSets;
foreach (var set in sets)
{
AppendSyntaxChart(cmdletName,
set,
parameterSetPartitioning,
sb);
}
}
else
{
AppendSyntaxChart(cmdletName, CmdletParameterSetPartitions.AllSetsKey, parameterSetPartitioning, sb);
}
writer.AddPageElement(CmdletPageWriter.SyntaxElementKey, sb.ToString());
}
protected override void GenerateHelper()
{
base.GenerateHelper();
if (string.IsNullOrEmpty(SDKHelpRoot))
{
SDKHelpRoot = "http://docs.aws.amazon.com/sdkfornet/v3/apidocs/";
}
else if (!SDKHelpRoot.EndsWith("/"))
{
SDKHelpRoot = SDKHelpRoot + "/";
}
Console.WriteLine("Generating web help documentation:");
Console.WriteLine(".... SDK help base URI set to {0}", SDKHelpRoot);
Console.WriteLine(".... writing doc output to {0}", OutputFolder);
var buildLogsPath = Path.Combine(this.Options.RootPath, "logs");
if (!Directory.Exists(buildLogsPath))
{
Directory.CreateDirectory(buildLogsPath);
}
var logFile = Path.Combine(buildLogsPath, Name + ".dll-WebHelp.log");
var oldWriter = Console.Out;
try
{
using (var consoleWriter = new StreamWriter(File.OpenWrite(logFile)))
{
Console.SetOut(consoleWriter);
CleanWebHelpOutputFolder(OutputFolder);
CopyWebHelpStaticFiles(OutputFolder);
CreateVersionInfoFile(Path.Combine(OutputFolder, "items"));
var tocWriter = new TOCWriter(Options, OutputFolder);
tocWriter.AddFixedSection();
Parallel.ForEach(CmdletTypes, (cmdletType) =>
{
var(moduleName, serviceName) = DetermineCmdletServiceOwner(cmdletType);
var cmdletInfo = InspectCmdletAttributes(cmdletType);
string synopsis = null;
if (cmdletInfo.AWSCmdletAttribute == null)
{
Console.WriteLine("Unable to find AWSCmdletAttribute for type " + cmdletType.FullName);
}
else
{
var cmdletReturnAttributeType = cmdletInfo.AWSCmdletAttribute.GetType();
synopsis =
cmdletReturnAttributeType.GetProperty("Synopsis").GetValue(cmdletInfo.AWSCmdletAttribute, null) as
string;
}
foreach (var cmdletAttribute in cmdletInfo.CmdletAttributes)
{
var typeDocumentation = DocumentationUtils.GetTypeDocumentation(cmdletType,
AssemblyDocumentation);
typeDocumentation = DocumentationUtils.FormatXMLForPowershell(typeDocumentation, true);
Console.WriteLine($"Cmdlet = {cmdletType.FullName}");
Console.WriteLine($"Documentation = {typeDocumentation}");
var cmdletName = cmdletAttribute.VerbName + "-" + cmdletAttribute.NounName;
var allProperties = GetRootSimpleProperties(cmdletType);
var parameterPartitioning = new CmdletParameterSetPartitions(allProperties, cmdletAttribute.DefaultParameterSetName);
var serviceAbbreviation = GetServiceAbbreviation(cmdletType);
var cmdletPageWriter = new CmdletPageWriter(Options, OutputFolder, serviceName, moduleName, cmdletName);
WriteDetails(cmdletPageWriter, typeDocumentation, synopsis, cmdletInfo.AWSCmdletAttribute);
WriteSyntax(cmdletPageWriter, cmdletName, parameterPartitioning);
WriteParameters(cmdletPageWriter, cmdletName, allProperties, false);
WriteParameters(cmdletPageWriter, cmdletName, allProperties, true);
WriteOutputs(cmdletPageWriter, cmdletInfo.AWSCmdletOutputAttributes);
WriteNotes(cmdletPageWriter);
WriteExamples(cmdletPageWriter, cmdletName);
WriteRelatedLinks(cmdletPageWriter, serviceAbbreviation, cmdletName);
cmdletPageWriter.Write();
lock (tocWriter)
{
var legacyAlias = InspectForLegacyAliasAttribution(moduleName, cmdletName, cmdletInfo.AWSCmdletAttribute);
tocWriter.AddServiceCmdlet(moduleName, serviceName, cmdletName, cmdletPageWriter.GetTOCID(), synopsis, legacyAlias);
}
}
});
tocWriter.Write();
WriteLegacyAliasesPage();
}
}
finally
{
Console.SetOut(oldWriter);
}
}
protected override void GenerateHelper()
{
Console.WriteLine("Generating Native PowerShell help (Get-Help) documentation file");
base.GenerateHelper();
var buildLogsPath = Path.Combine(this.Options.RootPath, "logs");
if (!Directory.Exists(buildLogsPath))
{
Directory.CreateDirectory(buildLogsPath);
}
var logFilename = Path.Combine(buildLogsPath, Name + ".dll-Help.log");
var oldWriter = Console.Out;
try
{
using (var consoleWriter = new StreamWriter(File.OpenWrite(logFilename)))
{
Console.SetOut(consoleWriter);
var outputFile = Path.Combine(this.OutputFolder, Name + PsHelpFilenameTail);
var settings = new XmlWriterSettings
{
Indent = true
};
using (var psHelpWriter = new XmlTextWriter(outputFile, Encoding.UTF8))
{
psHelpWriter.Formatting = Formatting.Indented;
psHelpWriter.WriteStartElement("helpItems");
psHelpWriter.WriteAttributeString("schema", "maml");
Parallel.ForEach(CmdletTypes, (cmdletType) =>
{
CmdletInfo cmdletInfo = InspectCmdletAttributes(cmdletType);
using (StringWriter sectionWriter = new StringWriter())
using (var sectionXmlWriter = XmlWriter.Create(sectionWriter, new XmlWriterSettings()
{
OmitXmlDeclaration = true,
ConformanceLevel = ConformanceLevel.Fragment,
CloseOutput = true
}))
{
string synopsis = null;
if (cmdletInfo.AWSCmdletAttribute == null)
{
Console.WriteLine("Unable to find AWSCmdletAttribute for type " + cmdletType.FullName);
}
else
{
var cmdletReturnAttributeType = cmdletInfo.AWSCmdletAttribute.GetType();
synopsis = cmdletReturnAttributeType.GetProperty("Synopsis").GetValue(cmdletInfo.AWSCmdletAttribute, null) as string;
}
foreach (var cmdletAttribute in cmdletInfo.CmdletAttributes)
{
sectionXmlWriter.WriteStartElement("command");
sectionXmlWriter.WriteAttributeString("xmlns", "maml", null, "http://schemas.microsoft.com/maml/2004/10");
sectionXmlWriter.WriteAttributeString("xmlns", "command", null, "http://schemas.microsoft.com/maml/dev/command/2004/10");
sectionXmlWriter.WriteAttributeString("xmlns", "dev", null, "http://schemas.microsoft.com/maml/dev/2004/10");
{
var typeDocumentation = DocumentationUtils.GetTypeDocumentation(cmdletType, AssemblyDocumentation);
typeDocumentation = DocumentationUtils.FormatXMLForPowershell(typeDocumentation);
Console.WriteLine($"Cmdlet = {cmdletType.FullName}");
Console.WriteLine($"Documentation = {typeDocumentation}");
var cmdletName = cmdletAttribute.VerbName + "-" + cmdletAttribute.NounName;
var allProperties = GetRootSimpleProperties(cmdletType);
var parameterPartitioning = new CmdletParameterSetPartitions(allProperties, cmdletAttribute.DefaultParameterSetName);
var serviceAbbreviation = GetServiceAbbreviation(cmdletType);
WriteDetails(sectionXmlWriter, cmdletAttribute, typeDocumentation, cmdletName, synopsis);
WriteSyntax(sectionXmlWriter, cmdletName, parameterPartitioning);
WriteParameters(sectionXmlWriter, cmdletName, allProperties);
WriteReturnValues(sectionXmlWriter, cmdletInfo.AWSCmdletOutputAttributes);
WriteRelatedLinks(sectionXmlWriter, serviceAbbreviation, cmdletName);
WriteExamples(sectionXmlWriter, cmdletName);
}
sectionXmlWriter.WriteEndElement();
}
sectionXmlWriter.Close();
lock (psHelpWriter)
{
psHelpWriter.WriteRaw(sectionWriter.ToString());
}
}
});
psHelpWriter.WriteEndElement();
}
Console.WriteLine($"Verifying help file {outputFile} using XmlDocument...");
try
{
var document = new XmlDocument();
document.Load(outputFile);
}
catch (Exception e)
{
Logger.LogError(e, $"Error when loading file {outputFile} as XmlDocument");
}
}
}
finally
{
Console.SetOut(oldWriter);
}
}
private static void WriteSyntaxItem(XmlWriter writer, string cmdletName, string setName, CmdletParameterSetPartitions parameterSetPartitioning)
{
var isCustomNamedSet = !setName.Equals(CmdletParameterSetPartitions.AllSetsKey);
var isDefaultSet = isCustomNamedSet && setName.Equals(parameterSetPartitioning.DefaultParameterSetName, StringComparison.Ordinal);
var setParameterNames = parameterSetPartitioning.ParameterNamesForSet(setName, parameterSetPartitioning.HasNamedParameterSets);
writer.WriteStartElement("syntaxItem");
{
writer.WriteElementString("name", cmdletName);
var allParameters = parameterSetPartitioning.Parameters;
// Microsoft cmdlets show params in syntax in defined but non-alpha order. Use the ordering we found
// during reflection here in the hope the sdk has them in 'most important' order
foreach (var parameter in allParameters)
{
if (!setParameterNames.Contains(parameter.CmdletParameterName))
{
continue;
}
InspectParameter(parameter, out var isRequiredForParametersets, out var pipelineInput, out var position, out var aliases);
var isRequiredForCurrentParameterset = isRequiredForParametersets != null && (isRequiredForParametersets.Count == 0 || isRequiredForParametersets.Contains(setName));
writer.WriteStartElement("parameter");
{
writer.WriteAttributeString("required", isRequiredForCurrentParameterset.ToString());
writer.WriteAttributeString("variableLength", "false");
writer.WriteAttributeString("globbing", "false");
writer.WriteAttributeString("pipelineInput", pipelineInput);
writer.WriteAttributeString("position", position);
writer.WriteElementString("name", parameter.CmdletParameterName);
writer.WriteStartElement("description");
{
writer.WriteRawElementString("para", parameter.PowershellDocumentation);
}
writer.WriteEndElement();
writer.WriteStartElement("parameterValue");
{
writer.WriteAttributeString("required", "true");
writer.WriteAttributeString("variableLength", "false");
writer.WriteString(parameter.PropertyTypeName);
}
writer.WriteEndElement();
}
writer.WriteEndElement();
}
}
writer.WriteEndElement();
}
protected override void GenerateHelper()
{
Console.WriteLine("Generating Native PowerShell help (Get-Help) documentation file");
base.GenerateHelper();
var buildLogsPath = Path.Combine(this.Options.RootPath, "logs");
if (!Directory.Exists(buildLogsPath))
{
Directory.CreateDirectory(buildLogsPath);
}
var logFilename = Path.Combine(buildLogsPath, Name + ".dll-Help.log");
var oldWriter = Console.Out;
try
{
using (var consoleWriter = new StreamWriter(File.OpenWrite(logFilename)))
{
Console.SetOut(consoleWriter);
var outputFile = Path.Combine(this.OutputFolder, Name + PsHelpFilenameTail);
var settings = new XmlWriterSettings
{
Indent = true
};
using (var psHelpWriter = new XmlTextWriter(outputFile, Encoding.UTF8))
{
psHelpWriter.Formatting = Formatting.Indented;
psHelpWriter.WriteStartElement("helpItems");
psHelpWriter.WriteAttributeString("schema", "maml");
foreach (var cmdletType in CmdletTypes)
{
InspectCmdletAttributes(cmdletType);
string synopsis = null;
if (AWSCmdletAttribute == null)
{
Console.WriteLine("Unable to find AWSCmdletAttribute for type " + cmdletType.FullName);
}
else
{
var cmdletReturnAttributeType = AWSCmdletAttribute.GetType();
synopsis = cmdletReturnAttributeType.GetProperty("Synopsis").GetValue(AWSCmdletAttribute, null) as string;
}
foreach (var cmdletAttribute in CmdletAttributes)
{
psHelpWriter.WriteStartElement("command");
psHelpWriter.WriteAttributeString("xmlns", "maml", null, "http://schemas.microsoft.com/maml/2004/10");
psHelpWriter.WriteAttributeString("xmlns", "command", null, "http://schemas.microsoft.com/maml/dev/command/2004/10");
psHelpWriter.WriteAttributeString("xmlns", "dev", null, "http://schemas.microsoft.com/maml/dev/2004/10");
{
var hasDynamicParams = DynamicParamsType.IsAssignableFrom(cmdletType);
var typeDocumentation = DocumentationUtils.GetTypeDocumentation(cmdletType, AssemblyDocumentation);
typeDocumentation = DocumentationUtils.FormatXMLForPowershell(typeDocumentation);
Console.WriteLine("Cmdlet = {0}", cmdletType.FullName);
if (hasDynamicParams)
{
Console.WriteLine("This cmdlet has dynamic parameters!");
}
Console.WriteLine("Documentation = {0}", typeDocumentation);
var cmdletName = cmdletAttribute.VerbName + "-" + cmdletAttribute.NounName;
var allProperties = GetRootSimpleProperties(cmdletType);
var parameterPartitioning = new CmdletParameterSetPartitions(allProperties, cmdletAttribute.DefaultParameterSetName);
var serviceAbbreviation = GetServiceAbbreviation(cmdletType);
WriteDetails(psHelpWriter, cmdletAttribute, typeDocumentation, cmdletName, synopsis);
WriteSyntax(psHelpWriter, cmdletName, parameterPartitioning);
WriteParameters(psHelpWriter, cmdletName, allProperties);
WriteReturnValues(psHelpWriter, AWSCmdletOutputAttributes);
WriteRelatedLinks(psHelpWriter, serviceAbbreviation, cmdletName);
WriteExamples(psHelpWriter, cmdletName);
}
psHelpWriter.WriteEndElement();
}
}
psHelpWriter.WriteEndElement();
}
Console.WriteLine("Verifying help file {0} using XmlDocument...", outputFile);
try
{
var document = new XmlDocument();
document.Load(outputFile);
}
catch (Exception e)
{
Logger.LogError(e, "Error when loading file {0} as XmlDocument", outputFile);
}
}
}
finally
{
Console.SetOut(oldWriter);
}
}
