protected override void Write(MamlRenderer renderer, ListBlock listBlock)
{
renderer.EnsureLine();
if (listBlock.IsOrdered)
{
renderer.Push(MamlElements.list, new Dictionary <string, string> {
["class"] = "ordered"
});
}
else
{
renderer.Push(MamlElements.list, new Dictionary <string, string> {
["class"] = "bullet"
});
}
foreach (var item in listBlock)
{
var listItem = (ListItemBlock)item;
renderer.EnsureLine();
renderer.Push(MamlElements.listItem);
renderer.WriteChildren(listItem);
renderer.PopTo(MamlElements.listItem);
}
renderer.PopTo(MamlElements.list);
}
protected override void Write(MamlRenderer renderer, Markdig.Extensions.Figures.FigureCaption obj)
{
renderer.Push(MamlElements.para);
renderer.WriteLeafInline(obj);
renderer.EnsureLine();
renderer.PopTo(MamlElements.para);
}
public void RendererProduceNameAndSynopsis()
{
MamlRenderer renderer = new MamlRenderer();
MamlCommand command = new MamlCommand()
{
Name = "Get-Foo",
Synopsis = "This is the synopsis",
Description = "This is a long description."
};
command.Parameters.Add(new MamlParameter()
{
Type = "String",
Name = "Name",
Required = true,
Description = "Parameter Description.",
VariableLength = true,
Globbing = true,
PipelineInput = "True (ByValue)",
Position = "1",
Aliases = new string [] { "GF", "Foos", "Do" },
}
);
command.Inputs.Add(new MamlInputOutput()
{
TypeName = "String",
Description = "Input Description goes here!"
}
);
command.Outputs.Add(new MamlInputOutput()
{
TypeName = "String",
Description = "Output Description goes here!"
}
);
command.Examples.Add(new MamlExample()
{
Title = "Example 1",
Code = "PS:> Get-Help -YouNeedIt",
Remarks = "This does stuff!"
}
);
command.Links.Add(new MamlLink()
{
LinkName = "PowerShell made by Microsoft Hackathon",
LinkUri = "www.microsoft.com"
}
);
string maml = renderer.MamlModelToString(new [] { command });
string[] name = EndToEndTests.GetXmlContent(maml, "/helpItems/command:command/command:details/command:name");
Assert.Equal(1, name.Length);
Assert.Equal("Get-Foo", name[0]);
string[] synopsis = EndToEndTests.GetXmlContent(maml, "/helpItems/command:command/command:details/maml:description/maml:para");
Assert.Equal(1, synopsis.Length);
Assert.Equal("This is the synopsis", synopsis[0]);
}
protected override void Write(MamlRenderer renderer, QuoteBlock obj)
{
renderer.EnsureLine();
renderer.Push(MamlElements.quote);
renderer.WriteChildren(obj);
renderer.PopTo(MamlElements.quote);
}
protected override void Write(MamlRenderer renderer, AutolinkInline obj)
{
renderer.Push(MamlElements.externalLink);
renderer.Push(MamlElements.linkUri);
renderer.Write(obj.Url);
renderer.PopTo(MamlElements.linkUri);
renderer.PopTo(MamlElements.externalLink);
}
protected override void Write(MamlRenderer renderer, CodeBlock obj)
{
renderer.EnsureLine();
renderer.Push(MamlElements.code);
renderer.WriteLeafRawLines(obj, true, true);
renderer.PopTo(MamlElements.code);
}
protected override void Write(MamlRenderer renderer, MathBlock obj)
{
string formulaText = string.Empty; // obj.Content.Text.Substring(obj.Content.Start, obj.Content.Length);
for (int i = 0; i < obj.Lines.Count; ++i)
{
var l = obj.Lines.Lines[i];
formulaText += l.Slice.Text.Substring(l.Slice.Start, l.Slice.Length);
}
if (string.IsNullOrEmpty(formulaText))
{
return;
}
var formulaService = Current.GetRequiredService <ILaTeXFormulaImageStreamProvider>();
var(stream, placement, offset, width, height) = formulaService.Parse(formulaText, renderer.BodyTextFontFamily, renderer.BodyTextFontSize, 192, renderer.IsIntendedForHelp1File);
if (null == stream)
{
return;
}
stream.Seek(0, SeekOrigin.Begin);
var streamHash = MemoryStreamImageProxy.ComputeStreamHash(stream);
stream.Seek(0, SeekOrigin.Begin);
try
{
renderer.StorePngImageFile(stream, streamHash);
stream.Close();
}
finally
{
stream.Dispose();
}
// now render to Maml file
string localUrl = "../media/" + streamHash + ".png";
var attributes = new Dictionary <string, string>
{
{ "src", localUrl },
{ "width", System.Xml.XmlConvert.ToString(width) },
{ "height", System.Xml.XmlConvert.ToString(height) }
};
renderer.Push(MamlElements.markup);
renderer.Push(MamlElements.a, new[] { new KeyValuePair <string, string>("href", renderer.ImageTopicFileGuid + ".htm#" + streamHash) });
renderer.Push(MamlElements.img, attributes);
renderer.PopTo(MamlElements.markup);
}
/// <inheritdoc/>
protected override void Write(MamlRenderer renderer, LiteralInline obj)
{
if (obj.Content.IsEmpty)
{
return;
}
renderer.WriteEscape(obj.Content.ToString());
}
protected override void Write(MamlRenderer renderer, ThematicBreakBlock obj)
{
// since there is no direct equivalent to a thematic break in Maml,
// here we use a paragraph with 80 underlines
renderer.Push(MamlElements.markup);
renderer.Write("<hr/>");
renderer.PopTo(MamlElements.markup);
}
public void RendererProducePaddedExampleTitle()
{
MamlRenderer renderer = new MamlRenderer();
MamlCommand command = new MamlCommand()
{
Name = "Get-Foo",
Synopsis = new SectionBody("This is a description")
};
var example1 = new MamlExample()
{
Title = "Example 1",
Code = new[] { new MamlCodeBlock("PS:> Get-Help -YouNeedIt") },
Remarks = "This does stuff!"
};
var example10 = new MamlExample()
{
Title = "Example 10",
Code = new[] { new MamlCodeBlock("PS:> Get-Help -YouNeedIt") },
Remarks = "This does stuff!"
};
var exampleWithTitle = new MamlExample()
{
Title = "Example 11: With a title",
Code = new[] { new MamlCodeBlock("PS:> Get-Help -YouNeedIt") },
Remarks = "This does stuff!"
};
var exampleWithLongTitle = new MamlExample()
{
Title = "Example 12: ".PadRight(66, 'A'),
Code = new[] { new MamlCodeBlock("PS:> Get-Help -YouNeedIt") },
Remarks = "This does stuff!"
};
command.Examples.Add(example1);
command.Examples.Add(example10);
command.Examples.Add(exampleWithTitle);
command.Examples.Add(exampleWithLongTitle);
string maml = renderer.MamlModelToString(new[] { command });
// Check that example header is padded by dashes (-) unless to long
string[] example = EndToEndTests.GetXmlContent(maml, "/msh:helpItems/command:command/command:examples/command:example/maml:title");
Assert.Equal(4, example.Length);
Assert.Equal(63, example[0].Length);
Assert.Equal(64, example[1].Length);
Assert.Equal(66, example[3].Length);
Assert.Matches($"^-+ {example1.Title} -+$", example[0]);
Assert.Matches($"^-+ {example10.Title} -+$", example[1]);
Assert.Matches($"^-+ {exampleWithTitle.Title} -+$", example[2]);
Assert.Matches($"^{exampleWithLongTitle.Title}$", example[3]);
}
protected override void Write(MamlRenderer renderer, EmphasisInline obj)
{
MamlElement mamlElement = null;
switch (obj.DelimiterChar)
{
case '*':
case '_':
if (obj.IsDouble)
{
mamlElement = MamlElements.legacyBold;
}
else
{
mamlElement = MamlElements.legacyItalic;
}
break;
case '~':
if (obj.IsDouble)
{
mamlElement = MamlElements.legacyStrikethrough;
}
else
{
mamlElement = MamlElements.subscript;
}
break;
case '^':
mamlElement = MamlElements.superscript;
break;
case '+':
// Inserted style
mamlElement = MamlElements.legacyUnderline;
break;
case '=':
// Marked style
break;
}
if (null != mamlElement)
{
renderer.Push(mamlElement);
}
renderer.WriteChildren(obj);
if (null != mamlElement)
{
renderer.PopTo(mamlElement);
}
}
protected override void Write(MamlRenderer renderer, LineBreakInline obj)
{
if (obj.IsHard)
{
renderer.WriteLine("<lineBreak/>");
}
else
{
renderer.WriteLine();
}
}
protected override void Write(MamlRenderer renderer, HeadingBlock obj)
{
bool newFileWasStarted = renderer.TryStartNewMamlFile(obj);
if (newFileWasStarted)
{
}
else
{
// Ensure we have the sections element somewhere down the line ...
// we need (obj.Level - renderer.SplitLevel) section elements down the stack
int numberOfSectionsElementsRequired = obj.Level - renderer.SplitLevel - 1;
int numberOfSectionsElementsOnStack = renderer.NumberOfElementsOnStack(MamlElements.sections);
// Push sections element if required
for (int i = 0; i < numberOfSectionsElementsRequired - numberOfSectionsElementsOnStack; ++i)
{
renderer.Push(MamlElements.sections);
}
if (numberOfSectionsElementsOnStack > 0 && numberOfSectionsElementsRequired > 0)
{
// Or pop sections elements if required
for (int i = 0; i < numberOfSectionsElementsOnStack - numberOfSectionsElementsRequired; ++i)
{
renderer.PopToBefore(MamlElements.sections);
}
}
if (numberOfSectionsElementsRequired == 0)
{
renderer.PopToBefore(MamlElements.developerConceptualDocument);
}
// Find a unique address in order for AutoOutline to work
var attr = (Markdig.Renderers.Html.HtmlAttributes)obj.GetData(typeof(Markdig.Renderers.Html.HtmlAttributes));
string uniqueAddress = attr?.Id; // this header has a user defined address
if (string.IsNullOrEmpty(uniqueAddress))
{
renderer.HeaderGuids.TryGetValue(obj.Span.Start, out uniqueAddress); // use the guid generated from the hierarchy of titles
}
if (string.IsNullOrEmpty(uniqueAddress))
{
uniqueAddress = Guid.NewGuid().ToString(); // fallback (should not happen): Create Guid
}
renderer.Push(MamlElements.section, new[] { new KeyValuePair <string, string>("address", uniqueAddress) });
renderer.Push(MamlElements.title);
renderer.WriteLeafInline(obj);
renderer.EnsureLine();
renderer.PopTo(MamlElements.title);
renderer.Push(MamlElements.content);
}
}
protected override void Write(MamlRenderer renderer, ParagraphBlock obj)
{
if (!renderer.IsFirstInContainer)
{
renderer.EnsureLine();
}
renderer.Push(MamlElements.para);
renderer.WriteLeafInline(obj);
renderer.EnsureLine();
renderer.PopTo(MamlElements.para);
}
/// <summary>
/// This is a helper method to do all 3 steps.
/// </summary>
/// <param name="markdown"></param>
/// <returns></returns>
public static string MarkdownStringToMamlString(string markdown)
{
var parser = new MarkdownParser();
var transformer = new ModelTransformerVersion2();
var renderer = new MamlRenderer();
var markdownModel = parser.ParseString(new string[] { markdown });
var mamlModel = transformer.NodeModelToMamlModel(markdownModel);
string maml = renderer.MamlModelToString(mamlModel);
return(maml);
}
public void RendererProduceEscapeXmlSpecialChars()
{
MamlRenderer renderer = new MamlRenderer();
MamlCommand command = new MamlCommand()
{
Name = "Get-Foo",
Synopsis = new SectionBody("<port&number>") // < and > should be properly escaped
};
string maml = renderer.MamlModelToString(new[] { command });
string[] synopsis = EndToEndTests.GetXmlContent(maml, "/msh:helpItems/command:command/command:details/maml:description/maml:para");
Assert.Single(synopsis);
Assert.Equal(command.Synopsis.Text, synopsis[0]);
}
public void ProduceNameAndSynopsis()
{
string maml = MamlRenderer.MarkdownStringToMamlString(@"
# Get-Foo
## Synopsis
This is Synopsis
");
string[] name = GetXmlContent(maml, "/helpItems/command:command/command:details/command:name");
Assert.Equal(1, name.Length);
Assert.Equal("Get-Foo", name[0]);
string[] synopsis = GetXmlContent(maml, "/helpItems/command:command/command:details/maml:description/maml:para");
Assert.Equal(1, synopsis.Length);
Assert.Equal("This is Synopsis", synopsis[0]);
}
public void RendererProduceSyntaxAndParameter()
{
MamlRenderer renderer = new MamlRenderer();
MamlCommand command = new MamlCommand()
{
Name = "Get-Foo",
};
var param1 = new MamlParameter()
{
Type = "String",
Name = "Param1",
Position = ""
};
var param2 = new MamlParameter()
{
Type = "System.Int32",
Name = "Param2",
Position = "Named"
};
command.Parameters.Add(param1);
command.Parameters.Add(param2);
var syntax = new MamlSyntax();
syntax.Parameters.Add(param1);
syntax.Parameters.Add(param2);
command.Syntax.Add(syntax);
string maml = renderer.MamlModelToString(new[] { command });
string[] syntaxItemName = EndToEndTests.GetXmlContent(maml, "/msh:helpItems/command:command/command:syntax/command:syntaxItem/maml:name");
Assert.Single(syntaxItemName);
Assert.Equal("Get-Foo", syntaxItemName[0]);
string[] nameSyntax = EndToEndTests.GetXmlContent(maml, "/msh:helpItems/command:command/command:syntax/command:syntaxItem/command:parameter/maml:name");
Assert.Equal(2, nameSyntax.Length);
Assert.Equal("Param1", nameSyntax[0]);
Assert.Equal("Param2", nameSyntax[1]);
string[] nameParam = EndToEndTests.GetXmlContent(maml, "/msh:helpItems/command:command/command:parameters/command:parameter/maml:name");
Assert.Equal(2, nameParam.Length);
Assert.Equal("Param1", nameParam[0]);
Assert.Equal("Param2", nameParam[1]);
}
public void ProduceMultilineDescription()
{
string maml = MamlRenderer.MarkdownStringToMamlString(@"
# Get-Foo
## Synopsis
This is Synopsis, but it doesn't matter in this test
## DESCRIPTION
Hello,
I'm a multiline description.
And this is my last line.
");
string[] description = GetXmlContent(maml, "/helpItems/command:command/maml:description/maml:para");
Assert.Equal(3, description.Length);
}
public void CanUseSharpInsideParagraphs()
{
string maml = MamlRenderer.MarkdownStringToMamlString(@"
# Get-Foo
## Synopsis
This is Synopsis #hashtagNotAHeader.
## DESCRIPTION
I'm description
");
string[] description = GetXmlContent(maml, "/helpItems/command:command/maml:description/maml:para");
Assert.Equal(1, description.Length);
Assert.Equal("I'm description", description[0]);
string[] synopsis = GetXmlContent(maml, "/helpItems/command:command/command:details/maml:description/maml:para");
Assert.Equal(1, synopsis.Length);
Assert.Equal("This is Synopsis #hashtagNotAHeader.", synopsis[0]);
}
protected override void Write(MamlRenderer renderer, Table table)
{
renderer.Push(MamlElements.table);
renderer.Push(MamlElements.tableHeader);
foreach (TableRow row in table)
{
if (row.IsHeader)
{
renderer.Push(MamlElements.row);
foreach (TableCell cell in row)
{
renderer.Push(MamlElements.entry);
renderer.Write(cell);
renderer.PopTo(MamlElements.entry);
}
renderer.PopTo(MamlElements.row);
}
}
renderer.PopTo(MamlElements.tableHeader);
foreach (TableRow row in table)
{
if (!row.IsHeader)
{
renderer.Push(MamlElements.row);
foreach (TableCell cell in row)
{
renderer.Push(MamlElements.entry);
renderer.Write(cell);
renderer.PopTo(MamlElements.entry);
}
renderer.PopTo(MamlElements.row);
}
}
renderer.PopTo(MamlElements.table);
}
/// <inheritdoc/>
protected override void Write(MamlRenderer renderer, LinkInline link)
{
var url = link.GetDynamicUrl != null?link.GetDynamicUrl() ?? link.Url : link.Url;
if (link.IsImage)
{
RenderImage(renderer, link, url);
}
else // link is not an image
{
if (Uri.IsWellFormedUriString(url, UriKind.RelativeOrAbsolute))
{
renderer.Push(MamlElements.externalLink);
renderer.Push(MamlElements.linkText);
renderer.WriteChildren(link);
renderer.PopTo(MamlElements.linkText);
renderer.Push(MamlElements.linkUri);
renderer.Write(url);
renderer.PopTo(MamlElements.linkUri);
renderer.PopTo(MamlElements.externalLink);
}
else // not a well formed Uri String - then it is probably a fragment reference
{
// the challenge here is to find out where (in which file) our target is. The file might even not be defined in the moment
var(fileGuid, localUrl) = renderer.FindFragmentLink(url);
string totalAddress = string.Empty;
if (null != fileGuid && null != localUrl)
{
totalAddress = fileGuid + "#" + localUrl;
}
renderer.Push(MamlElements.link, new[] { new KeyValuePair <string, string>("xlink:href", totalAddress) });
renderer.WriteChildren(link);
renderer.PopTo(MamlElements.link);
}
}
}
/// <summary>
/// Exports the specified <see cref="TextDocument"/> to an external markdown file.
/// </summary>
/// <param name="document">The document to export.</param>
/// <param name="fileName">Full name of the Maml file to export to. Note that if exporting to multiple Maml files,
/// this is the base file name only; the file names will be derived from this name.</param>
/// <param name="errors">A list that collects error messages.</param>
public void Export(TextDocument document, string fileName, List <MarkdownError> errors = null)
{
if (null == document)
{
throw new ArgumentNullException(nameof(document));
}
if (string.IsNullOrEmpty(fileName))
{
throw new ArgumentNullException(nameof(fileName));
}
var basePathName = Path.GetDirectoryName(fileName);
if (ExpandChildDocuments)
{
document = ChildDocumentExpander.ExpandDocumentToNewDocument(document, errors: errors);
}
if (RenumerateFigures)
{
document.SourceText = FigureRenumerator.RenumerateFigures(document.SourceText);
}
// remove the old content
if (EnableRemoveOldContentsOfContentFolder)
{
var fullContentFolderName = Path.Combine(basePathName, ContentFolderName);
MamlRenderer.RemoveOldContentsOfContentFolder(fullContentFolderName);
}
// remove old images
var fullImageFolderName = Path.Combine(basePathName, ImageFolderName);
if (EnableRemoveOldContentsOfImageFolder)
{
MamlRenderer.RemoveOldContentsOfImageFolder(fullImageFolderName);
}
if (!Directory.Exists(fullImageFolderName))
{
Directory.CreateDirectory(fullImageFolderName);
}
// First, export the images
var(oldToNewImageUrl, listOfReferencedImageFileNames) = ExportImages(document, basePathName);
// now export the markdown document as Maml file(s)
// first parse it with Markdig
var pipeline = new MarkdownPipelineBuilder();
pipeline = MarkdownUtilities.UseSupportedExtensions(pipeline);
var markdownDocument = Markdig.Markdown.Parse(document.SourceText, pipeline.Build());
var renderer = new MamlRenderer(
projectOrContentFileName: fileName,
contentFolderName: ContentFolderName,
contentFileNameBase: ContentFileNameBase,
imageFolderName: ImageFolderName,
splitLevel: SplitLevel,
enableHtmlEscape: EnableHtmlEscape,
autoOutline: EnableAutoOutline,
enableLinkToPreviousSection: EnableLinkToPreviousSection,
linkToPreviousSectionLabelText: LinkToPreviousSectionLabelText,
enableLinkToNextSection: EnableLinkToNextSection,
linkToNextSectionLabelText: LinkToNextSectionLabelText,
imagesFullFileNames: listOfReferencedImageFileNames,
oldToNewImageUris: oldToNewImageUrl,
bodyTextFontFamily: BodyTextFontFamily,
bodyTextFontSize: BodyTextFontSize,
isIntendedForHelp1File: IsIntendedForHtmlHelp1File
);
renderer.Render(markdownDocument);
}
private void RenderImage(MamlRenderer renderer, LinkInline link, string url)
{
double?width = null, height = null;
if (link.ContainsData(typeof(Markdig.Renderers.Html.HtmlAttributes)))
{
var htmlAttributes = (Markdig.Renderers.Html.HtmlAttributes)link.GetData(typeof(Markdig.Renderers.Html.HtmlAttributes));
if (null != htmlAttributes.Properties)
{
foreach (var entry in htmlAttributes.Properties)
{
switch (entry.Key.ToLowerInvariant())
{
case "width":
width = GetLength(entry.Value);
break;
case "height":
height = GetLength(entry.Value);
break;
}
}
}
}
if (null != renderer.OldToNewImageUris && renderer.OldToNewImageUris.ContainsKey(url))
{
url = renderer.OldToNewImageUris[url];
}
if (width == null && height == null) // if we include the image in its native resolution, we do not need a link to the native resolution image
{
string localUrl = System.IO.Path.GetFileNameWithoutExtension(url);
renderer.Push(MamlElements.mediaLinkInline);
renderer.Push(MamlElements.image, new[] { new KeyValuePair <string, string>("xlink:href", localUrl) });
renderer.PopTo(MamlElements.image);
renderer.PopTo(MamlElements.mediaLinkInline);
}
else // width or height or both specified
{
string localUrl = "../media/" + System.IO.Path.GetFileName(url);
var attributes = new Dictionary <string, string>
{
{ "src", localUrl }
};
if (width.HasValue)
{
attributes.Add("width", System.Xml.XmlConvert.ToString(Math.Round(width.Value)));
}
if (height.HasValue)
{
attributes.Add("height", System.Xml.XmlConvert.ToString(height.Value));
}
renderer.Push(MamlElements.markup);
renderer.Push(MamlElements.a, new[] { new KeyValuePair <string, string>("href", renderer.ImageTopicFileGuid + ".htm#" + System.IO.Path.GetFileNameWithoutExtension(url)) });
renderer.Push(MamlElements.img, attributes);
renderer.PopTo(MamlElements.markup);
}
}
protected override void Write(MamlRenderer renderer, CodeInline obj)
{
renderer.Push(MamlElements.codeInline);
renderer.WriteEscape(obj.Content);
renderer.PopTo(MamlElements.codeInline);
}
public void CanProcessAddHistoryAddSnapinMarkdownWithoutErrors()
{
string maml = MamlRenderer.MarkdownStringToMamlString(@"
# Add-History
## SYNOPSIS
Appends entries to the session history.
## DESCRIPTION
The Add-History cmdlet adds entries to the end of the session history, that is, the list of commands entered during the current session.
You can use the Get-History cmdlet to get the commands and pass them to Add-History, or you can export the commands to a CSV or XML file, then import the commands, and pass the imported file to Add-History. You can use this cmdlet to add specific commands to the history or to create a single history file that includes commands from more than one session.
## PARAMETERS
### InputObject [PSObject[]]
```powershell
[Parameter(
Position = 1,
ValueFromPipeline = $true,
ParameterSetName = 'Set 1')]
```
Adds the specified HistoryInfo object to the session history. You can use this parameter to submit a HistoryInfo object, such as the ones that are returned by the Get-History, Import-Clixml, or Import-Csv cmdlets, to Add-History.
### Passthru [switch]
```powershell
[Parameter(ParameterSetName = 'Set 1')]
```
Returns a history object for each history entry. By default, this cmdlet does not generate any output.
## INPUTS
### Microsoft.PowerShell.Commands.HistoryInfo
You can pipe a HistoryInfo object to Add-History.
## OUTPUTS
### None or Microsoft.PowerShell.Commands.HistoryInfo
When you use the PassThru parameter, Add-History returns a HistoryInfo object. Otherwise, this cmdlet does not generate any output.
## NOTES
The session history is a list of the commands entered during the session along with the ID. The session history represents the order of execution, the status, and the start and end times of the command. As you enter each command, Windows PowerShell adds it to the history so that you can reuse it. For more information about the session history, see about_History.
To specify the commands to add to the history, use the InputObject parameter. The Add-History command accepts only HistoryInfo objects, such as those returned for each command by the Get-History cmdlet. You cannot pass it a path and file name or a list of commands.
You can use the InputObject parameter to pass a file of HistoryInfo objects to Add-History. To do so, export the results of a Get-History command to a file by using the Export-Csv or Export-Clixml cmdlet and then import the file by using the Import-Csv or Import-Clixml cmdlets. You can then pass the file of imported HistoryInfo objects to Add-History through a pipeline or in a variable. For more information, see the examples.
The file of HistoryInfo objects that you pass to the Add-History cmdlet must include the type information, column headings, and all of the properties of the HistoryInfo objects. If you intend to pass the objects back to Add-History, do not use the NoTypeInformation parameter of the Export-Csv cmdlet and do not delete the type information, column headings, or any fields in the file.
To edit the session history, export the session to a CSV or XML file, edit the file, import the file, and use Add-History to append it to the current session history.
## EXAMPLES
### -------------------------- EXAMPLE 1 --------------------------
```powershell
PS C:\>get-history | export-csv c:\testing\history.csv
PS C:\>import-csv history.csv | add-history
```
These commands add the commands typed in one Windows PowerShell session to the history of a different Windows PowerShell session. The first command gets objects representing the commands in the history and exports them to the History.csv file. The second command is typed at the command line of a different session. It uses the Import-Csv cmdlet to import the objects in the History.csv file. The pipeline operator passes the objects to the Add-History cmdlet, which adds the objects representing the commands in the History.csv file to the current session history.
### -------------------------- EXAMPLE 2 --------------------------
```powershell
PS C:\>import-clixml c:\temp\history.xml | add-history -passthru | foreach-object -process {invoke-history}
```
This command imports commands from the History.xml file, adds them to the current session history, and then executes the commands in the combined history.
The first command uses the Import-Clixml cmdlet to import a command history that was exported to the History.xml file. The pipeline operator (|) passes the commands to the Add-History parameter, which adds the commands to the current session history. The PassThru parameter passes the objects representing the added commands down the pipeline.
The command then uses the ForEach-Object cmdlet to apply the Invoke-History command to each of the commands in the combined history. The Invoke-History command is formatted as a script block (enclosed in braces) as required by the Process parameter of the ForEach-Object cmdlet.
### -------------------------- EXAMPLE 3 --------------------------
```powershell
PS C:\>get-history -id 5 -count 5 | add-history
```
This command adds the first five commands in the history to the end of the history list. It uses the Get-History cmdlet to get the five commands ending in command 5. The pipeline operator (|) passes them to the Add-History cmdlet, which appends them to the current history. The Add-History command does not include any parameters, but Windows PowerShell associates the objects passed through the pipeline with the InputObject parameter of Add-History.
### -------------------------- EXAMPLE 4 --------------------------
```powershell
PS C:\>$a = import-csv c:\testing\history.csv
PS C:\>add-history -inputobject $a -passthru
```
These commands add the commands in the History.csv file to the current session history. The first command uses the Import-Csv cmdlet to import the commands in the History.csv file and store its contents in the variable $a. The second command uses the Add-History cmdlet to add the commands from History.csv to the current session history. It uses the InputObject parameter to specify the $a variable and the PassThru parameter to generate an object to display at the command line. Without the PassThru parameter, the Add-History cmdlet does not generate any output.
### -------------------------- EXAMPLE 5 --------------------------
```powershell
PS C:\>add-history -inputobject (import-clixml c:\temp\history01.xml)
```
This command adds the commands in the History01.xml file to the current session history. It uses the InputObject parameter to pass the results of the command in parentheses to the Add-History cmdlet. The command in parentheses, which is executed first, imports the History01.xml file into Windows PowerShell. The Add-History cmdlet then adds the commands in the file to the session history.
## RELATED LINKS
[Online Version:](http://go.microsoft.com/fwlink/p/?linkid=289569)
[Clear-History]()
[Get-History]()
[Invoke-History]()
[about_History]()
# Add-PSSnapin
## SYNOPSIS
Adds one or more Windows PowerShell snap-ins to the current session.
## DESCRIPTION
The Add-PSSnapin cmdlet adds registered Windows PowerShell snap-ins to the current session. After the snap-ins are added, you can use the cmdlets and providers that the snap-ins support in the current session.
To add the snap-in to all future Windows PowerShell sessions, add an Add-PSSnapin command to your Windows PowerShell profile. For more information, see about_Profiles.
Beginning in Windows PowerShell 3.0, the core commands that are included in Windows PowerShell are packaged in modules. The exception is Microsoft.PowerShell.Core, which is a snap-in (PSSnapin). By default, only the Microsoft.PowerShell.Core snap-in is added to the session. Modules are imported automatically on first use and you can use the Import-Module cmdlet to import them.
## PARAMETERS
### Name [String[]]
```powershell
[Parameter(
Mandatory = $true,
Position = 1,
ValueFromPipelineByPropertyName = $true,
ParameterSetName = 'Set 1')]
```
Specifies the name of the snap-in. (This is the Name, not the AssemblyName or ModuleName.) Wildcards are permitted.
To find the names of the registered snap-ins on your system, type: ""get-pssnapin -registered"".
### PassThru [switch]
```powershell
[Parameter(ParameterSetName = 'Set 1')]
```
Returns an object representing each added snap-in. By default, this cmdlet does not generate any output.
## INPUTS
### None
You cannot pipe objects to Add-PSSnapin.
## OUTPUTS
### None or System.Management.Automation.PSSnapInInfo
When you use the PassThru parameter, Add-PSSnapin returns a PSSnapInInfo object that represents the snap-in. Otherwise, this cmdlet does not generate any output.
## NOTES
Beginning in Windows PowerShell 3.0, the core commands that are installed with Windows PowerShell are packaged in modules. In Windows PowerShell 2.0, and in host programs that create older-style sessions in later versions of Windows PowerShell, the core commands are packaged in snap-ins (""PSSnapins""). The exception is Microsoft.PowerShell.Core, which is always a snap-in. Also, remote sessions, such as those started by the New-PSSession cmdlet, are older-style sessions that include core snap-ins.
For information about the CreateDefault2 method that creates newer-style sessions with core modules, see ""CreateDefault2 Method"" in MSDN at [http://msdn.microsoft.com/en-us/library/windows/desktop/system.management.automation.runspaces.initialsessionstate.createdefault2(v=VS.85).aspx]().
For detailed information about snap-ins in Windows PowerShell, see about_Pssnapins. For information about how to create a Windows PowerShell snap-in, see ""How to Create a Windows PowerShell Snap-in"" in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkId=144762http://go.microsoft.com/fwlink/?LinkId=144762.
Add-PSSnapin adds the snap-in only to the current session. To add the snap-in to all Windows PowerShell sessions, add it to your Windows PowerShell profile. For more information, see about_Profiles.
You can add any Windows PowerShell snap-in that has been registered by using the Microsoft .NET Framework install utility. For more information, see ""How to Register Cmdlets, Providers, and Host Applications"" in the MSDN library at http://go.microsoft.com/fwlink/?LinkID=143619http://go.microsoft.com/fwlink/?LinkID=143619.
To get a list of snap-ins that are registered on your computer, type get-pssnapin -registered.
Before adding a snap-in, Add-PSSnapin checks the version of the snap-in to verify that it is compatible with the current version of Windows PowerShell. If the snap-in fails the version check, Windows PowerShell reports an error.
## EXAMPLES
### -------------------------- EXAMPLE 1 --------------------------
```powershell
PS C:\>add-PSSnapIn Microsoft.Exchange, Microsoft.Windows.AD
```
This command adds the Microsoft Exchange and Active Directory snap-ins to the current session.
### -------------------------- EXAMPLE 2 --------------------------
```powershell
PS C:\>get-pssnapin -registered | add-pssnapin -passthru
```
This command adds all of the registered Windows PowerShell snap-ins to the session. It uses the Get-PSSnapin cmdlet with the Registered parameter to get objects representing each of the registered snap-ins. The pipeline operator (|) passes the result to Add-PSSnapin, which adds them to the session. The PassThru parameter returns objects that represent each of the added snap-ins.
### -------------------------- EXAMPLE 3 --------------------------
```powershell
The first command gets snap-ins that have been added to the current session, including the snap-ins that are installed with Windows PowerShell. In this example, ManagementFeatures is not returned. This indicates that it has not been added to the session.
PS C:\>get-pssnapin
The second command gets snap-ins that have been registered on your system (including those that have already been added to the session). It does not include the snap-ins that are installed with Windows PowerShell.In this case, the command does not return any snap-ins. This indicates that the ManagementFeatures snapin has not been registered on the system.
PS C:\>get-pssnapin -registered
The third command creates an alias, ""installutil"", for the path to the InstallUtil tool in .NET Framework.
PS C:\>set-alias installutil $env:windir\Microsoft.NET\Framework\v2.0.50727\installutil.exe
The fourth command uses the InstallUtil tool to register the snap-in. The command specifies the path to ManagementCmdlets.dll, the file name or ""module name"" of the snap-in.
PS C:\>installutil C:\Dev\Management\ManagementCmdlets.dll
The fifth command is the same as the second command. This time, you use it to verify that the ManagementCmdlets snap-in is registered.
PS C:\>get-pssnapin -registered
The sixth command uses the Add-PSSnapin cmdlet to add the ManagementFeatures snap-in to the session. It specifies the name of the snap-in, ManagementFeatures, not the file name.
PS C:\>add-pssnapin ManagementFeatures
To verify that the snap-in is added to the session, the seventh command uses the Module parameter of the Get-Command cmdlet. It displays the items that were added to the session by a snap-in or module.
PS C:\>get-command -module ManagementFeatures
You can also use the PSSnapin property of the object that the Get-Command cmdlet returns to find the snap-in or module in which a cmdlet originated. The eighth command uses dot notation to find the value of the PSSnapin property of the Set-Alias cmdlet.
PS C:\>(get-command set-alias).pssnapin
```
This example demonstrates the process of registering a snap-in on your system and then adding it to your session. It uses ManagementFeatures, a fictitious snap-in implemented in a file called ManagementCmdlets.dll.
## RELATED LINKS
[Online Version:](http://go.microsoft.com/fwlink/p/?linkid=289570)
[Get-PSSnapin]()
[Remove-PSSnapin]()
[about_Profiles]()
[about_PSSnapins]()
");
string[] examples = GetXmlContent(maml, "/helpItems/command:command/command:examples/command:example/dev:code");
Assert.Equal(5 + 3, examples.Length);
}
protected override void Write(MamlRenderer renderer, Markdig.Extensions.Figures.Figure obj)
{
renderer.WriteChildren(obj);
}
public void RendererProduceNameAndSynopsis()
{
MamlRenderer renderer = new MamlRenderer();
MamlCommand command = new MamlCommand()
{
Name = "Get-Foo",
Synopsis = new SectionBody("This is the synopsis"),
Description = new SectionBody("This is a long description.")
};
command.Parameters.Add(new MamlParameter()
{
Type = "String",
Name = "Name",
Required = true,
Description = "This is the name parameter description.",
VariableLength = true,
Globbing = true,
PipelineInput = "True (ByValue)",
Position = "1",
Aliases = new string [] { "GF", "Foos", "Do" },
}
);
command.Parameters.Add(new MamlParameter()
{
Type = "String",
Name = "Path",
Required = true,
Description = "This is the path parameter description.",
VariableLength = true,
Globbing = true,
PipelineInput = "True (ByValue)",
Position = "2",
Aliases = new string[] { },
}
);
command.Inputs.Add(new MamlInputOutput()
{
TypeName = "String",
Description = "Input Description goes here!"
}
);
command.Outputs.Add(new MamlInputOutput()
{
TypeName = "String",
Description = "Output Description goes here!"
}
);
command.Examples.Add(new MamlExample()
{
Title = "Example 1",
Code = new[] { new MamlCodeBlock("PS:> Get-Help -YouNeedIt") },
Remarks = "This does stuff!"
});
command.Examples.Add(new MamlExample()
{
Title = "Example 2",
Code = new[] {
new MamlCodeBlock("PS:> Get-Help -YouNeedIt", "powershell"),
new MamlCodeBlock("Output")
},
Remarks = "This does stuff!"
});
command.Links.Add(new MamlLink()
{
LinkName = "PowerShell made by Microsoft Hackathon",
LinkUri = "www.microsoft.com"
}
);
string maml = renderer.MamlModelToString(new [] { command });
string[] name = EndToEndTests.GetXmlContent(maml, "/msh:helpItems/command:command/command:details/command:name");
Assert.Single(name);
Assert.Equal("Get-Foo", name[0]);
string[] synopsis = EndToEndTests.GetXmlContent(maml, "/msh:helpItems/command:command/command:details/maml:description/maml:para");
Assert.Single(synopsis);
Assert.Equal("This is the synopsis", synopsis[0]);
string[] description = EndToEndTests.GetXmlContent(maml, "/msh:helpItems/command:command/maml:description/maml:para");
Assert.Single(description);
Assert.Equal("This is a long description.", description[0]);
string[] parameter1 = EndToEndTests.GetXmlContent(maml, "/msh:helpItems/command:command/command:parameters/command:parameter[maml:name='Name']/maml:description/maml:para");
Assert.Single(parameter1);
Assert.Equal("This is the name parameter description.", parameter1[0]);
string[] parameter2 = EndToEndTests.GetXmlContent(maml, "/msh:helpItems/command:command/command:parameters/command:parameter[maml:name='Path']/maml:description/maml:para");
Assert.Single(parameter2);
Assert.Equal("This is the path parameter description.", parameter2[0]);
string[] example1 = EndToEndTests.GetXmlContent(maml, "/msh:helpItems/command:command/command:examples/command:example[contains(maml:title,'Example 1')]/dev:code");
Assert.Single(example1);
Assert.Equal("PS:> Get-Help -YouNeedIt", example1[0]);
// Check that multiple code blocks in the same example merge together when rendering maml
string[] example2 = EndToEndTests.GetXmlContent(maml, "/msh:helpItems/command:command/command:examples/command:example[contains(maml:title,'Example 2')]/dev:code");
Assert.Single(example2);
Common.AssertMultilineEqual("PS:> Get-Help -YouNeedIt\r\n\r\nOutput", example2[0]);
}
protected override void Write(MamlRenderer renderer, HtmlEntityInline obj)
{
renderer.WriteEscape(obj.Transcoded);
}
protected override void Write(MamlRenderer renderer, DelimiterInline obj)
{
renderer.WriteEscape(obj.ToLiteral());
renderer.WriteChildren(obj);
}
