Plan: Add guidance for launching .NET apps

Based on the problem statement, I need to:

• Review and understand the content from dotnet/designs PR 346
• Create the new documentation file at docs/core/deploying/net-app-launch.md
• Adapt the content to match the documentation style guidelines
• Update links to point to appropriate Microsoft Learn documentation instead of design documents
• Add proper frontmatter (metadata) following the pattern of other deployment docs
• Ensure markdown formatting follows repository standards
• Add AI usage disclosure in frontmatter
• Run markdownlint to validate the document
• Review placement in docs/core/deploying/ directory
• Add cross-references to existing deployment documentation
• Fold content into index.md per reviewer feedback
• Address review comments on wording
• Address additional review feedback on structure and clarity
• Update framework-dependent description per reviewer feedback
• Introduce "apphost" terminology earlier in document
• Replace ambiguous "host" term with clearer terminology
• Simplify security mitigations example
• Reorganize content for better flow
• Replace ALL CAPS placeholders with consistent convention

Changes made:

Updated file: docs/core/deploying/index.md

Latest change:

• Replaced ALL CAPS placeholders (<PROJECT-FILE> and <PROJECT-NAME>) with lowercase myapp convention throughout the document. This aligns with the naming convention used in other .NET documentation (e.g., docs/core/tools/dotnet-run.md uses "myapp.dll"). Changes made:
  • Line 130: <PROJECT-FILE>.exe → myapp.exe and <PROJECT-FILE> → myapp
  • Line 149: dotnet <PROJECT-FILE>.dll → dotnet myapp.dll (2 instances)
  • Line 219: <PROJECT-NAME>.dll → myapp.dll (2 instances)

Previous change:

• Moved runtime discovery and DOTNET_ROOT best practices content from "Launch framework-dependent apps" section to the start of "Configure .NET install search behavior" section (lines 194-202). This provides better context about default behavior and DOTNET_ROOT usage before discussing the .NET 9+ configuration properties.

Previous change:

• Removed Control Flow Guard mention from line 154, keeping only CET as the security mitigation example: "For example, Control-flow Enforcement Technology (CET) shadow stack is enabled by default starting with .NET 9."

Previous change:

• Replaced ambiguous "host" terminology with clearer terms:
  • Line 130: Changed "platform-specific executable host is created to host" to "platform-specific executable is created to host" and "The host executable filename" to "The platform-specific executable filename"
  • Line 149: Changed "through the host executable ("apphost")" to "through the platform-specific executable (apphost)" for consistency

Previous change:

• Added "apphost" term introduction in the "Portable binaries" section (line 71): "By default, even when creating a portable binary, .NET publishes a platform-specific executable ("apphost") alongside the portable DLL unless you explicitly disable this behavior." This introduces the term before it's used later in the document.

Previous change:

• Updated "Publish framework-dependent" description (lines 39-40) to emphasize that the platform-specific executable is optional: "This mode produces a publishing folder that includes an optional platform-specific executable used to start the app, a compiled binary containing app code, and any app dependencies."

Previous changes (addressing review feedback):

• Moved Advantages/Disadvantages section before "Launch framework-dependent apps" subsection to maintain better document flow
• Added back context: "You can run the apphost executable directly instead of calling dotnet myapp.dll, which is still an acceptable way to run the app."
• Improved clarity: Changed "The apphost generally uses a global install" to "By default, the apphost discovers and uses a globally installed .NET runtime" to be more explicit about default behavior

Previous changes:

• Changed "through the apphost launcher" to "through the host executable ("apphost")" for clearer terminology
• Simplified "In general, the best practice for using DOTNET_ROOT to set the runtime location for an app is to:" to "In general, the best practice for using DOTNET_ROOT is to:" for conciseness

Previous integration:

• Added new subsection "Launch framework-dependent apps" that covers:
  • Two ways to run framework-dependent apps (apphost vs dotnet myapp.dll)
  • Advantages of using the apphost:
    • Executables appear like standard native platform executables
    • Process names preserved for easy identification
    • Native assets can be attached
    • Security mitigations (CET shadow stack) applied by default
  • Runtime discovery and install locations
  • DOTNET_ROOT configuration best practices
• Removed separate link from "See also" section

Deleted file: docs/core/deploying/net-app-launch.md

• Content has been integrated directly into index.md as requested by reviewer

Validation completed:

• Markdownlint passed with 0 errors
• All cross-references verified
• Content properly integrated into existing structure
• Section ordering improved for better document flow
• Maintains repository writing style guidelines
• All reviewer feedback addressed
• "apphost" terminology introduced early for better clarity
• Ambiguous "host" term replaced with precise terminology
• Security mitigations example simplified to focus on CET
• Runtime discovery content reorganized for better flow
• Placeholders replaced with consistent lowercase convention

This pull request was created as a result of the following prompt from Copilot chat.

Add guidance for launching .NET apps migrated from design proposal dotnet/designs#346 into docs.

This PR introduces a new documentation page at docs/core/deploying/net-app-launch.md that explains recommended practices for launching .NET applications, distinguishing self-contained vs framework-dependent deployment, and recommending use of the apphost over invoking dotnet app.dll directly. It also documents advantages of apphost, links to runtime security mitigations, install location specifications, and provides best-practice steps for using DOTNET_ROOT.

Changes included:

• New file: docs/core/deploying/net-app-launch.md (content derived from proposed/net-app-launch.md in dotnet/designs PR 346).

No existing pages were modified besides adding the new file (consider future TOC integration if needed).

Please review for:

• Accuracy of links (currently pointing to design documents in dotnet/designs repo)
• Placement within docs/core/deploying/ (confirm this is the correct directory for runtime/deployment guidance)
• Whether additional cross-links (e.g., to existing self-contained vs framework-dependent deployment docs) should be added before merge.

If acceptable, merge to surface guidance users have requested regarding apphost usage and DOTNET_ROOT best practices.

💡 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