3

I'm digging into DocFX. My projects are all using either .NET Standard 2.1 or 6.

I've come across an issue where classes, structs, interfaces that are in either System.* or Microsoft.* are not being resolved.

The DocFX metadata command generates warning messages:

Warning:[ExtractMetadata]Invalid cref value "!:ArgumentNullException" found in triple-slash-comments for .ctor defined ..., ignored.
Warning:[ExtractMetadata]Invalid cref value "!:ArgumentException" found in triple-slash-comments for .ctor defined in ... , ignored.
Warning:[ExtractMetadata]Invalid cref value "!:CancellationToken.None" found in triple-slash-comments for .ctor defined in ..., ignored.
Warning:[ExtractMetadata]Invalid cref value "!:IServiceProvider" found in triple-slash-comments for Run defined in ... , ignored.
Warning:[ExtractMetadata]Invalid cref value "!:InvalidOperationException" found in triple-slash-comments for Run defined in ... , ignored.
Warning:[ExtractMetadata]Invalid cref value "!:DateTime" found in triple-slash-comments for Run defined in ... , ignored.
Warning:[ExtractMetadata]Invalid cref value "!:Action" found in triple-slash-comments for Run defined in ... , ignored.
Warning:[ExtractMetadata]Invalid cref value "!:Task" found in triple-slash-comments for Run defined in ... , ignored.

I have the <see cref="Exception"/> tag in the triple slash comment. There are no issues compiling.

Any idea how to resolve this?

Thanks.

mhsimkin
  • 311
  • 4
  • 15
  • I've been stuck on this as well. Like @nrmontagne said, you do need `xrefService` element in `docfx.json`. Unfortunately though, it doesn't seem to be the only issue. I've found out that if I included **.cs instead of **.csproj in metadata source files configuration, a lot of `System.*` gets resolved. Unfortunately, there are other problems that comes with not using projects as the source. – Crono Oct 17 '22 at 17:23

1 Answers1

1

It happens when you are missing the xrefService field in your docfx.json configuration file. See DocFX Documentation for more details.

nrmontagne
  • 151
  • 1
  • 5
  • I have the same problem and I do have the `xrefService` field set to `[ "https://xref.docs.microsoft.com/query?uid={uid}" ]`. It seems to work for markdown files, but it doesn't cause `see[@cref]` elements from XML doc comments to be transformed like the rest. – Crono Oct 17 '22 at 16:45
  • @Crono, it is my understanding that 'cref' is used to reference members of your project and that you should use 'href' instead. – nrmontagne Oct 18 '22 at 17:51
  • Thanks for coming back at me. I've managed to make it work in the end with `cref` - a must if you want IDE intellisense and code analysis tools to work as designed. Not sure what the original issue was but I'm suspecting cached files from previous failing builds to be in cause. As soon as I could get back to a clean build state, DocFX started working as expected. – Crono Oct 18 '22 at 18:28