search

dotnet / docfx

Static site generator for .NET API documentation.
https://dotnet.github.io/docfx/
MIT License
4.06k stars 865 forks source link

ArgumentException: Illegal characters in path #5432

Closed Sharparam closed 11 months ago

Sharparam commented 4 years ago

Operation System: Windows 10

DocFX Version Used: 2.48.1

Template used: default

Steps to Reproduce:

  1. Grab Colore: https://github.com/chroma-sdk/Colore/tree/142ebfe84b6db47fe73c37c522e66eb1e7011ddf
  2. Build it in Release configuration.
  3. Run docfx docs/docfx.json from the repository root.

Expected Behavior: DocFx generates documentation.

Actual Behavior: DocFx fails with the following output:

[20-01-08 10:14:32.398]Info:[MetadataCommand.ExtractMetadata]Using msbuild C:\Program Files (x86)\Microsoft Visual Studio\2019\Enterprise\MSBuild\Current\Bin as inner compiler.
[20-01-08 10:14:32.606]Info:[MetadataCommand.ExtractMetadata]Loading projects...
[20-01-08 10:14:32.614]Info:[MetadataCommand.ExtractMetadata]Generating metadata for each project...
[20-01-08 10:14:33.040]Info:[MetadataCommand.ExtractMetadata]'E:/Users/adamh/Projects/CSharp/Colore/src/Colore/bin/Release/netstandard1.3/Colore.dll' keep up-to-date since '2020-01-08 22:14:24', cached intermediate result 'E:/Users/adamh/Projects/CSharp/Colore/src/Colore/bin/Release/netstandard1.3/obj/xdoc/cache/obj\yrgppxwo.gtm' is used.
[20-01-08 10:14:34.007]Info:[MetadataCommand.ExtractMetadata]Loading developer comments from file: E:/Users/adamh/Projects/CSharp/Colore/src/Colore/bin/Release/netstandard1.3/Colore.xml
[20-01-08 10:14:34.091]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.096]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.103]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.108]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.109]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.116]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.119]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.120]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.121]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.124]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.125]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.137]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.140]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.142]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.144]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.145]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.147]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.152]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.155]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.170]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.171]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.171]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.172]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.173]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.173]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.173]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.174]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.175]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.175]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.177]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.179]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.179]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.180]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.180]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.181]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.182]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.182]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.182]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.183]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.184]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.191]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.199]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.421]Info:[MetadataCommand]Completed Scope:MetadataCommand in 2038.6 milliseconds.
[20-01-08 10:14:34.421]Error:Error extracting metadata for E:/Users/adamh/Projects/CSharp/Colore/src/Colore/bin/Release/netstandard1.3/Colore.dll: System.ArgumentException: Illegal characters in path.
   at System.IO.Path.CheckInvalidPathChars(String path, Boolean checkAdditional)
   at System.IO.Path.Combine(String path1, String path2)
   at Microsoft.DocAsCode.Metadata.ManagedReference.ExtractMetadataWorker.<ResolveAndExportYamlMetadata>d__19.MoveNext()
   at System.Collections.Generic.List`1..ctor(IEnumerable`1 collection)
   at System.Linq.Enumerable.ToList[TSource](IEnumerable`1 source)
   at Microsoft.DocAsCode.Metadata.ManagedReference.ExtractMetadataWorker.<SaveAllMembersFromCacheAsync>d__13.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Microsoft.DocAsCode.Metadata.ManagedReference.ExtractMetadataWorker.<ExtractMetadataAsync>d__11.MoveNext()
[20-01-08 10:14:34.422]Info:Completed in 2043.1496 milliseconds

Build failed.
[20-01-08 10:14:34.427]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.427]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.428]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.428]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.428]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.428]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.429]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.429]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.429]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.429]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.429]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.430]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.430]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.430]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.430]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.430]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.431]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.431]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.431]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.431]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.432]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.432]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.432]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.432]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.432]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.433]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.433]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.433]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.433]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.434]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.434]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.434]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.434]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.434]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.435]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.435]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.435]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.435]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.435]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.436]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.436]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.436]Warning:[MetadataCommand.ExtractMetadata]Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.
[20-01-08 10:14:34.436]Error:Error extracting metadata for E:/Users/adamh/Projects/CSharp/Colore/src/Colore/bin/Release/netstandard1.3/Colore.dll: System.ArgumentException: Illegal characters in path.
   at System.IO.Path.CheckInvalidPathChars(String path, Boolean checkAdditional)
   at System.IO.Path.Combine(String path1, String path2)
   at Microsoft.DocAsCode.Metadata.ManagedReference.ExtractMetadataWorker.<ResolveAndExportYamlMetadata>d__19.MoveNext()
   at System.Collections.Generic.List`1..ctor(IEnumerable`1 collection)
   at System.Linq.Enumerable.ToList[TSource](IEnumerable`1 source)
   at Microsoft.DocAsCode.Metadata.ManagedReference.ExtractMetadataWorker.<SaveAllMembersFromCacheAsync>d__13.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Microsoft.DocAsCode.Metadata.ManagedReference.ExtractMetadataWorker.<ExtractMetadataAsync>d__11.MoveNext()
        42 Warning(s)
        1 Error(s)

Additional info:

The stack trace in the output doesn't say much, but after downloading the source for DocFx v2.48.1 and debugging it I see that the path it complains about is Colore.ColoreProvider.<CreateNativeAsync>d__2.yml. I don't know why it generates such a path though (the angle brackets are forbidden in file paths on Windows).

Debugger screenshot

Documentation generation has worked in the past, so something must have changed, but unsure what. I'll see if some older versions work.

Sharparam commented 4 years ago

On further inspection, rolling back to the previously working version (2.43.4) and a previous commit on my repo that is confirmed to have successfully generated docs it fails with the same error. So this must be due to something that has changed with the .NET build tools?

Edit: I can also confirm the same error occurs when using the dev branch of DocFx.

Edit 2: Similar to #4952, if I apply the below patch and generate metadata on my own, I can then successfully generate the HTML site with an existing build of DocFx.

https://gist.github.com/Sharparam/f73727aa916389266ac9060dac629f3f

(The diff is against v2.48.1, the change is to escape < and > in filenames by replacing them with a dash (-))

I can't do the whole flow with my self-built copy as, again similar to the linked issue, I get the below message after generating metadata:

[20-01-08 11:07:32.062]Warning:[BuildCommand.BuildCore.Build Document.LinkPhaseHandlerWithIncremental.Apply Templates]There is no template processing document type(s): Conceptual,ManagedReference,Toc
superyyrrzz commented 4 years ago

I cannot tell why the filename is like this. Usually, it should be Colore.ColoreProvider.yml. Need more investigation into this.

I can't do the whole flow with my self-built copy

For this, run build.cmd to ensure the required resources are there. After that, it is enough to simply build the solution to get a workable docfx.

Sharparam commented 4 years ago

It seems to be related to at least a few things:

Looking at the site I get generated (not using static TOC so has to be served with docfx serve or similar): _site.zip

For ColoreProvider, each async method gets one of these weird entries generated, containing references to the async state machine and other related stuff.

In the Devices, there is a (private) method BuildMetadataCache that collects all fields in its own class and generates some stuff from it, collecting the fields is done with:

var fields = typeof(Devices).GetFields(BindingFlags.Static | BindingFlags.Public).Where(p => p.FieldType == typeof(Guid));

The predicate function used in the Where gets generated as a field called <>9__30_0 in the Devices.<>c class.

I don't know enough about C# internals to know what all this really means, but maybe it will be useful for further investigation.

Sharparam commented 4 years ago

After updating to DocFx 2.49, I'm now receiving a different error:

[20-02-29 11:37:05.253]Info:[ExtractMetadata]Using msbuild C:\Program Files (x86)\Microsoft Visual Studio\2019\Enterprise\MSBuild\Current\Bin as inner compiler.
[20-02-29 11:37:05.448]Info:[ExtractMetadata]Loading projects...
[20-02-29 11:37:05.502]Info:[ExtractMetadata]Generating metadata for each project...
[20-02-29 11:37:05.874]Info:[ExtractMetadata]'E:/Users/adamh/Projects/CSharp/Colore/src/Colore/bin/Release/netstandard1.3/Colore.dll' keep up-to-date since '2020-02-29 11:33:00', cached intermediate result 'E:/Users/adamh/Projects/CSharp/Colore/src/Colore/bin/Release/netstandard1.3/obj/xdoc/cache/obj\ogou3zgk.yxv' is used.
[20-02-29 11:37:06.805]Info:[ExtractMetadata]Loading developer comments from file: E:/Users/adamh/Projects/CSharp/Colore/src/Colore/bin/Release/netstandard1.3/Colore.xml
[20-02-29 11:37:07.011]Error:Error extracting metadata for E:/Users/adamh/Projects/CSharp/Colore/src/Colore/bin/Release/netstandard1.3/Colore.dll: System.ArgumentNullException: Value cannot be null.
Parameter name: key
   at System.ThrowHelper.ThrowArgumentNullException(ExceptionArgument argument)
   at System.Collections.Generic.Dictionary`2.FindEntry(TKey key)
   at System.Collections.Generic.Dictionary`2.TryGetValue(TKey key, TValue& value)
   at Microsoft.DocAsCode.Metadata.ManagedReference.CopyInherited.Copy(MetadataItem dest, String srcName, ResolverContext context)
   at Microsoft.DocAsCode.Metadata.ManagedReference.CopyInherited.InheritDoc(MetadataItem dest, ResolverContext context)
   at Microsoft.DocAsCode.Metadata.ManagedReference.CopyInherited.<>c__DisplayClass0_0.<Run>b__1(MetadataItem current, MetadataItem parent)
   at Microsoft.DocAsCode.Common.TreeIterator.Preorder[T](T current, T parent, Func`2 childrenGetter, Func`3 action)
   at Microsoft.DocAsCode.Common.TreeIterator.Preorder[T](T current, T parent, Func`2 childrenGetter, Func`3 action)
   at Microsoft.DocAsCode.Common.TreeIterator.Preorder[T](T current, T parent, Func`2 childrenGetter, Func`3 action)
   at Microsoft.DocAsCode.Metadata.ManagedReference.CopyInherited.Run(MetadataModel yaml, ResolverContext context)
   at Microsoft.DocAsCode.Metadata.ManagedReference.YamlMetadataResolver.ExecutePipeline(MetadataModel yaml, ResolverContext context)
   at Microsoft.DocAsCode.Metadata.ManagedReference.YamlMetadataResolver.ResolveMetadata(Dictionary`2 allMembers, Dictionary`2 allReferences, Boolean preserveRawInlineComments)
   at Microsoft.DocAsCode.Metadata.ManagedReference.ExtractMetadataWorker.<ResolveAndExportYamlMetadata>d__19.MoveNext()
   at System.Collections.Generic.List`1..ctor(IEnumerable`1 collection)
   at System.Linq.Enumerable.ToList[TSource](IEnumerable`1 source)
   at Microsoft.DocAsCode.Metadata.ManagedReference.ExtractMetadataWorker.<SaveAllMembersFromCacheAsync>d__13.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Microsoft.DocAsCode.Metadata.ManagedReference.ExtractMetadataWorker.<ExtractMetadataAsync>d__11.MoveNext()
[20-02-29 11:37:07.013]Info:Completed in 1777.9178 milliseconds

Build failed.
[20-02-29 11:37:07.018]Error:Error extracting metadata for E:/Users/adamh/Projects/CSharp/Colore/src/Colore/bin/Release/netstandard1.3/Colore.dll: System.ArgumentNullException: Value cannot be null.
Parameter name: key
   at System.ThrowHelper.ThrowArgumentNullException(ExceptionArgument argument)
   at System.Collections.Generic.Dictionary`2.FindEntry(TKey key)
   at System.Collections.Generic.Dictionary`2.TryGetValue(TKey key, TValue& value)
   at Microsoft.DocAsCode.Metadata.ManagedReference.CopyInherited.Copy(MetadataItem dest, String srcName, ResolverContext context)
   at Microsoft.DocAsCode.Metadata.ManagedReference.CopyInherited.InheritDoc(MetadataItem dest, ResolverContext context)
   at Microsoft.DocAsCode.Metadata.ManagedReference.CopyInherited.<>c__DisplayClass0_0.<Run>b__1(MetadataItem current, MetadataItem parent)
   at Microsoft.DocAsCode.Common.TreeIterator.Preorder[T](T current, T parent, Func`2 childrenGetter, Func`3 action)
   at Microsoft.DocAsCode.Common.TreeIterator.Preorder[T](T current, T parent, Func`2 childrenGetter, Func`3 action)
   at Microsoft.DocAsCode.Common.TreeIterator.Preorder[T](T current, T parent, Func`2 childrenGetter, Func`3 action)
   at Microsoft.DocAsCode.Metadata.ManagedReference.CopyInherited.Run(MetadataModel yaml, ResolverContext context)
   at Microsoft.DocAsCode.Metadata.ManagedReference.YamlMetadataResolver.ExecutePipeline(MetadataModel yaml, ResolverContext context)
   at Microsoft.DocAsCode.Metadata.ManagedReference.YamlMetadataResolver.ResolveMetadata(Dictionary`2 allMembers, Dictionary`2 allReferences, Boolean preserveRawInlineComments)
   at Microsoft.DocAsCode.Metadata.ManagedReference.ExtractMetadataWorker.<ResolveAndExportYamlMetadata>d__19.MoveNext()
   at System.Collections.Generic.List`1..ctor(IEnumerable`1 collection)
   at System.Linq.Enumerable.ToList[TSource](IEnumerable`1 source)
   at Microsoft.DocAsCode.Metadata.ManagedReference.ExtractMetadataWorker.<SaveAllMembersFromCacheAsync>d__13.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Microsoft.DocAsCode.Metadata.ManagedReference.ExtractMetadataWorker.<ExtractMetadataAsync>d__11.MoveNext()
        0 Warning(s)
        1 Error(s)

Unclear if this is still related to the same cause as above, will need to investigate.

Edit: This seems to actually be this issue: #5536.

If that issue is fixed the root issue of this issue may still be present, however.

Sharparam commented 4 years ago

Can confirm that when I apply the fix from #5561 to solve #5536, the original error message about invalid characters in path comes back.

Edit: So this is on DocFx version 2.49.

Sharparam commented 4 years ago

@superyyrrzz I have created this MWE to produce the error:

namespace DocFxIssueTest
{
    using System.Threading.Tasks;

    public static class TestClass
    {
        public static async Task<int> TestAsync()
        {
            await Task.Delay(50);
            return 42;
        }
    }
}

If you try to generate docs for this class (targeting either .NET Standard 1.3 or latest 2.1), DocFx will produce the errors described above.

So this seems to affect any code that uses async functionalities? But if so, it should be affecting many more people than just me. Can you test this and see if you get the error yourself? Or could this be something unique to my setup?

Sharparam commented 4 years ago

Still an issue as of latest 2.55 version. However, it seems the metadata generation now works properly for netstandard2.1 projects.

The "Illegal characters in path" appears when I run DocFx against a netstandard1.3 binary, but not against a netstandard2.1 binary.

Does this bring any clarity?

mikasoukhov commented 3 years ago

2.58.2 - same error.

at System.IO.Path.CheckInvalidPathChars(String path, Boolean checkAdditional) at System.IO.Path.Combine(String path1, String path2) at Microsoft.DocAsCode.Metadata.ManagedReference.ExtractMetadataWorker.d19.MoveNext() at System.Collections.Generic.List1..ctor(IEnumerable1 collection) at System.Linq.Enumerable.ToList[TSource](IEnumerable`1 source) at Microsoft.DocAsCode.Metadata.ManagedReference.ExtractMetadataWorker.d13.MoveNext() --- End of stack trace from previous location where exception was thrown --- at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task) at Microsoft.DocAsCode.Metadata.ManagedReference.ExtractMetadataWorker.d__11.MoveNext()

mikasoukhov commented 3 years ago

Ok, I've got the source.

Reflector tries to get all public members. Including like that MyNamespace.MyClass.<_name>e__FixedBuffer (auto-gen class for these things https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/unsafe-code#fixed-size-buffers ). And it is failed when ExtractMetadataWorker call Path.Combine.

I believe need more filtering for extracted metas.

tom-weiland commented 1 year ago

Getting the same error with DocFX 2.58.9:

Error:Error extracting metadata for D:/tomdw/Documents/Programming/Flax/FlaxDocs/FlaxEngine/Binaries/Editor/Win64/Development/FlaxEngine.CSharp.dll: System.ArgumentException: Illegal characters in path.
   at System.IO.Path.CheckInvalidPathChars(String path, Boolean checkAdditional)
   at System.IO.Path.Combine(String path1, String path2)
   at Microsoft.DocAsCode.Metadata.ManagedReference.ExtractMetadataWorker.<ResolveAndExportYamlMetadata>d__19.MoveNext()
   at System.Collections.Generic.List`1..ctor(IEnumerable`1 collection)
   at System.Linq.Enumerable.ToList[TSource](IEnumerable`1 source)
   at Microsoft.DocAsCode.Metadata.ManagedReference.ExtractMetadataWorker.<SaveAllMembersFromCacheAsync>d__13.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Microsoft.DocAsCode.Metadata.ManagedReference.ExtractMetadataWorker.<ExtractMetadataAsync>d__11.MoveNext()

I also tried it with the latest version (v2.70.4), where the error is more useful because it mentions the name of the file it's trying to generate:

Error: The filename, directory name, or volume label syntax is incorrect. :
'D:\tomdw\Documents\Programming\Flax\FlaxDocs\api\FlaxEngine.ProfilerCPU.Event.<Name0>e__FixedBuffer.yml'

As mentioned by @mikasoukhov, this seems to be caused by the angle brackets (<>) in the names of auto-generated structs, in my case from the following code (source):

public unsafe string Name
{
    get
    {
        fixed (short* name = Name0)
        {
            return new string((char*)name);
        }
    }
}

DocFX tries to create a yml file for this auto-generated struct using its name, but fails because angle brackets are not allowed in Windows file paths. As far as I know, Linux doesn't have that same restriction which explains why the FlaxDocs GitHub action works without issue, but I (on Windows) can't build the documentation locally. Cloning the FlaxDocs repo and running the build_all.bat file on a Windows machine should reproduce the error.

Since this isn't an issue on Linux, resolving it isn't particularly urgent for this project, but I was hoping to update the DocFX version and then make some other changes, and not being able to build the docs locally to ensure I haven't broken anything makes that difficult :/