Replace file destination instructions for OpenAPI build-time documentation so projects can build correctly #34509

sander1095 · 2025-01-16T15:45:14Z

Internal previews

📄 File	🔗 Preview link
aspnetcore/fundamentals/openapi/aspnetcore-openapi.md	Generate OpenAPI documents

captainsafia · 2025-01-16T16:02:44Z

@sander1095 What operating system did you observe these issues on? When this doc was written we observed that ./ wasn't resilient to path handling in Windows.

sander1095 · 2025-01-16T16:21:37Z

Hi @captainsafia !

I'm running on Windows 11. You're correct, when running on Ubuntu (via WSL), ./ does work.

However, this means the docs should be updated:

to either reflect the fact that Windows and linux needs different paths, OR
the ./ needs to be replaced with . , which works both on Windows and Ubuntu (WSL).

This PR does the latter. I do not have a mac available to test this on. I believe we should advocate for a single solution that works for all OS's, as teams can use multiple OS's :).

I remember you having a mac? If this works on your machine, would you consider accepting this approach? If you'd like me to take a different path, let me know!

wadepickett · 2025-01-16T18:48:56Z

Just a side note with a verification point:
I just tested it on Windows 11 Enterprise v 10.0.26100 + .NET SDK 9.0.102 using the sample for this doc: https://github.com/dotnet/AspNetCore.Docs/tree/3b6e82c616db6bfa0ec5899c268b02fc001b6d99/aspnetcore/fundamentals/openapi/samples/9.x/WebMinOpenApi

It compiled, no build error for that particular setup using either:
<OpenApiDocumentsDirectory>./</OpenApiDocumentsDirectory>
or
<OpenApiDocumentsDirectory>.</OpenApiDocumentsDirectory>

Rick-Anderson · 2025-01-16T21:03:46Z

I found that here. See #33361

sander1095 · 2025-01-25T13:48:12Z

Does this mean this can get merged @captainsafia ?

wadepickett · 2025-01-29T21:11:00Z

@captainsafia, I think it is not clear where you would like us to go from here with this PR. Thoughts?

Rick-Anderson · 2025-01-29T21:26:56Z

@sander1095 what OS and version? What .NET version?

This happened on preview versions but was fixed in .NET 9 GA.

sander1095 · 2025-01-29T22:16:25Z

@Rick-Anderson

WSL (Ubuntu 22.04)

sander@PC-Sander:~$ dotnet --info
.NET SDK:
 Version:           9.0.100
 Commit:            a2bc464e40
 Workload version:  9.0.100-manifests.6bf02610
 MSBuild version:   17.12.7+a2bc464e4

Runtime Environment:
 OS Name:     ubuntu
 OS Version:  22.04
 OS Platform: Linux
 RID:         ubuntu.22.04-x64
 Base Path:   /usr/lib/dotnet/sdk/9.0.100/

.NET workloads installed:
There are no installed workloads to display.
Configured to use loose manifests when installing new manifests.

Host:
  Version:      9.0.0
  Architecture: x64
  Commit:       a2bc464e40

.NET SDKs installed:
  9.0.100 [/usr/lib/dotnet/sdk]

.NET runtimes installed:
  Microsoft.AspNetCore.App 9.0.0 [/usr/lib/dotnet/shared/Microsoft.AspNetCore.App]
  Microsoft.NETCore.App 9.0.0 [/usr/lib/dotnet/shared/Microsoft.NETCore.App]

Other architectures found:
  None

Environment variables:
  Not set

global.json file:
  Not found

Learn more:
  https://aka.ms/dotnet/info

Download .NET:
  https://aka.ms/dotnet/download

Windows 11 Pro (10.0.22631 Build 22631, 23H2)

.NET SDK:
 Version:           9.0.102
 Commit:            cb83cd4923
 Workload version:  9.0.100-manifests.4a54b1a6
 MSBuild version:   17.12.18+ed8c6aec5

Runtime Environment:
 OS Name:     Windows
 OS Version:  10.0.22631
 OS Platform: Windows
 RID:         win-x64
 Base Path:   C:\Program Files\dotnet\sdk\9.0.102\

.NET workloads installed:
There are no installed workloads to display.
Configured to use loose manifests when installing new manifests.

Host:
  Version:      9.0.1
  Architecture: x64
  Commit:       c8acea2262

