Skip to content

docs: Document .NET 8 self-contained deployment default change and add troubleshooting#53498

Draft
Copilot wants to merge 2 commits intomainfrom
copilot/fix-doc-gap-net8-self-contained-change
Draft

docs: Document .NET 8 self-contained deployment default change and add troubleshooting#53498
Copilot wants to merge 2 commits intomainfrom
copilot/fix-doc-gap-net8-self-contained-change

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented Apr 29, 2026

In .NET 8, specifying -r <RID> no longer implies --self-contained — apps now publish framework-dependent by default even with a RID. This silent behavioral change from .NET 7 has caused widespread confusion (16k-view SO question).

Changes to docs/core/deploying/index.md

  • Breaking change callout — Added [!IMPORTANT] alert at the top of the Self-contained deployment section, explicitly stating that -r <RID> alone no longer produces a self-contained app in .NET 8+:

    # .NET 7 behavior (implicit self-contained)
    dotnet publish -r win-x64
    
    # .NET 8+ required form
    dotnet publish -r win-x64 --self-contained
  • Troubleshooting section — Added ## Troubleshoot self-contained deployment before ## See also with:

    • App prompts for .NET runtime installation — root cause explanation + fix for both CLI and Visual Studio
    • Verify that publish output is self-contained — tells readers to check for coreclr.dll / libcoreclr.so / libcoreclr.dylib in the publish folder; includes project-file fix via <SelfContained>true</SelfContained>
  • See also — Added link to the Runtime-specific apps no longer self-contained breaking change article

Copilot AI changed the title [WIP] Add documentation for .NET 8 self-contained deployment change docs: Document .NET 8 self-contained deployment default change and add troubleshooting Apr 29, 2026
Copilot AI requested a review from gewarren April 29, 2026 21:48

For more information about container deployment, see [.NET SDK container creation overview](../containers/overview.md).

## Troubleshoot self-contained deployment
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should probably go under the self-contained section, if it's needed.

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Doc gap: .NET 8 self-contained deployment default change not prominently documented

2 participants