Skip to content

Support for .NET Core Tooling Preview3+ projects #1254

New issue
New issue
Closed
Closed
Support for .NET Core Tooling Preview3+ projects#1254
Assignees
vicancy
@foxbot

Description

@foxbot
foxbot
opened on Jan 30, 2017

Support for .NET Core Tooling Preview3+ projects

When building API documentation for a project that uses .NET Core Preview 3 or higher (csproj), the build fails, because (roslyn?) is unable to parse PackageReference tags

Functional impact

API documentation can not be built for projects that use .NET Core

Minimal repro steps

  1. Create a docFx project
  2. Add a metadata reference to a csproj file

Expected result

The build would succeed and API documentation would be built.

Actual result

During the 'generating metadata' phase of the build, a warning is thrown opening the project.
Warning: Error opening project <project>.csproj: The attribute "Version" in element <PackageReference> is unrecognized.. Ignored.

No API documentation is built.

Further technical details

N/A

Sample csproj/docfx.json for reference

Activity

superyyrrzz

superyyrrzz commented on Feb 14, 2017

@superyyrrzz
superyyrrzz
on Feb 14, 2017
Contributor

Yes, Roslyn should be updated to support it. Currently we are waiting for its official release.

superyyrrzz

superyyrrzz commented on Feb 15, 2017

@superyyrrzz
superyyrrzz
on Feb 15, 2017
Contributor

Seems Roslyn 2.0-rc4 can open new csproj, but fail to extract info from it.

superyyrrzz
mentioned this on Feb 17, 2017
cpx86

cpx86 commented on Feb 20, 2017

@cpx86
cpx86
on Feb 20, 2017

Is there any work being done on this? VS2017 is just around the corner, and for libraries targeting the latest dotnet version, not being able to use DocFx is a bit of a problem.

fubar-coder
mentioned this on Feb 23, 2017
DustinKingen

DustinKingen commented on Feb 25, 2017

@DustinKingen
DustinKingen
on Feb 25, 2017

I encountered this today too. I'm using .NET Core SDK 1.0 rc4 build 004771.

I created a new project:

C:\Code> mkdir MyApp\src\App

C:\Code> cd MyApp

C:\Code\MyApp> dotnet new console -o .\src\App
Content generation time: 42.4024 ms
The template "Console Application" created successfully.

C:\Code\MyApp> dir .\src\App
 Directory of C:\Code\MyApp\src\App

02/24/2017  08:34 PM    <DIR>          .
02/24/2017  08:34 PM    <DIR>          ..
02/24/2017  08:34 PM               170 App.csproj
02/24/2017  08:34 PM               177 Program.cs

Added docfx:

C:\Code\MyApp> docfx init -q
Created folder C:\Code\MyApp\docfx_project\src
Created folder C:\Code\MyApp\docfx_project\api
Created folder C:\Code\MyApp\docfx_project\apidoc
Created folder C:\Code\MyApp\docfx_project\articles
Created folder C:\Code\MyApp\docfx_project\images
Created File C:\Code\MyApp\docfx_project\toc.yml
Created File C:\Code\MyApp\docfx_project\index.md
Created File C:\Code\MyApp\docfx_project\api\toc.yml
Created File C:\Code\MyApp\docfx_project\api\index.md
Created File C:\Code\MyApp\docfx_project\articles\toc.yml
Created File C:\Code\MyApp\docfx_project\articles\intro.md
Created File C:\Code\MyApp\docfx_project\.gitignore
Created File C:\Code\MyApp\docfx_project\api\.gitignore
Created config file C:\Code\MyApp\docfx_project\docfx.json
Successfully generated default docfx project to C:\Code\MyApp\docfx_project
Please run:
        docfx "C:\Code\MyApp\docfx_project\docfx.json" --serve
To generate a default docfx website.
Info: Completed executing in 167.4719 milliseconds.

C:\Code\MyApp> move docfx_project docs
        1 dir(s) moved.

