Update file-based apps reference article

[meaghanlewis]

Summary

Address comments from review feedback in: #50371

This pull request updates the documentation for file-based .NET apps, focusing on clarifying CLI usage, improving explanations of build and caching behavior, and providing more precise instructions for advanced scenarios. The changes aim to make the documentation more accurate and user-friendly by refining command syntax, clarifying default behaviors, and adding details on cache management and publishing.

CLI Command Usage and Syntax Improvements:

• Clarified how to run file-based apps with dotnet run, emphasizing the use of the --file option and providing updated examples for passing arguments, including the recommended use of -- to separate app arguments.
• Updated instructions for cleaning build artifacts, including new options like --days for cache cleanup and clarified the difference between deleting artifacts for a single file and a directory.
• Improved explanations and examples for publishing (noting default native AOT publishing and how to disable it), packaging as a tool, and converting to a project, including details on default locations and how to override default behaviors.

NuGet and SDK Reference Syntax:

• Updated NuGet package reference syntax from #:package Serilog version="3.1.1" to #:package [email protected] for consistency, and added an example for referencing a specific SDK version.

User Secrets and Advanced Features:

• Updated user secrets commands to use the --file option instead of --project, and added an example for listing secrets.
• Added a note about shebang requirements, specifying line endings and BOM constraints.

Build Output and Caching Behavior:

• Clarified that the SDK generates a "virtual project" (not just a temporary one), and specified the default build output path with instructions for customizing it.
• Expanded and clarified the section on build caching, emphasizing that the caching system is unique to file-based apps, and detailed what factors affect cache keys. Added explicit instructions for clearing cache artifacts.

---

Internal previews

📄 File	🔗 Preview link
docs/core/sdk/file-based-apps.md	File-based apps

[DamianEdwards]

Looking good! Left a few comments.

[Copilot]

Pull request overview

This PR updates the file-based .NET apps reference documentation based on review feedback. The changes improve CLI command documentation, clarify build and caching behavior, and refine advanced features like publishing and user secrets management.

Key changes:

• Enhanced CLI command examples with explicit --file option usage and argument passing conventions
• Updated NuGet package reference syntax from version="x.x.x" to @x.x.x format
• Clarified build caching behavior and provided explicit cache cleanup instructions

[DamianEdwards]

Looks great, thank you!