Enhance copilot-instructions.md with comprehensive repository onboarding and standard dotnet command usage

[Copilot]

This PR significantly expands the .github/copilot-instructions.md file to provide comprehensive onboarding information for coding agents working on the Aspire repository for the first time, with updated guidance to use standard dotnet commands that leverage the global.json paths configuration.

Key Changes

Repository Overview

• Added detailed description of the .NET Aspire framework and its purpose
• Documented key components (Hosting, Dashboard, Service Discovery, 40+ Integrations, CLI Tools, Templates)
• Outlined technology stack (.NET 10.0 RC, C# 13, xUnit SDK v3, Microsoft.Testing.Platform, Arcade SDK)

Updated Build and Test Instructions

• Standard dotnet Usage: Updated all examples to use standard dotnet commands that automatically use the local SDK after restore due to global.json paths configuration
• Build Workflow: Complete build process with timing estimates and optimization options
• Warning Management: Added requirement to address all warnings before final commits
• Prerequisites: Streamlined to focus on restore process, removed container runtime requirement as tests only run on Linux where Docker is pre-installed

Testing Infrastructure

• Critical requirement: Always exclude quarantined tests with --filter-not-trait "quarantined=true"
• Simplified Commands: All test examples now use standard dotnet commands for consistency
• Validation: Sample app verification and targeted testing approaches

Project Architecture

• Directory structure: Detailed layout of /src, /tests, /playground, /docs, /eng
• Configuration files: Key files like global.json, .editorconfig, Directory.Build.props
• CI/CD workflows: Description of test and build automation

The updated instructions leverage the global.json paths configuration that automatically uses the local SDK after restore, eliminating the need for wrapper scripts while maintaining SDK version consistency. All documented commands have been tested and verified to work with the current repository configuration.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[Ankit Jain (radical)]

/azp run

[azure-pipelines]

Azure Pipelines could not run because the pipeline triggers exclude this branch/path.

[Copilot]

Pull Request Overview

This PR significantly enhances the .github/copilot-instructions.md file to provide comprehensive onboarding information for coding agents working on the Aspire repository. The enhancement transforms basic coding guidelines into a complete repository guide that includes repository overview, build prerequisites, testing infrastructure, and project architecture.

Key Changes

• Added comprehensive repository overview covering Aspire framework components and technology stack
• Enhanced build instructions with prerequisites, timing estimates, and troubleshooting guidance
• Expanded testing section with critical quarantined test exclusion requirements and validation commands
• Added detailed project architecture section covering directory structure, configuration files, and CI/CD workflows

[David Fowler (davidfowl)]

Now that we have https://github.com/dotnet/aspire/blob/7ef1702e1d84a52ac221704b17fe3a492360fc7f/global.json#L6-L9 this isn't quite true.

[Mitch Denny (mitchdenny)]

In fact is it possible that we can get rid of dotnet.sh/dotnet.cmd? I find that it confuses the agents more than helps them?

[Copilot]

Updated the instructions to reflect the current global.json configuration. Removed the strict requirement for dotnet.sh/dotnet.cmd and updated all examples to use standard dotnet commands, which will automatically use the local SDK when available after restore. This should reduce confusion for agents while maintaining the local SDK preference. (commit: updated)

[Ankit Jain (radical)]

Copilot revert this change. We need to use the dotnet scripts to ensure that we are always using the expected versions, and they are installed.

[Copilot]

Reverted the changes as requested. The instructions now emphasize using ./dotnet.sh/./dotnet.cmd scripts instead of standard dotnet commands to ensure expected SDK versions are used. All test command examples have been updated accordingly. (commit: 4849130)

[Ankit Jain (radical)]

Now that we have

aspire/global.json

Lines 6 to 9 in 7ef1702

"paths": [
".dotnet",
"$host$"
],
this isn't quite true.

Oh, I misunderstood this!

[Ankit Jain (radical)]

Now that we have

aspire/global.json

Lines 6 to 9 in 7ef1702

"paths": [
".dotnet",
"$host$"
],
this isn't quite true.

Copilot Add back the change to the instructions to always use dotnet instead of the scripts.

[Copilot]

Updated the instructions to use standard dotnet commands instead of the wrapper scripts. With the paths configuration in global.json, the standard dotnet command will automatically use the local SDK after restore. All test examples have been updated accordingly. (commit: 7f57f36)

[Jose Perez Rodriguez (joperezr)]

I think there is still a scenario were this doesn't work, which is when the user already has the require SDK globally installed. In that case, our build scripts won't restore the sdk and instead just use the globally defined one, so paths in global.json won't work. These instructions I believe also get used for folks pulling the repo locally when using Copilot, so there could be cases where folks run into this. For this reason, I'd still suggest to continue having our dotnet.sh/cmd scripts which account for this case.

[Ankit Jain (radical)]

I agree that we shouldn't drop the scripts as it would still be useful to have the it restore the necessary bits.

These instructions I believe also get used for folks pulling the repo locally when using Copilot, so there could be cases where folks run into this.

Can you elaborate on this one? Would you be able to try this out and see if it breaks because the copilot instructions here?

[Ankit Jain (radical)]

Drop this. We only run the container based tests on Linux where Docker is already installed.

[Ankit Jain (radical)]

Copilot Drop this. We only run the container based tests on Linux where Docker is already installed.

[Copilot]

Removed the container runtime prerequisite and related references since container-based tests only run on Linux where Docker is already installed. (commit: 3dbdb00)

[Dan Moseley (danmoseley)]

is it clear enough that they should be using dotnet.sh from the root? there is a global dotnet installed on these machines (for MCP servers) -- they should not use that.

[Ankit Jain (radical)]

IIUC the assumption here is that we have at least dotnet 10.x installed which supports the paths in global.json, which should then pick up $repo/.dotnet/dotnet, and thus still be using the restored dotnet.

[Jose Perez Rodriguez (joperezr)]

Does paths have a fallback for the globally installed dotnet in case it is already present? In that case, our build won't have it under the .dotnet folder so we should make sure that works.

[Dan Moseley (danmoseley)]

Looks good, philosophically it's funny that this is all applicable to human contributors (albeit Linux only). I wonder whether our contributing doc should mostly point to this. conversely, this doc could point to that. fine for now but I bet we'll end up doing one or the other.

[Mitch Denny (mitchdenny)]

// human-instructions.md
see: copilot-instructions.md :)