/// <summary>
/// Append a section to the documentation containing the targets error handling by using the
/// MsBuild Task "OnError". The task is read from the target content if exists.
/// </summary>
/// <param name="targetOverviewDocument">Document the section should be appended to.</param>
/// <param name="target">The target for which the section should be created.</param>
private void AppendErrorHandlingSection(IPrintableDocument targetOverviewDocument,
IMsBuildTarget target)
{
if (target.OnErrorTargets == null ||
target.OnErrorTargets?.Count == 0)
{
return;
}
IPrintableDocumentChapter errorHandlingChapter =
targetOverviewDocument.AddNewChapter("Error Handling");
IPrintableDocumentChapterStringContent chapterContent =
errorHandlingChapter.AddNewContent <IPrintableDocumentChapterStringContent>();
StringBuilder builder = new StringBuilder();
builder.AppendLine(
string.Format(CultureInfo.InvariantCulture,
"This chapter contains an description of the error handling of this target. All listed targets are executed after an error occured in the target {0}.",
target.Name)
);
builder.AppendLine();
foreach (var onErrorTarget in target.OnErrorTargets)
{
builder.AppendLine(string.Format(CultureInfo.InvariantCulture, " - {0}", onErrorTarget));
}
chapterContent.Content = builder.ToString();
}
public void IndexOf_ExistingItemAtIndex5_ShouldReturn5()
{
MsBuildXmlProjectImplementation project = CreateProjectWithMockedContent();
IMsBuildTarget target = project.GetChildren <IMsBuildTarget>()[5];
Assert.AreEqual(5, project.IndexOf(target));
}
public void Contains_ExistingItem_ShouldReturnTrue()
{
MsBuildXmlProjectImplementation project = CreateProjectWithMockedContent();
IMsBuildTarget target = project.GetChildren <IMsBuildTarget>().First();
Assert.IsTrue(project.Contains(target));
}
Load_FromExistentTestFileWithTargetExecutedBeforeOtherTarget_ShouldReturnObjectContainingTargetWithCorrectBeforeTargetValue()
{
IMsBuildProject projectFile = MsBuildProjectFile.Load("TestData/ProjectFiles/Test.tcsproj");
IMsBuildTarget target =
projectFile.GetChildren <IMsBuildTarget>().First(t => t.Name.Equals("BeforeCompile"));
Assert.AreEqual("CoreCompile", target.BeforeTargets.First());
}
Load_FromExistentTestFileWithOneTargetContainingOnErrorImplementation_ShouldContainTargetWithCorrectNamedOnErrorImplementation()
{
IMsBuildProject projectFile = MsBuildProjectFile.Load("TestData/ProjectFiles/TargetWithOnError.tcsproj");
IMsBuildTarget target =
projectFile.GetChildren <IMsBuildTarget>().First(t => t.Name.Equals("BeforeCompile"));
Assert.AreEqual(1, target.OnErrorTargets.Count);
Assert.AreEqual("CheckFileNameSyntax", target.OnErrorTargets.First());
}
public void Load_FromExistentTestFileWithTargetContainingComment_ShouldInitializeTargetsOnErrorImplementation()
{
IMsBuildProject projectFile = MsBuildProjectFile.Load("TestData/ProjectFiles/TargetWithOnError.tcsproj");
IMsBuildTarget target =
projectFile.GetChildren <IMsBuildTarget>().First(t => t.Name.Equals("BeforeCompile"));
Assert.IsNotNull(target.OnErrorTargets);
Assert.AreNotEqual(0, target.OnErrorTargets.Count);
}
public void GetChildren_WithOneTarget_ReturnCorrectTarget()
{
string projectXml = "<Project><Target Name=\"TestTargetA\"></Target></Project>";
IMsBuildProject project = new MsBuildXmlProjectImplementation(CreateFromString(projectXml));
IMsBuildTarget target = project.GetChildren <IMsBuildTarget>().First();
Assert.AreEqual("TestTargetA", target.Name);
}
Load_FromExistentTestFileWithDocumentedTargetNamedCheckFileNameSyntax_ShouldContainTargetWithXmlHelp()
{
IMsBuildProject projectFile = MsBuildProjectFile.Load("TestData/ProjectFiles/Test.tcsproj");
IMsBuildTarget target = projectFile.GetChildren <IMsBuildTarget>()
.First(t => t.Name.Equals("CheckFileNameSyntax"));
Assert.AreEqual("Checks the files from @(RelevantFiles) if it ends with '*.json'.",
target.Help.GetSectionContent("Synopsis", StringComparison.OrdinalIgnoreCase));
Assert.AreEqual(
"Prints an error with information about the item when it does not\nmatches the file extension 'json'. The printed error contains\ninformation about the affected item.",
target.Help.GetSectionContent("DESCRIPTION", StringComparison.OrdinalIgnoreCase));
}
Load_FromExistentTestFileWithTargetImplementingComplexConditionalOverwritableProperty_ShouldReturnProjectContainingTargetWithOverwritableProperty()
{
IMsBuildProject projectFile = MsBuildProjectFile.Load("TestData/ProjectFiles/TargetWithProperties.tcsproj");
IMsBuildTarget target = projectFile.GetChildren <IMsBuildTarget>()
.First(t => t.Name.Equals("WithComplexConditionalOverwritableProperty"));
IMsBuildProperty overwritableProperty =
target.GetChildren <IMsBuildPropertyGroup>().First().GetChildren <IMsBuildProperty>()
.First(p => p.Name.Equals("OverwritableProperty"));
Assert.AreEqual(true, overwritableProperty.HasPublicSetter);
}
/// <summary>
/// Creates the documentation body content for the given MsBuild target
/// </summary>
/// <param name="target">The target for which the documentation should be generated.</param>
/// <returns>Document representing the generated documentation</returns>
public IPrintableDocument CreateOverview(IMsBuildTarget target)
{
IPrintableDocument targetOverviewDocument = _printableDocument.Create(target.Name);
AppendDescriptionSection(targetOverviewDocument, target);
AppendParameterSection(targetOverviewDocument, target);
AppendOutputSection(targetOverviewDocument, target);
AppendDependencySection(targetOverviewDocument, target);
AppendErrorHandlingSection(targetOverviewDocument, target);
AppendExampleSection(targetOverviewDocument, target);
return(targetOverviewDocument);
}
public void CopyTo_Array_ShouldCopyAllValuesToArray()
{
string inputValue = "<Project></Project>";
IMsBuildTarget[] array = new IMsBuildTarget[20];
MsBuildXmlProjectImplementation projectImplementation =
new MsBuildXmlProjectImplementation(CreateFromString(inputValue));
for (int i = 0; i <= 10; i++)
{
Mock <IMsBuildTarget> mock = new Mock <IMsBuildTarget>();
mock.Setup(m => m.Name).Returns($"Target{i}");
projectImplementation.Add(mock.Object);
}
projectImplementation.CopyTo(array, 0);
Assert.AreEqual("Target0", array[0].Name);
}
/// <summary>
/// Append a section to the documentation containing the targets examples by using the
/// xml based help. Therefore all examples are appended a code block.
/// </summary>
/// <param name="targetOverviewDocument">Document the section should be appended to.</param>
/// <param name="target">The target for which the section should be created.</param>
private void AppendExampleSection(IPrintableDocument targetOverviewDocument,
IMsBuildTarget target)
{
if (target.Help.ContainsSection(MsBuildHelpSections.Example, StringComparison.OrdinalIgnoreCase) == false)
{
return;
}
foreach (IMsBuildElementHelpParagraph exampleHelpParagraph in target.Help.LookUp(
MsBuildHelpSections.Example, StringComparison.OrdinalIgnoreCase))
{
IPrintableDocumentChapter exampleChapter =
targetOverviewDocument.AddNewChapter(MsBuildHelpSections.Example);
IPrintableDocumentCodeBlock exampleCodeBlock =
exampleChapter.AddNewContent <IPrintableDocumentCodeBlock>();
var codeBlock = MsBuildElementHelpCodeBlockUtility.Parse(exampleHelpParagraph.Content);
exampleCodeBlock.AppendContentLine(codeBlock.Content);
exampleCodeBlock.SetLanguage(codeBlock.Language.ToString());
}
}
/// <summary>
/// Append a section to the documentation containing the targets outputs by using the
/// xml based help. Therefore the help section "Outputs" is used.
/// </summary>
/// <param name="targetOverviewDocument">Document the section should be appended to.</param>
/// <param name="target">The target for which the section should be created.</param>
private void AppendOutputSection(IPrintableDocument targetOverviewDocument, IMsBuildTarget target)
{
if (!target.Help.ContainsSection(MsBuildHelpSections.Outputs,
StringComparison.OrdinalIgnoreCase))
{
return;
}
foreach (IMsBuildElementHelpParagraph outputsHelpParagraph in
target.Help.LookUp(MsBuildHelpSections.Outputs, StringComparison.OrdinalIgnoreCase))
{
IPrintableDocumentChapter parameterChapter =
targetOverviewDocument.AddNewChapter(
string.Format(CultureInfo.InvariantCulture, "Outputs {0}",
outputsHelpParagraph.Additional)
);
IPrintableDocumentChapterStringContent outputsSectionBody =
parameterChapter.AddNewContent <IPrintableDocumentChapterStringContent>();
outputsSectionBody.Content = outputsHelpParagraph.Content;
}
}
/// <summary>
/// Append a section to the documentation containing the targets dependencies by using the
/// MsBuild target attributes. Therefore all dependencies like "AfterTargets", "BeforeTargets"
/// and "DependsOnTargets" are appended as a paragraph table.
/// </summary>
/// <param name="targetOverviewDocument">Document the section should be appended to.</param>
/// <param name="target">The target for which the section should be created.</param>
private void AppendDependencySection(IPrintableDocument targetOverviewDocument,
IMsBuildTarget target)
{
if (target.HasTargetDependencies == false)
{
return;
}
IPrintableDocumentChapter dependencyChapter =
targetOverviewDocument.AddNewChapter("Target Dependencies");
IPrintableParagraphTable dependencyTable =
dependencyChapter.AddNewContent <IPrintableParagraphTable>()
.WithHeaders("Target", "Dependency Type", "Dependency Description");
foreach (var dependentOnTarget in target.DependsOnTargets)
{
dependencyTable.WithRow(dependentOnTarget, "DependsOnTargets",
string.Format(CultureInfo.InvariantCulture,
"Calls the target {0} before execution of {1}.", dependentOnTarget, target.Name));
}
foreach (var afterTarget in target.AfterTargets)
{
dependencyTable.WithRow(afterTarget, "AfterTargets",
string.Format(CultureInfo.InvariantCulture,
"Runs the target {0} after the execution of {1} has finished.", target.Name, afterTarget));
}
foreach (var beforeTargets in target.BeforeTargets)
{
dependencyTable.WithRow(beforeTargets, "BeforeTargets",
string.Format(CultureInfo.InvariantCulture,
"Runs the target {0} before the execution of {1} starts.", target.Name, beforeTargets));
}
}
/// <summary>
/// Append a section to the documentation containing the targets parameters by using the
/// xml based help. Therefore the help section "Parameter" is used.
/// </summary>
/// <param name="targetOverviewDocument">Document the section should be appended to.</param>
/// <param name="target">The target for which the section should be created.</param>
private void AppendParameterSection(IPrintableDocument targetOverviewDocument, IMsBuildTarget target)
{
if (!target.Help.ContainsSection(MsBuildHelpSections.Parameter,
StringComparison.OrdinalIgnoreCase))
{
return;
}
IPrintableDocumentChapter parameterChapter = targetOverviewDocument.AddNewChapter("Parameters");
foreach (IMsBuildElementHelpParagraph parameterHelpParagraph in
target.Help.LookUp(MsBuildHelpSections.Parameter, StringComparison.OrdinalIgnoreCase))
{
IPrintableDocumentParagraph parameterParagraph =
parameterChapter.AddNewParagraph(
string.Format(CultureInfo.InvariantCulture, "Parameter {0}",
parameterHelpParagraph.Additional)
);
IPrintableDocumentChapterStringContent parameterSectionBody =
parameterParagraph.AddNewContent <IPrintableDocumentChapterStringContent>();
parameterSectionBody.Content = parameterHelpParagraph.Content;
}
}
/// <summary>
/// Append a section to the documentation containing the targets description by using
/// the xml based help. Therefore the help section "Description" is used.
/// </summary>
/// <param name="targetOverviewDocument">Document the section should be appended to.</param>
/// <param name="target">The target for which the section should be created.</param>
private void AppendDescriptionSection(IPrintableDocument targetOverviewDocument, IMsBuildTarget target)
{
if (!target.Help.ContainsSection(MsBuildHelpSections.Description, StringComparison.OrdinalIgnoreCase)
)
{
return;
}
string descriptionContent = target.Help.GetSectionContent(
MsBuildHelpSections.Description, StringComparison.OrdinalIgnoreCase
);
IPrintableDocumentChapter descriptionChapter = targetOverviewDocument.AddNewChapter("Description");
IPrintableDocumentChapterStringContent descriptionChapterContent =
descriptionChapter.AddNewContent <IPrintableDocumentChapterStringContent>();
descriptionChapterContent.Content = string.Join(Environment.NewLine, descriptionContent);
}
/// <summary>
/// Creates a hyperlink to a dedicated overview file representing the target target located
/// in a sub directory of the destination documentation directory.
/// </summary>
/// <param name="target">Target for which the hyperlink should be created</param>
/// <returns>ParagraphHyperlink linking to the dedicated target documentation site</returns>
private IPrintableDocumentParagraphHyperlink CreateHyperlinkForTargetOverviewFile(IMsBuildTarget target)
{
IPrintableDocumentParagraphHyperlink paragraphHyperLink =
_outputDocument.CreateElement <IPrintableDocumentParagraphHyperlink>();
paragraphHyperLink.DisplayString = target.Name;
paragraphHyperLink.Hyperlink = Path.Combine(".", "Targets",
string.Format(CultureInfo.InvariantCulture, "{0}.{1}", target.Name,
_outputDocument.DefaultFileExtension));
paragraphHyperLink.ToolTip =
string.Format(CultureInfo.CurrentCulture, "See more about the target {0}.", target.Name);
return(paragraphHyperLink);
}
