protected override void OnReadXml(XmlReader reader)
{
if (String.Equals(reader.Name, ReferenceSource.TagName,
StringComparison.OrdinalIgnoreCase))
{
string sourceName = reader.GetAttribute("name");
if (_topicSource == null)
{
_topicSource = ReferenceSource.CreateSource(sourceName);
}
if (_topicSource == null)
{
throw new BuildException(String.Format(
"The creation of the reference content source '{0}' failed.",
reader.GetAttribute("name")));
}
_topicSource.ReadXml(reader);
}
else if (String.Equals(reader.Name, "versionInfo",
StringComparison.OrdinalIgnoreCase))
{
if (_versionInfo == null)
{
_versionInfo = new ReferenceVersionInfo();
}
_versionInfo.ReadXml(reader);
}
}
private void CreateReflectionSteps(BuildMultiStep listSteps,
ReferenceGroup group, string sandcastleDir, string helpStyle)
{
Debug.Assert(_engineSettings != null);
if (_engineSettings == null)
{
return;
}
BuildContext context = this.Context;
BuildSettings settings = this.Settings;
ReferenceGroupContext groupContext =
context.GroupContexts[group.Id] as ReferenceGroupContext;
if (groupContext == null)
{
throw new BuildException(
"The group context is not provided, and it is required by the build system.");
}
string workingDir = context.WorkingDirectory;
ReferenceContent content = group.Content;
string assemblyDir = Path.Combine(workingDir, groupContext.AssemblyFolder);
string dependencyDir = Path.Combine(workingDir, groupContext.DependencyFolder);
DependencyContent dependencies = content.Dependencies;
string reflectionFile = groupContext["$ReflectionFile"];
string manifestFile = groupContext["$ManifestFile"];
string refBuilderFile = groupContext["$ReflectionBuilderFile"];
string tocFile = groupContext["$TocFile"];
BuildStyleType outputStyle = settings.Style.StyleType;
string tempText = null;
string arguments = null;
string application = null;
bool ripOldApis = true;
string assemblyFiles = null;
string dependencyFiles = null;
string outputFile = null;
string configurationFile = null;
ReferenceVisibilityConfiguration visibility =
_engineSettings.Visibility;
Debug.Assert(visibility != null);
// 1. Create the reflection and the manifest
StringBuilder textBuilder = new StringBuilder();
if (group.IsSingleVersion)
{
// Call MRefBuilder to generate the reflection...
// MRefBuilder Assembly.dll
// /out:reflection.org /config:MRefBuilder.config
// /internal-
application = Path.Combine(context.SandcastleToolsDirectory,
"MRefBuilder.exe");
assemblyFiles = String.Format(@"{0}\*.*", assemblyDir);
dependencyFiles = String.Format(@"{0}\*.*", dependencyDir);
outputFile = Path.ChangeExtension(reflectionFile, ".ver");
configurationFile = Path.Combine(workingDir, refBuilderFile);
textBuilder.Append(assemblyFiles);
textBuilder.Append(" /dep:" + dependencyFiles);
textBuilder.AppendFormat(" /out:{0} /config:{1}",
outputFile, refBuilderFile);
if (visibility != null && visibility.IncludeInternalsMembers)
{
textBuilder.Append(" /internal+");
}
else
{
textBuilder.Append(" /internal-");
}
arguments = textBuilder.ToString();
outputFile = Path.Combine(workingDir, outputFile);
}
else
{
// Call the VersionBuilder to create the combined reflection file...
application = Path.Combine(context.SandcastleToolsDirectory,
"VersionBuilder.exe");
textBuilder.AppendFormat(" /config:{0} /out:{1}",
groupContext["$ApiVersionsBuilderFile"],
Path.ChangeExtension(reflectionFile, ".org"));
configurationFile = Path.Combine(workingDir,
groupContext["$ApiVersionsBuilderFile"]);
ReferenceVersionInfo versionInfo = group.VersionInfo;
ripOldApis = versionInfo.RipOldApis;
if (ripOldApis)
{
textBuilder.Append(" /rip+");
}
else
{
textBuilder.Append(" /rip-");
}
arguments = textBuilder.ToString();
}
StepReflectionBuilder refBuilder = new StepReflectionBuilder(workingDir,
application, arguments);
refBuilder.Group = group;
refBuilder.LogTitle = String.Empty;
refBuilder.Message = "Creating XML-formatted reflection information.";
refBuilder.CopyrightNotice = 2;
// For the direct use of the Sandcastle library, we need the
// following parameters...
refBuilder.RipOldApis = ripOldApis;
refBuilder.DocumentInternals =
(visibility != null && visibility.IncludeInternalsMembers);
refBuilder.ConfigurationFile = configurationFile;
refBuilder.ReflectionFile = outputFile;
refBuilder.AssemblyFiles.Add(assemblyFiles);
refBuilder.DependencyFiles.Add(dependencyFiles);
listSteps.Add(refBuilder);
textBuilder.Length = 0;
// 2. Create the reflection and comment refining step...
StepReferenceRefine referenceRefine =
new StepReferenceRefine(workingDir);
referenceRefine.LogTitle = String.Empty;
referenceRefine.Message = "Refining the reflection files - filtering and cleaning";
referenceRefine.Group = group;
listSteps.Add(referenceRefine);
textBuilder.Length = 0;
// 3. Apply Transforms
// XslTransform.exe
// /xsl:"%DXROOT%\ProductionTransforms\ApplyVSDocModel.xsl"
// reflection.org
// /xsl:"%DXROOT%\ProductionTransforms\AddFriendlyFilenames.xsl"
// /out:reflection.xml /arg:IncludeAllMembersTopic=true
// /arg:IncludeInheritedOverloadTopics=true /arg:project=Project
application = Path.Combine(context.SandcastleToolsDirectory,
"XslTransform.exe");
string prodPath = Path.Combine(sandcastleDir, "ProductionTransforms");
string textTemp = String.Empty;
if (group.EnableXmlnsForXaml)
{
textTemp = Path.Combine(prodPath, "AddXamlSyntaxData.xsl");
if (!String.IsNullOrEmpty(textTemp))
{
textBuilder.AppendFormat(" /xsl:\"{0}\"", textTemp);
textTemp = String.Empty;
}
}
if (outputStyle == BuildStyleType.ClassicWhite ||
outputStyle == BuildStyleType.ClassicBlue)
{
textTemp = Path.Combine(prodPath, "ApplyVSDocModel.xsl");
}
else if (outputStyle == BuildStyleType.Lightweight)
{
}
else if (outputStyle == BuildStyleType.ScriptFree)
{
}
if (!String.IsNullOrEmpty(textTemp))
{
textBuilder.AppendFormat(" /xsl:\"{0}\"", textTemp);
textTemp = String.Empty;
}
ReferenceNamingMethod namingMethod = _engineSettings.Naming;
if (namingMethod == ReferenceNamingMethod.Guid)
{
textTemp = Path.Combine(prodPath, "AddGuidFilenames.xsl");
}
else if (namingMethod == ReferenceNamingMethod.MemberName)
{
textTemp = Path.Combine(prodPath, "AddFriendlyFilenames.xsl");
}
else
{
textTemp = Path.Combine(prodPath, "AddGuidFilenames.xsl");
}
if (!String.IsNullOrEmpty(textTemp))
{
textBuilder.AppendFormat(" /xsl:\"{0}\"", textTemp);
textTemp = String.Empty;
}
textBuilder.Append(" " + Path.ChangeExtension(reflectionFile, ".org"));
textBuilder.AppendFormat(" /out:{0}", reflectionFile);
textBuilder.AppendFormat(" /arg:IncludeAllMembersTopic={0}",
_engineSettings.IncludeAllMembersTopic ? "true" : "false");
textBuilder.AppendFormat(" /arg:IncludeInheritedOverloadTopics={0}",
_engineSettings.IncludeInheritedOverloadTopics ? "true" : "false");
bool rootContainer = _engineSettings.RootNamespaceContainer;
string rootTitle = group.RootNamespaceTitle;
if (rootContainer && !String.IsNullOrEmpty(rootTitle))
{
textBuilder.Append(" /arg:project=Project");
// Indicate that this reference group is rooted...
groupContext["$IsRooted"] = Boolean.TrueString;
}
arguments = textBuilder.ToString();
StepReferenceModel applyDocProcess = new StepReferenceModel(
workingDir, application, arguments);
applyDocProcess.Group = group;
applyDocProcess.LogTitle = String.Empty;
applyDocProcess.Message = "Xsl Transformation - Applying model and adding filenames";
applyDocProcess.CopyrightNotice = 2;
listSteps.Add(applyDocProcess);
textBuilder.Length = 0;
// 4. and finally the manifest...
// XslTransform.exe
// /xsl:"%DXROOT%\ProductionTransforms\ReflectionToManifest.xsl"
// reflection.xml /out:manifest.xml
application = Path.Combine(context.SandcastleToolsDirectory,
"XslTransform.exe");
textTemp = Path.Combine(prodPath, "ReflectionToManifest.xsl");
textBuilder.AppendFormat(" /xsl:\"{0}\"", textTemp);
textBuilder.AppendFormat(" {0} /out:{1}", reflectionFile, manifestFile);
arguments = textBuilder.ToString();
StepReferenceManifest manifestProcess = new StepReferenceManifest(
workingDir, application, arguments);
manifestProcess.Group = group;
manifestProcess.LogTitle = String.Empty;
manifestProcess.Message = "Xsl Transformation - Reflection to Manifest";
manifestProcess.CopyrightNotice = 2;
listSteps.Add(manifestProcess);
// 5. Create the reflection table of contents
// XslTransform.exe
// /xsl:"%DXROOT%\ProductionTransforms\createvstoc.xsl"
// reflection.xml /out:ApiToc.xml
application = Path.Combine(context.SandcastleToolsDirectory,
"XslTransform.exe");
if (outputStyle == BuildStyleType.ClassicWhite ||
outputStyle == BuildStyleType.ClassicBlue)
{
tempText = Path.Combine(sandcastleDir,
@"ProductionTransforms\CreateVSToc.xsl");
}
else if (outputStyle == BuildStyleType.Lightweight)
{
}
else if (outputStyle == BuildStyleType.ScriptFree)
{
}
arguments = String.Format("/xsl:\"{0}\" {1} /out:{2}",
tempText, reflectionFile, tocFile);
StepReferenceToc tocProcess = new StepReferenceToc(workingDir,
application, arguments);
tocProcess.LogTitle = String.Empty;
tocProcess.Message = "Xsl Transformation - Creating References TOC";
tocProcess.Group = group;
tocProcess.CopyrightNotice = 2;
listSteps.Add(tocProcess);
}
/// <summary>
/// The creates the configuration information or settings required by the
/// target component for the build process.
/// </summary>
/// <param name="group">
/// A build group, <see cref="BuildGroup"/>, representing the documentation
/// target for configuration.
/// </param>
/// <param name="writer">
/// An <see cref="XmlWriter"/> object used to create one or more new
/// child nodes at the end of the list of child nodes of the current node.
/// </param>
/// <returns>
/// Returns <see langword="true"/> for a successful configuration;
/// otherwise, it returns <see langword="false"/>.
/// </returns>
/// <remarks>
/// The <see cref="XmlWriter"/> writer passed to this configuration object
/// may be passed on to other configuration objects, so do not close or
/// dispose it.
/// </remarks>
public override bool Configure(BuildGroup group, XmlWriter writer)
{
BuildExceptions.NotNull(group, "group");
BuildExceptions.NotNull(writer, "writer");
if (!this.Enabled || !this.IsInitialized)
{
return(false);
}
ReferenceGroup refGroup = group as ReferenceGroup;
if (refGroup == null)
{
return(false);
}
ReferenceGroupContext theContext = _context.GroupContexts[group.Id]
as ReferenceGroupContext;
if (theContext == null)
{
throw new BuildException(
"The group context is not provided, and it is required by the build system.");
}
ReferenceVersionType versionType = refGroup.VersionType;
if (versionType != ReferenceVersionType.Advanced)
{
return(false);
}
ReferenceVersionInfo versionInfo = refGroup.VersionInfo;
if (versionInfo == null || versionInfo.IsEmpty ||
!versionInfo.PlatformFilters)
{
return(false);
}
IList <ReferenceVersions> platforms = theContext.Versions;
if (platforms == null || platforms.Count == 0)
{
return(false);
}
//<component type="Microsoft.Ddue.Tools.PlatformsComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
// <!-- The order of filter files in this config determines the order of platforms in the output. -->
// <filter files=".\SupportFiles\Platforms\WinVista.xml"/>
// <filter files=".\SupportFiles\Platforms\WinXP.xml"/>
// <filter files=".\SupportFiles\Platforms\WinXpMediaCenter.xml"/>
// <filter files=".\SupportFiles\Platforms\WinXPPro64.xml"/>
// <filter files=".\SupportFiles\Platforms\WinXPSE.xml"/>
// <filter files=".\SupportFiles\Platforms\WinSvr2003.xml"/>
// <filter files=".\SupportFiles\Platforms\WinSvr2000.xml"/>
// <filter files=".\SupportFiles\Platforms\WinME.xml"/>
// <filter files=".\SupportFiles\Platforms\Win98.xml"/>
// <filter files=".\SupportFiles\Platforms\WindowsCE.xml"/>
// <filter files=".\SupportFiles\Platforms\SmartPhone.xml"/>
// <filter files=".\SupportFiles\Platforms\PocketPC.xml"/>
// <filter files=".\SupportFiles\Platforms\Xbox360.xml"/>
//</component>
writer.WriteComment(" The order of filter files in this config determines the order of platforms in the output. ");
for (int i = 0; i < platforms.Count; i++)
{
ReferenceVersions platform = platforms[i];
string platformFile = platform.PlatformFile;
if (String.IsNullOrEmpty(platformFile) ||
!File.Exists(platformFile))
{
continue;
}
writer.WriteStartElement("filter"); //start: filter
writer.WriteAttributeString("files", platformFile);
writer.WriteEndElement(); //end: filter
}
return(true);
}