C:\Code\MyApp>dotnet new classlib -o .\docs
Content generation time: 22.0136 ms
The template "Class library" created successfully.

Add nuget reference to docfx.console in docs.csproj.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Library</OutputType>
    <TargetFramework>netcoreapp1.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="docfx.console" Version="2.12.1" />
  </ItemGroup>

</Project>

Added src node to the docfx.json.

  "metadata": [
    {
      "src": [
        {
          "files": [
            "src/**.csproj"
          ],
          "exclude": [
            ...
          ],
          "src": "../"

Add a C# class src/App/Foo.cs:

namespace App
{
    /// <summary>
    /// Very useful class
    /// </summary>
    public class Foo { }
}

Build App:

C:\Code\MyApp>dotnet restore .\src\App\App.csproj
  Restoring packages for C:\Code\MyApp\src\App\App.csproj...
  Generating MSBuild file C:\Code\MyApp\src\App\obj\App.csproj.nuget.g.props.
  Generating MSBuild file C:\Code\MyApp\src\App\obj\App.csproj.nuget.g.targets.
  Writing lock file to disk. Path: C:\Code\MyApp\src\App\obj\project.assets.json
  Restore completed in 532.35 ms for C:\Code\MyApp\src\App\App.csproj.

  NuGet Config files used:
      C:\Users\<UserProfile>\AppData\Roaming\NuGet\NuGet.Config

  Feeds used:
      https://api.nuget.org/v3/index.json

C:\Code\MyApp>dotnet build .\src\App\App.csproj
Microsoft (R) Build Engine version 15.1.545.13942
Copyright (C) Microsoft Corporation. All rights reserved.

  App -> C:\Code\MyApp\src\App\bin\Debug\netcoreapp1.0\App.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:01.35

Build docfx:

C:\Code\MyApp>dotnet restore .\docs\docs.csproj
  Restoring packages for C:\Code\MyApp\docs\docs.csproj...
  Generating MSBuild file C:\Code\MyApp\docs\obj\docs.csproj.nuget.g.props.
  Generating MSBuild file C:\Code\MyApp\docs\obj\docs.csproj.nuget.g.targets.
  Writing lock file to disk. Path: C:\Code\MyApp\docs\obj\project.assets.json
  Restore completed in 538.22 ms for C:\Code\MyApp\docs\docs.csproj.

  NuGet Config files used:
      C:\Users\<UserProfile>\AppData\Roaming\NuGet\NuGet.Config

  Feeds used:
      https://api.nuget.org/v3/index.json

C:\Code\MyApp>dotnet build .\docs\docs.csproj
...
Build succeeded.

EXEC : warning : Error opening project C:/Code/MyApp/src/App/App.csproj: The default XML namespace of the project must be the MSBuild XML namespace. If the project is authored in the MSBuild 2003 format, please add xmlns="http://schemas.microsoft.com/developer/msbuild/2003" to the <Project> element. If the project has been authored in the old 1.0 or 1.2 format, please convert it to MSBuild 2003 format.. Ignored. [C:\Code\MyApp\docs\docs.csproj]
EXEC : warning : No metadata is generated for . [C:\Code\MyApp\docs\docs.csproj]
EXEC : warning : Error opening project C:/Code/MyApp/src/App/App.csproj: The default XML namespace of the project must be the MSBuild XML namespace. If the project is authored in the MSBuild 2003 format, please add xmlns="http://schemas.microsoft.com/developer/msbuild/2003" to the <Project> element. If the project has been authored in the old 1.0 or 1.2 format, please convert it to MSBuild 2003 format.. Ignored. [C:\Code\MyApp\docs\docs.csproj]
EXEC : warning : No metadata is generated for . [C:\Code\MyApp\docs\docs.csproj]
    4 Warning(s)
    0 Error(s)

Add xmlns to App.csproj

<Project Sdk="Microsoft.NET.Sdk" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp1.0</TargetFramework>
  </PropertyGroup>

</Project>

Rebuild App

C:\Code\MyApp>dotnet clean .\src\App\App.csproj
Microsoft (R) Build Engine version 15.1.545.13942
Copyright (C) Microsoft Corporation. All rights reserved.


C:\Code\MyApp>dotnet build .\src\App\App.csproj
Microsoft (R) Build Engine version 15.1.545.13942
Copyright (C) Microsoft Corporation. All rights reserved.

  App -> C:\Code\MyApp\src\App\bin\Debug\netcoreapp1.0\App.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:01.33

Rebuild docs

C:\Code\MyApp>dotnet clean .\docs\docs.csproj
Microsoft (R) Build Engine version 15.1.545.13942
Copyright (C) Microsoft Corporation. All rights reserved.


C:\Code\MyApp>dotnet build .\docs\docs.csproj
...
Build succeeded.

EXEC : warning : Cache for C:/Code/MyApp/src/App/App.csproj in C:\Code\MyApp\src\App\obj\xdoc\cache\final\1753801265 is corrupted [C:\Code\MyApp\docs\docs.csproj]
EXEC : warning : No metadata is generated for App. [C:\Code\MyApp\docs\docs.csproj]
EXEC : warning : Cache for C:/Code/MyApp/src/App/App.csproj in C:\Code\MyApp\src\App\obj\xdoc\cache\final\1753801265 is corrupted [C:\Code\MyApp\docs\docs.csproj]
EXEC : warning : No metadata is generated for App. [C:\Code\MyApp\docs\docs.csproj]
    4 Warning(s)
    0 Error(s)

That's as far as I've gotten.

foxbot

foxbot commented on Mar 5, 2017

@foxbot
foxbot
on Mar 5, 2017
Author

Looks like Roslyn 2.0-rc4 has made it's way on to the official NuGet feed, any progress on this?

sethjuarez

sethjuarez commented on Mar 8, 2017

@sethjuarez
sethjuarez
on Mar 8, 2017
Member

Any word on a fix for this?

rschili

rschili commented on Mar 8, 2017

@rschili
rschili
on Mar 8, 2017

As a workaround I'm including *.cs files directly now, that seems to work at least to some extent. Would love to see real support for the new .csproj files. The stable tooling has been released yesterday.

superyyrrzz

superyyrrzz commented on Mar 9, 2017

@superyyrrzz
superyyrrzz
on Mar 9, 2017
Contributor

I have still no success in parsing csproj using Roslyn 4.0-rc4. As @rschili mentioned above, including *.cs is a workaround for now. We are waiting for the stable version of Roslyn.

fubar-coder
mentioned this on Mar 9, 2017
fubar-coder

fubar-coder commented on Mar 10, 2017

@fubar-coder
fubar-coder
on Mar 10, 2017 · edited by fubar-coder

Why would anyone still use RC4 when RTM is available? BTW: RC4 is nearly a month old now (even the version on nuget.org).

EDIT: According to dotnet/roslyn#17439, the new multi-TFM MSBuild workspaces still aren't supported yet. So I guess that we have to wait for the next version.

cpx86

cpx86 commented on Mar 10, 2017

@cpx86
cpx86
on Mar 10, 2017

@fubar-coder The issue is that DocFx has been broken for MSBuild 2017 projects ever since they were introduced in RC3 and replaced project.json, and is still broken despite 2017 now being available as RTM.

ThadHouse

ThadHouse commented on Mar 14, 2017

@ThadHouse
ThadHouse
on Mar 14, 2017

The *.cs workaround does not seem to be working properly for me. It builds most of the docs, but misses some of the cross references that worked with the old setup. This is the last showstopper to being able to update all my repos to the new project format. Any ETA on when this will happen, especially now that 2017 is RTM and released?

jskeet
mentioned this on Mar 17, 2017

59 remaining items

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

    Development

    No branches or pull requests

      Participants

      @jskeet@sethjuarez@cpx86@vicancy@agc93

      Issue actions
        Support for .NET Core Tooling Preview3+ projects · Issue #1254 · dotnet/docfx