.NET SDKs installed:
  6.0.428 [C:\Program Files\dotnet\sdk]
  8.0.300-preview.24203.14 [C:\Program Files\dotnet\sdk]
  9.0.102 [C:\Program Files\dotnet\sdk]

.NET runtimes installed:
  Microsoft.AspNetCore.App 6.0.36 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
  Microsoft.AspNetCore.App 8.0.2 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
  Microsoft.AspNetCore.App 8.0.12 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
  Microsoft.AspNetCore.App 9.0.1 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
  Microsoft.NETCore.App 6.0.36 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.NETCore.App 8.0.2 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.NETCore.App 8.0.12 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.NETCore.App 9.0.1 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.WindowsDesktop.App 6.0.36 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
  Microsoft.WindowsDesktop.App 8.0.2 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
  Microsoft.WindowsDesktop.App 8.0.12 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
  Microsoft.WindowsDesktop.App 9.0.1 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]

Other architectures found:
  x86   [C:\Program Files (x86)\dotnet]
    registered at [HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\x86\InstallLocation]

Environment variables:
  Not set

global.json file:
  Not found

Learn more:
  https://aka.ms/dotnet/info

Download .NET:
  https://aka.ms/dotnet/download

Building with ./

The final csproj

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

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <OpenApiDocumentsDirectory>./</OpenApiDocumentsDirectory>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.1" />
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.1">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

</Project>

Windows 11 Pro ❌

dotnet new webapi -f net9.0
dotnet add package Microsoft.Extensions.ApiDescription.Server -v 9.0.1 # Install the latest version from nuget
# Add <OpenApiDocumentsDirectory>./</OpenApiDocumentsDirectory> to the csproj
dotnet build

# ERROR
PS C:\projects\Personal\temp6> dotnet build
Restore complete (0,3s)
  temp6 failed with 2 error(s) (2,1s) → bin\Debug\net9.0\temp6.dll
    C:\Users\stenb\.nuget\packages\microsoft.extensions.apidescription.server\9.0.1\build\Microsoft.Extensions.ApiDescription.Server.targets(68,5): error : Missing required option '--project'.
    C:\Users\stenb\.nuget\packages\microsoft.extensions.apidescription.server\9.0.1\build\Microsoft.Extensions.ApiDescription.Server.targets(68,5): error MSB3073: The command "dotnet "C:\Users\stenb\.nuget\packages\microsoft.extensions.apidescription.server\9.0.1\build\../tools/dotnet-getdocument.dll" --assembly "C:\projects\Personal\temp6\bin\Debug\net9.0\temp6.dll" --file-list "obj\temp6.OpenApiFiles.cache" --framework ".NETCoreApp,Version=v9.0" --output "C:\projects\Personal\temp6\" --project "temp6" --assets-file "C:\projects\Personal\temp6\obj\project.assets.json" --platform "AnyCPU" " exited with code 1.

Build failed with 2 error(s) in 2,6s

WSL (Ubuntu 22.04) ✅

dotnet new webapi -f net9.0
dotnet add package Microsoft.Extensions.ApiDescription.Server -v 9.0.1 # Install the latest version from nuget
# Add <OpenApiDocumentsDirectory>./</OpenApiDocumentsDirectory> to the csproj
dotnet build

# SUCCESS
sander@PC-Sander:~/projects/temp$ dotnet build
Restore complete (0.5s)
  temp succeeded (2.6s) → bin/Debug/net9.0/temp.dll

Build succeeded in 3.4s

Building with .

The final csproj

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

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <OpenApiDocumentsDirectory>.</OpenApiDocumentsDirectory>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.1" />
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.1">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

</Project>

Windows 11 Pro ✅

dotnet new webapi -f net9.0
dotnet add package Microsoft.Extensions.ApiDescription.Server -v 9.0.1 # Install the latest version from nuget
# Add <OpenApiDocumentsDirectory>.</OpenApiDocumentsDirectory> to the csproj
dotnet build

# SUCCESS
PS C:\projects\Personal\temp6> dotnet build
Restore complete (0,3s)
  temp6 succeeded (0,7s) → bin\Debug\net9.0\temp6.dll

Build succeeded in 1,2s

WSL (Ubuntu 22.04) ✅

