/// <inheritdoc />
        public override void Apply(XmlDocument document, string key)
        {
            Target target = null, keyTarget;
            string msdnUrl = null;

            foreach (XPathNavigator linkNode in document.CreateNavigator().Select(referenceLinkExpression).ToArray())
            {
                // Extract link information
                ReferenceLinkInfo link = new ReferenceLinkInfo(linkNode);

                // Determine target, link type, and display options
                string            targetId = link.Target;
                DisplayOptions    options  = link.DisplayOptions;
                ReferenceLinkType type     = ReferenceLinkType.None;

                if (String.IsNullOrWhiteSpace(targetId))
                {
                    this.WriteMessage(key, MessageLevel.Warn, "The target attribute is missing or has no " +
                                      "value.  You have most likely omitted a cref attribute or left it blank on an XML " +
                                      "comments element such as see, seealso, or exception.");
                    continue;
                }

                bool targetFound = targets.TryGetValue(targetId, out target, out type);

                // If it's an overload ID that wasn't found, it's possible that the overloads got excluded.
                // As such, see if we can find a match for a method using the same ID regardless of any
                // parameters.
                if (!targetFound && targetId.StartsWith("Overload:", StringComparison.Ordinal) ||
                    targetId.StartsWith("O:", StringComparison.Ordinal))
                {
                    string methodTargetId = "M:" + targetId.Substring(targetId.IndexOf(':') + 1);
                    methodTargetId = targets.Keys.FirstOrDefault(k => k.StartsWith(methodTargetId));

                    if (methodTargetId != null)
                    {
                        targetId    = methodTargetId;
                        targetFound = targets.TryGetValue(targetId, out target, out type);
                        options    |= DisplayOptions.ShowParameters;

                        // Don't use the content as it may not be appropriate for the method.  The default is
                        // "{0} Overload" which no longer applies.  Instead we'll show the method name and
                        // its parameters.
                        if (link.DisplayTarget.Equals("format", StringComparison.OrdinalIgnoreCase))
                        {
                            link.DisplayTarget = null;
                            link.Contents      = null;
                        }
                    }
                }

                // If not found and it starts with "System." or "Microsoft." we'll go with the assumption that
                // it's part of a Microsoft class library that is not part of the core framework but does have
                // documentation available on MSDN.  Worst case it doesn't and we get an unresolved link warning
                // instead of an unknown reference target warning.
                if (!targetFound && ((targetId.Length > 9 && targetId.Substring(2).StartsWith("System.",
                                                                                              StringComparison.Ordinal)) || (targetId.Length > 12 && targetId.Substring(2).StartsWith(
                                                                                                                                 "Microsoft.", StringComparison.Ordinal))))
                {
                    // Use the same link type as a core framework class
                    targetFound = targets.TryGetValue("T:System.Object", out target, out type);

                    // We don't have a target in this case so links to overloads pages won't work.  Also note
                    // that the link text will be generated from the ID which shouldn't make much of a difference
                    // in most cases.  If either case is an issue, the Additional Reference Links SHFB plug-in
                    // can be used to generate valid link target data.
                    target = null;
                }

                if (!targetFound)
                {
                    // If not being rendered as a link, don't report a warning
                    if (link.RenderAsLink && targetId != key)
                    {
                        this.WriteMessage(key, MessageLevel.Warn, "Unknown reference link target '{0}'.", targetId);
                    }

                    // !EFW - Turn off the Show Parameters option for unresolved elements except methods.  If
                    // not, it outputs an empty "()" after the member name which looks odd.
                    if (targetId[0] != 'M')
                    {
                        options &= ~DisplayOptions.ShowParameters;
                    }
                }
                else
                {
                    // If overload is preferred and found, change targetId and make link options hide parameters
                    if (link.PreferOverload && target != null)
                    {
                        bool isConversionOperator = false;

                        MethodTarget method = target as MethodTarget;

                        if (method != null)
                        {
                            isConversionOperator = method.IsConversionOperator;
                        }

                        MemberTarget member = target as MemberTarget;

                        // If conversion operator is found, always link to individual topic
                        if (member != null && !String.IsNullOrEmpty(member.OverloadId) && !isConversionOperator)
                        {
                            Target overloadTarget = targets[member.OverloadId];

                            if (overloadTarget != null)
                            {
                                target   = overloadTarget;
                                targetId = overloadTarget.Id;
                            }
                        }

                        // If individual conversion operator is found, always display parameters
                        if (isConversionOperator && member != null && !String.IsNullOrEmpty(member.OverloadId))
                        {
                            options = options | DisplayOptions.ShowParameters;
                        }
                        else
                        {
                            options = options & ~DisplayOptions.ShowParameters;
                        }
                    }
                }

                // Suppress the link if so requested.  Links to this page are not live.
                if (!link.RenderAsLink)
                {
                    type = ReferenceLinkType.None;
                }
                else
                if (targetId == key)
                {
                    type = ReferenceLinkType.Self;
                }
                else
                if (target != null && targets.TryGetValue(key, out keyTarget) && target.File == keyTarget.File)
                {
                    type = ReferenceLinkType.Self;
                }

                // !EFW - Redirect enumeration fields to the containing enumerated type so that we
                // get a valid link target.  Enum fields don't have a topic to themselves.
                if (type != ReferenceLinkType.None && type != ReferenceLinkType.Self && type != ReferenceLinkType.Local &&
                    targetId.StartsWith("F:", StringComparison.OrdinalIgnoreCase))
                {
                    MemberTarget member = target as MemberTarget;

                    if (member != null)
                    {
                        SimpleTypeReference typeRef = member.ContainingType as SimpleTypeReference;

                        if (typeRef != null && targets[typeRef.Id] is EnumerationTarget)
                        {
                            targetId = typeRef.Id;
                        }
                    }
                }

                // Get MSDN endpoint if needed
                if (type == ReferenceLinkType.Msdn)
                {
                    if (msdnResolver != null && !msdnResolver.IsDisabled)
                    {
                        msdnUrl = msdnResolver.GetMsdnUrl(targetId);

                        if (String.IsNullOrEmpty(msdnUrl))
                        {
                            // If the web service failed, report the reason
                            if (msdnResolver.IsDisabled)
                            {
                                this.WriteMessage(key, MessageLevel.Warn, "MSDN web service failed.  No " +
                                                  "further look ups will be performed for this build.\r\nReason: {0}",
                                                  msdnResolver.DisabledReason);
                            }
                            else
                            {
                                this.WriteMessage(key, MessageLevel.Warn, "MSDN URL not found for target '{0}'.",
                                                  targetId);
                            }

                            type = ReferenceLinkType.None;
                        }
                    }
                    else
                    {
                        type = ReferenceLinkType.None;
                    }
                }

                // Write opening link tag and target info
                XmlWriter writer = linkNode.InsertAfter();

                switch (type)
                {
                case ReferenceLinkType.None:
                    writer.WriteStartElement("span");

                    // If the link was intentionally suppressed, write it out as an identifier (i.e. links
                    // in the syntax section).
                    if (link.RenderAsLink)
                    {
                        writer.WriteAttributeString("class", "nolink");
                    }
                    else
                    {
                        writer.WriteAttributeString("class", "identifier");
                    }
                    break;

                case ReferenceLinkType.Self:
                    writer.WriteStartElement("span");
                    writer.WriteAttributeString("class", "selflink");
                    break;

                case ReferenceLinkType.Local:
                    // Format link with prefix and/or postfix
                    string href = String.Format(CultureInfo.InvariantCulture, hrefFormat, target.File);

                    // Make link relative, if we have a baseUrl
                    if (baseUrl != null)
                    {
                        href = href.GetRelativePath(document.EvalXPathExpr(baseUrl, "key", key));
                    }

                    writer.WriteStartElement("a");
                    writer.WriteAttributeString("href", href);
                    break;

                case ReferenceLinkType.Msdn:
                    writer.WriteStartElement("a");
                    writer.WriteAttributeString("href", msdnUrl);
                    writer.WriteAttributeString("target", linkTarget);
                    break;

                case ReferenceLinkType.Id:
                    writer.WriteStartElement("a");
                    writer.WriteAttributeString("href", ("ms-xhelp:///?Id=" + targetId).Replace("#", "%23"));
                    break;
                }

                // Write the link text
                if (String.IsNullOrEmpty(link.DisplayTarget))
                {
                    if (link.Contents == null)
                    {
                        if (target != null)
                        {
                            resolver.WriteTarget(target, options, writer);
                        }
                        else
                        {
                            Reference reference = TextReferenceUtilities.CreateReference(targetId);

                            if (reference is InvalidReference)
                            {
                                this.WriteMessage(key, MessageLevel.Warn,
                                                  "Invalid reference link target '{0}'.", targetId);
                            }

                            resolver.WriteReference(reference, options, writer);
                        }
                    }
                    else
                    {
                        do
                        {
                            link.Contents.WriteSubtree(writer);
                        } while(link.Contents.MoveToNext());
                    }
                }
                else
                {
                    if (link.DisplayTarget.Equals("content", StringComparison.OrdinalIgnoreCase) &&
                        link.Contents != null)
                    {
                        // Use the contents as an XML representation of the display target
                        Reference reference = XmlTargetDictionaryUtilities.CreateReference(link.Contents);
                        resolver.WriteReference(reference, options, writer);
                    }

                    if (link.DisplayTarget.Equals("format", StringComparison.OrdinalIgnoreCase) &&
                        link.Contents != null)
                    {
                        // Use the contents as a format string for the display target
                        string format = link.Contents.OuterXml;
                        string input  = null;

                        using (StringWriter textStore = new StringWriter(CultureInfo.InvariantCulture))
                        {
                            XmlWriterSettings settings = new XmlWriterSettings();
                            settings.ConformanceLevel = ConformanceLevel.Fragment;

                            using (XmlWriter xmlStore = XmlWriter.Create(textStore, settings))
                            {
                                if (target != null)
                                {
                                    resolver.WriteTarget(target, options, xmlStore);
                                }
                                else
                                {
                                    Reference reference = TextReferenceUtilities.CreateReference(targetId);
                                    resolver.WriteReference(reference, options, xmlStore);
                                }
                            }

                            input = textStore.ToString();
                        }

                        string output = String.Format(CultureInfo.InvariantCulture, format, input);

                        XmlDocumentFragment fragment = document.CreateDocumentFragment();
                        fragment.InnerXml = output;
                        fragment.WriteTo(writer);
                    }
                    else if (link.DisplayTarget.Equals("extension", StringComparison.OrdinalIgnoreCase) &&
                             link.Contents != null)
                    {
                        Reference extMethodReference = XmlTargetDictionaryUtilities.CreateExtensionMethodReference(link.Contents);
                        resolver.WriteReference(extMethodReference, options, writer);
                    }
                    else
                    {
                        // Use the display target value as a CER for the display target
                        TextReferenceUtilities.SetGenericContext(key);
                        Reference reference = TextReferenceUtilities.CreateReference(link.DisplayTarget);
                        resolver.WriteReference(reference, options, writer);
                    }
                }

                // Write the closing link tag
                writer.WriteEndElement();
                writer.Close();

                // Delete the original tag
                linkNode.DeleteSelf();
            }
        }
