Document breaking change: SDK no longer sets mono launch target for .NET Framework apps #51453
Conversation
- Document .NET SDK no longer automatically setting mono as launch target - Add article to SDK section in .NET 11 breaking changes - Update TOC and index files
There was a problem hiding this comment.
Pull request overview
Documents a .NET 11 SDK breaking change where dotnet run on Linux no longer auto-configures mono for .NET Framework apps, and wires the new article into the compatibility navigation.
Changes:
- Added a new .NET 11 SDK breaking change article describing the removed auto-configuration behavior.
- Updated the compatibility TOC to include the new SDK/MSBuild entry under .NET 11.
- Updated the .NET 11 breaking changes index page to list the new SDK/MSBuild breaking change.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
docs/core/compatibility/toc.yml |
Adds the new .NET 11 “SDK and MSBuild” node and links to the breaking change article. |
docs/core/compatibility/sdk/11/mono-launch-target-removed.md |
Introduces the breaking change article content for the removed mono launch target behavior. |
docs/core/compatibility/11.md |
Adds an “SDK and MSBuild” section and links the new breaking change article. |
| --- | ||
| title: "Breaking change: mono launch target not set for .NET Framework apps" | ||
| description: "Learn about the breaking change in .NET 11 where the .NET SDK no longer automatically sets mono as the launch target for .NET Framework applications on Linux." | ||
| ms.date: 02/03/2026 | ||
| ai-usage: ai-assisted | ||
| --- |
There was a problem hiding this comment.
The SDK breaking-change articles in docs/core/compatibility/sdk/* consistently include an ms.custom frontmatter entry linking to the tracking GitHub issue. This new article is missing that metadata, which makes it harder to trace back to the source issue (for example, see docs/core/compatibility/sdk/10.0/dotnet-watch-stderr.md:6 and docs/core/compatibility/sdk/9.0/default-rid.md:6). Add an ms.custom value (for example, the issue linked in the PR description) to match the established pattern.
| --- | ||
| title: "Breaking change: mono launch target not set for .NET Framework apps" |
There was a problem hiding this comment.
The PR description references the new article path as docs/core/compatibility/sdk/11.0/mono-launch-target-removed.md, but the file added (and linked from TOC/index) is docs/core/compatibility/sdk/11/mono-launch-target-removed.md. Update the PR description so it matches the actual location.
|
|
||
| ## Reason for change | ||
|
|
||
| This change was made because running .NET Framework applications on Linux using Mono is no longer officially supported. Mono ownership was transitioned last year, and the .NET SDK should not automatically configure launch targets for unsupported scenarios. |
There was a problem hiding this comment.
Avoid time-relative wording like "last year" in docs because it becomes incorrect over time. Rephrase this sentence to be time-agnostic (for example, refer to the Mono ownership transition without specifying relative timing, or include a specific month/year if needed).
| This change was made because running .NET Framework applications on Linux using Mono is no longer officially supported. Mono ownership was transitioned last year, and the .NET SDK should not automatically configure launch targets for unsupported scenarios. | |
| This change was made because running .NET Framework applications on Linux using Mono is no longer officially supported. Mono ownership has transitioned, and the .NET SDK should not automatically configure launch targets for unsupported scenarios. |
| ## Recommended action | ||
|
|
||
| If you need to continue running .NET Framework applications on Linux using Mono, you can manually configure the `RunCommand` and `RunArguments` properties in your project file. | ||
|
|
There was a problem hiding this comment.
The "Recommended action" section says to configure RunCommand and RunArguments, but it doesn't include the actual .csproj example. Add the minimal XML snippet users need (and consider mentioning that they might want to scope it with a condition so it only applies on Linux and/or only for .NET Framework targets).
| <RunCommand Condition="'$(RunCommand)' == ''">mono</RunCommand> | ||
| <RunArguments Condition="'$(RunArguments)' == ''">"$(TargetPath)" $(StartArguments)</RunArguments> |
There was a problem hiding this comment.
In the XML snippet, the trailing spaces and the " entities reduce readability in a Markdown code block. Remove the trailing whitespace and use normal double quotes around $(TargetPath) since escaping isn't needed inside a fenced code block.
| <RunCommand Condition="'$(RunCommand)' == ''">mono</RunCommand> | |
| <RunArguments Condition="'$(RunArguments)' == ''">"$(TargetPath)" $(StartArguments)</RunArguments> | |
| <RunCommand Condition="'$(RunCommand)' == ''">mono</RunCommand> | |
| <RunArguments Condition="'$(RunArguments)' == ''">"$(TargetPath)" $(StartArguments)</RunArguments> |
Overview
The .NET SDK previously auto-configured
RunCommandandRunArgumentsto launch .NET Framework apps with mono on Linux. This behavior was removed in .NET 11 Preview 1 following mono ownership transition.Changes
Created breaking change article:
docs/core/compatibility/sdk/11.0/mono-launch-target-removed.mdUpdated navigation:
docs/core/compatibility/toc.ymldocs/core/compatibility/11.mdindexMigration
Users requiring this behavior can manually configure their
.csproj:However, migration to modern .NET is the recommended path forward.
Original prompt
💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.
Internal previews