dotnet new webapi -f net9.0
dotnet add package Microsoft.Extensions.ApiDescription.Server -v 9.0.1 # Install the latest version from nuget
# Add <OpenApiDocumentsDirectory>.</OpenApiDocumentsDirectory> to the csproj
dotnet build

# SUCCESS
sander@PC-Sander:~/projects/temp$ dotnet build
Restore complete (0.5s)
  temp succeeded (2.6s) → bin/Debug/net9.0/temp.dll

Build succeeded in 3.4s

I hope this gives you all the info you need!

As far as I see it, this issue persists in .NET 9 GA but is fixed on both Windows and Ubuntu when using <OpenApiDocumentsDirectory>.</OpenApiDocumentsDirectory>, which is what this PR aims to fix in the docs.

Rick-Anderson · 2025-01-30T03:03:16Z

Just a side note with a verification point: I just tested it on Windows 11 Enterprise v 10.0.26100 + .NET SDK 9.0.102 using the sample for this doc: https://github.com/dotnet/AspNetCore.Docs/tree/3b6e82c616db6bfa0ec5899c268b02fc001b6d99/aspnetcore/fundamentals/openapi/samples/9.x/WebMinOpenApi

It compiled, no build error for that particular setup using either: <OpenApiDocumentsDirectory>./</OpenApiDocumentsDirectory> or <OpenApiDocumentsDirectory>.</OpenApiDocumentsDirectory>

That's not what @sander1095 and I found out. Easy to repo the failure

Looks like it never got fixed from when I reported it. Maybe I forgot to update the doc.

Rick-Anderson · 2025-01-30T03:49:34Z

@sander1095 thanks for reporting and fixing this. Sorry it took so long to accept your PR. Keep them coming and I promise next time more prompt attention.

sander1095 added 2 commits January 16, 2025 16:43

Replace ./ with . so projects build correctly based on docs

01aadcd

Replace the instructions too

c73bb05

sander1095 mentioned this pull request Jan 29, 2025

OpenAPI build-time generation's file destination is incorrect and causes build errors #34508

Closed

Rick-Anderson merged commit bdd5ca5 into dotnet:main Jan 30, 2025
3 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Replace file destination instructions for OpenAPI build-time documentation so projects can build correctly #34509

Replace file destination instructions for OpenAPI build-time documentation so projects can build correctly #34509

sander1095 commented Jan 16, 2025 •

edited by github-actions bot

Loading

captainsafia commented Jan 16, 2025

sander1095 commented Jan 16, 2025 •

edited

Loading

wadepickett commented Jan 16, 2025 •

edited

Loading

Rick-Anderson commented Jan 16, 2025 •

edited

Loading

sander1095 commented Jan 25, 2025

wadepickett commented Jan 29, 2025

Rick-Anderson commented Jan 29, 2025

sander1095 commented Jan 29, 2025 •

edited

Loading

Rick-Anderson commented Jan 30, 2025 •

edited

Loading

Rick-Anderson commented Jan 30, 2025

Replace file destination instructions for OpenAPI build-time documentation so projects can build correctly #34509

Replace file destination instructions for OpenAPI build-time documentation so projects can build correctly #34509

Conversation

sander1095 commented Jan 16, 2025 • edited by github-actions bot Loading

Internal previews

captainsafia commented Jan 16, 2025

sander1095 commented Jan 16, 2025 • edited Loading

wadepickett commented Jan 16, 2025 • edited Loading

Rick-Anderson commented Jan 16, 2025 • edited Loading

sander1095 commented Jan 25, 2025

wadepickett commented Jan 29, 2025

Rick-Anderson commented Jan 29, 2025

sander1095 commented Jan 29, 2025 • edited Loading

Building with ./

Windows 11 Pro ❌

WSL (Ubuntu 22.04) ✅

Building with .

Windows 11 Pro ✅

WSL (Ubuntu 22.04) ✅

Rick-Anderson commented Jan 30, 2025 • edited Loading

Rick-Anderson commented Jan 30, 2025

sander1095 commented Jan 16, 2025 •

edited by github-actions bot

Loading

sander1095 commented Jan 16, 2025 •

edited

Loading

wadepickett commented Jan 16, 2025 •

edited

Loading

Rick-Anderson commented Jan 16, 2025 •

edited

Loading

sander1095 commented Jan 29, 2025 •

edited

Loading

Rick-Anderson commented Jan 30, 2025 •

edited

Loading