Illegal Characters in Path error when using DocFx

[DigitalFlow]

Description

When running DocFx targets from within FAKE, the execution breaks due to an illegal characters in path exception.
It was working previously and I did not change anything since the last successful runs, maybe a FAKE update broke it?

The error thrown is:
`

"C:\Git\FAKE-DocFx-Issue\packages\docfx.console\tools\docfx.exe" metadata "docs\docfx.json" "--output=""" "--filter=""" "--globalNamespaceId=""" "--property=""" "--log=""" "--repositoryRoot=""" "--correlationId=""" (In: false, Out: false, Err: false)
[18-11-05 10:53:43.241]Error:System.ArgumentException: Illegales Zeichen im Pfad.
bei System.IO.Path.CheckInvalidPathChars(String path, Boolean checkAdditional)
bei System.IO.Path.InternalGetDirectoryName(String path)
bei Microsoft.DocAsCode.Common.ReportLogListener..ctor(String reportPath, String repoRoot, String root)
bei Microsoft.DocAsCode.SubCommands.CommandCreator2.Create(String[] args, ISubCommandController controller, SubCommandParseOption option) bei Microsoft.DocAsCode.SubCommands.CommandController.Create() bei Microsoft.DocAsCode.Program.ExecSubCommand(String[] args) docfx 2.40.1.0

I tried copying the quoted parameters and removing the quotes and escapers from them. It worked afterwards, so it seems as if those parameters should not be escaped like that.

Repro steps

Steps to reproduce:

1. Clone repo from https:/DigitalFlow/FAKE-DocFx-Issue

2. Run build.cmd

3. Execution should fail with error as above

Expected behavior

There should be no illegal path error.

Actual behavior

An illegal characters in path error is being thrown.

Known workarounds

None that I know of.

Related information

• Operating system: Windows 10
• Branch: Master
• .NET Runtime, CoreCLR or Mono Version:
  `
  C:\Git\FAKE-DocFx-Issue>dotnet --info
  .NET Core SDK (gemäß "global.json"):
  Version: 2.1.402
  Commit: 3599f217f4

Laufzeitumgebung:
OS Name: Windows
OS Version: 10.0.14393
OS Platform: Windows
RID: win10-x64
Base Path: C:\Program Files\dotnet\sdk\2.1.402\

Host (useful for support):
Version: 2.1.4
Commit: 85255dde3e

.NET Core SDKs installed:
1.0.4 [C:\Program Files\dotnet\sdk]
2.1.103 [C:\Program Files\dotnet\sdk]
2.1.202 [C:\Program Files\dotnet\sdk]
2.1.300 [C:\Program Files\dotnet\sdk]
2.1.402 [C:\Program Files\dotnet\sdk]

.NET Core runtimes installed:
Microsoft.AspNetCore.All 2.1.0 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.All]
Microsoft.AspNetCore.All 2.1.4 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.All]
Microsoft.AspNetCore.App 2.1.0 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.AspNetCore.App 2.1.4 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.NETCore.App 1.0.5 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 1.1.2 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 2.0.6 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 2.0.9 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 2.1.0 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 2.1.4 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]

To install additional .NET Core runtimes or SDKs:
https://aka.ms/dotnet-download
`

• Indications of severity
• Version of FAKE (4.X, 5.X): 5.3
• (if performance issue) Performance information, links to performance testing scripts

[matthid]

Yes the quotes look a bit broken

[DigitalFlow]

As I found out, when escaping empty strings as "--arg=\"\"", the programm is passed the parameters as --arg="\", which can be seen in this error message:

Warning:Config file "docs\docfx.json" is found in command line! This file and ONLY this file will be used in generating metadata, other command line parameters **"\"** will be ignored.

As I found out, escaping of quotes should be done using back ticks in PowerShell and in the command line.
@matthid Would you be fine with me submitting a PR which changes quote escaping in CmdLineParsing.fs?

EDIT: Turns out escaping with backticks only works for powershell...

[matthid]

@DigitalFlow Escaping empty strings as "" is correct, what's broken here is how the DocFx module tries to build the argument string. In fact it doesn't need to as it is much safer to just build an argument list and use the Args and Arguments modules.

PR is welcome ;)

[DigitalFlow]

@matthid Alright, I'll submit a PR to fix this. For the meantime: Process.shellExec is a temporary workaround:

Process.shellExec
            { ExecParams.Empty with
                Program = @"packages\docfx.console\tools\docfx.exe"
                CommandLine = @"metadata ""docs\\docfx.json"""
                Args = [] }
        |> ignore

I think the Args module won't be needed in here, as this is what is escaping my commands, which I don't want. I'll take a look at the Arguments module.

[DigitalFlow]

@matthid
I have seen multiple cases where FAKE modules use sprintf for creating the command, as well as some that still use the Process functions which have been deprecated.

I checked the Arguments.OfArgs function by using

Arguments.OfArgs([| @"--output="""""; @"--fileFilter=""""" |])

Unfortunately this also produces the output that I do not want:
"--output=\"\"" "--fileFilter=\"t\""

[matthid]

But what you want is Arguments.OfArgs([| @"--output="; @"--fileFilter=" |]), correct?

[kblohm]

This broke in the refactoring of the ProcessModule, so you can use an older version as a workaround.
Version 5.0.0 works for me.
Line 26 is the broken one:

let private stringParam (paramName,paramValue) = Process.stringParam (paramName, Process.quoteIfNeeded paramValue)

Process.stringParam returns a None if the string is empty. But Procees.quoteIfNeeded now always returns a quoted string. Always quoting would be fine, but it also returns a quoted string when the the string is empty. So we always get back at least "".

@matthid: Is it intended that the ArgumentsModule returns quotes for an empty string? That seems strange.

[matthid]

@kblohm yes because otherwise the invariant Arguments.FromCommandLineString(Arguments.ToCommandLineString( args ) ) = args doesn't hold

[matthid]

Or put in other words you cannot tell the difference between [ "" ] and [ ] but they are obviously different, therefore an empty argument needs quotes.