Example #2
0
        // component logic

        public override void Apply(XmlDocument document, string key)
        {
            // XmlNodeList link_nodes = document.SelectNodes("//referenceLink");
            XPathNodeIterator linkIterator = document.CreateNavigator().Select(referenceLinkExpression);

            XPathNavigator[] linkNodes = BuildComponentUtilities.ConvertNodeIteratorToArray(linkIterator);

            foreach (XPathNavigator linkNode in linkNodes)
            {
                // extract link information
                ReferenceLinkInfo2 link = ReferenceLinkInfo2.Create(linkNode);

                if (link == null)
                {
                    WriteMessage(MessageLevel.Warn, "Invalid referenceLink element.");
                }
                else
                {
                    // determine target, link type, and display options
                    string         targetId = link.Target;
                    DisplayOptions options  = link.DisplayOptions;
                    LinkType2      type     = LinkType2.None;

                    Target target = GetTarget(targetId);
                    if (target == null)
                    {
                        // no such target known; set link type to none and warn
                        type = LinkType2.None;
                        WriteMessage(MessageLevel.Warn, String.Format("Unknown reference link target '{0}'.", targetId));
                    }
                    else
                    {
                        // if overload is prefered and found, change targetId and make link options hide parameters
                        if (link.PreferOverload)
                        {
                            bool isConversionOperator = false;

                            MethodTarget method = target as MethodTarget;
                            if (method != null)
                            {
                                isConversionOperator = method.conversionOperator;
                            }

                            MemberTarget member = target as MemberTarget;

                            // if conversion operator is found, always link to individual topic.
                            if ((member != null) && (!String.IsNullOrEmpty(member.OverloadId)) && !isConversionOperator)
                            {
                                Target overloadTarget = targets[member.OverloadId];
                                if (overloadTarget != null)
                                {
                                    target   = overloadTarget;
                                    targetId = overloadTarget.Id;
                                }
                            }

                            // if individual conversion operator is found, always display parameters.
                            if (isConversionOperator && member != null && (!string.IsNullOrEmpty(member.OverloadId)))
                            {
                                options = options | DisplayOptions.ShowParameters;
                            }
                            else
                            {
                                options = options & ~DisplayOptions.ShowParameters;
                            }
                        }

                        // get stored link type
                        type = target.DefaultLinkType;

                        // if link type is local or index, determine which
                        if (type == LinkType2.LocalOrIndex)
                        {
                            if ((key != null) && targets.Contains(key) && (target.Container == targets[key].Container))
                            {
                                type = LinkType2.Local;
                            }
                            else
                            {
                                type = LinkType2.Index;
                            }
                        }
                    }

                    // links to this page are not live
                    if (targetId == key)
                    {
                        type = LinkType2.Self;
                    }
                    else if ((target != null) && (key != null) && targets.Contains(key) && (target.File == targets[key].File))
                    {
                        type = LinkType2.Self;
                    }

                    // get msdn or external endpoint, if needed
                    string externalUrl = null;
                    if (type == LinkType2.Msdn || type == LinkType2.External)
                    {
                        externalUrl = ResolveExternalUrl(targetId, type);
                        if (String.IsNullOrEmpty(externalUrl))
                        {
                            type = LinkType2.None;
                        }
                    }

                    // write opening link tag and target info
                    XmlWriter writer = linkNode.InsertAfter();
                    switch (type)
                    {
                    case LinkType2.None:
                        writer.WriteStartElement("span");
                        writer.WriteAttributeString("class", "nolink");
                        break;

                    case LinkType2.Self:
                        writer.WriteStartElement("span");
                        writer.WriteAttributeString("class", "selflink");
                        break;

                    case LinkType2.Local:
                        // format link with prefix and/or postfix
                        string href = String.Format(hrefFormat, target.File);

                        // make link relative, if we have a baseUrl
                        if (baseUrl != null)
                        {
                            href = BuildComponentUtilities.GetRelativePath(href, BuildComponentUtilities.EvalXPathExpr(document, baseUrl, "key", key));
                        }

                        writer.WriteStartElement("a");
                        writer.WriteAttributeString("href", href);
                        break;

                    case LinkType2.Index:
                        writer.WriteStartElement("mshelp", "link", "http://msdn.microsoft.com/mshelp");
                        writer.WriteAttributeString("keywords", targetId);
                        writer.WriteAttributeString("tabindex", "0");
                        break;

                    case LinkType2.Msdn:
                    case LinkType2.External:
                        writer.WriteStartElement("a");
                        writer.WriteAttributeString("href", externalUrl);
                        writer.WriteAttributeString("target", linkTarget);
                        break;
                    }

                    // write the link text
                    if (String.IsNullOrEmpty(link.DisplayTarget))
                    {
                        if (link.Contents == null)
                        {
                            if (target != null)
                            {
                                resolver.WriteTarget(target, options, writer);
                            }
                            else
                            {
                                //Console.WriteLine("Attemting to create reference");
                                Reference reference = TextReferenceUtilities.CreateReference(targetId);
                                //Console.WriteLine("Returned");
                                if (reference is InvalidReference)
                                {
                                    WriteMessage(MessageLevel.Warn, String.Format("Invalid reference link target '{0}'.", targetId));
                                }
                                resolver.WriteReference(reference, options, writer);
                            }
                        }
                        else
                        {
                            // write contents to writer
                            link.Contents.WriteSubtree(writer);
                        }
                    }
                    else
                    {
                        //Console.WriteLine("Display target = {0}", link.DisplayTarget);
                        if ((String.Compare(link.DisplayTarget, "content", true) == 0) && (link.Contents != null))
                        {
                            // Use the contents as an XML representation of the display target

                            //Console.WriteLine(link.Contents.NodeType);
                            Reference reference = XmlTargetCollectionUtilities.CreateReference(link.Contents);
                            //Console.WriteLine(reference.GetType().FullName);
                            resolver.WriteReference(reference, options, writer);
                        }
                        if ((String.Compare(link.DisplayTarget, "format", true) == 0) && (link.Contents != null))
                        {
                            // Use the contents as a format string for the display target

                            string format = link.Contents.OuterXml;
                            //Console.WriteLine("format = {0}", format);

                            string       input     = null;
                            StringWriter textStore = new StringWriter();
                            try {
                                XmlWriterSettings settings = new XmlWriterSettings();
                                settings.ConformanceLevel = ConformanceLevel.Fragment;

                                XmlWriter xmlStore = XmlWriter.Create(textStore, settings);
                                try {
                                    if (target != null)
                                    {
                                        resolver.WriteTarget(target, options, xmlStore);
                                    }
                                    else
                                    {
                                        Reference reference = TextReferenceUtilities.CreateReference(targetId);
                                        resolver.WriteReference(reference, options, xmlStore);
                                    }
                                } finally {
                                    xmlStore.Close();
                                }
                                input = textStore.ToString();
                            } finally {
                                textStore.Close();
                            }
                            //Console.WriteLine("input = {0}", input);

                            string output = String.Format(format, input);
                            //Console.WriteLine("output = {0}", output);

                            XmlDocumentFragment fragment = document.CreateDocumentFragment();
                            fragment.InnerXml = output;
                            fragment.WriteTo(writer);

                            //writer.WriteRaw(output);
                        }
                        else if ((String.Compare(link.DisplayTarget, "extension", true) == 0) && (link.Contents != null))
                        {
                            Reference extMethodReference = XmlTargetCollectionUtilities.CreateExtensionMethodReference(link.Contents);
                            resolver.WriteReference(extMethodReference, options, writer);
                        }
                        else
                        {
                            // Use the display target value as a CER for the display target

                            TextReferenceUtilities.SetGenericContext(key);
                            Reference reference = TextReferenceUtilities.CreateReference(link.DisplayTarget);
                            //Console.WriteLine("Reference is {0}", reference.GetType().FullName);
                            resolver.WriteReference(reference, options, writer);
                        }
                    }

                    // write the closing link tag
                    writer.WriteEndElement();
                    writer.Close();
                }

                // delete the original tag
                linkNode.DeleteSelf();
            }
        }