This project welcomes contributions and suggestions. By contributing, you confirm that you have the right to, and actually do, grant us the rights to use your contribution. More information below.
Please feel free to contribute code, ideas, improvements, and patches - we've added some general guidelines and information below, and you can propose changes to this document in a pull request.
This project has adopted the Contributor Covenant Code of Conduct.
By contributing to this project, you:
- Agree that you have authored 100% of the content;
- Agree that you have the necessary rights to the content;
- Agree that you have received the necessary permissions from your employer to make the contributions (if applicable);
- Agree that the content you contribute may be provided under the Project license(s);
- Agree that, if you did not author 100% of the content, the appropriate licenses and copyrights have been added along with any other necessary attribution.
This project, and people participating in it, are governed by our code of conduct. By taking part, we expect you to try your best to uphold this code of conduct. If you have concerns about unacceptable behaviour, please contact the community leaders responsible for enforcement at ospo@avanade.com.
The most general guideline is that we use all the VS default settings in terms of code formatting; if in doubt, follow the coding convention of the existing code base.
- Use four spaces of indentation (no tabs).
- Use
_camelCasefor private fields. - Avoid
this.unless absolutely necessary. - Always specify member visibility, even if it's the default (i.e.
private string _foo;notstring _foo;). - Open-braces (
{) go on a new line (anifwith single-line statement does not need braces). - Use any language features available to you (expression-bodied members, throw expressions, tuples, etc.) as long as they make for readable, manageable code.
- All methods and properties must include the XML documentation comments. Private methods and properties only need to specifiy the summary as a minimum.
- Breaking changes should be avoided where possible; however, to minimize lifetime costs (technical debt) they are acceptable where change is expected to have a minimal impact (also avoid alternatives unless additive to minimize codebase bloat). For the most part be guided by Semantic Versioning 2.0.0.
For further guidance see ASP.NET Core Engineering guidelines.
Additionally, all source code files (/src/**/*.cs) require this exact header as follows:
// Copyright (c) Avanade. Licensed under the MIT License. See https://github.com/Avanade/CoreExSet the user environment variable CoreExLocalTargetFramework=net10.0 to opt into net10-only local builds, then launch Visual Studio from a process that has that environment value. The shared Directory.Build.props policy is imported by the framework, sample, and test props before SDK targets initialize; projects must inherit that framework list rather than redeclare it. Single-target projects, including the netstandard2.0 source generator, remain unchanged. The switch does not select a build configuration; Debug is recommended locally.
Use dotnet build CoreEx.sln -p:CoreExLocalTargetFramework= for the full framework matrix. CI (CI=true) and dotnet pack ignore narrowing; nuget-publish.ps1 and the template validator also clear it explicitly. Direct msbuild -t:Pack and Visual Studio Pack do not set the CLI's _IsPacking global property, so clear CoreExLocalTargetFramework explicitly for those entry points.
For reduced local packages, run .\nuget-publish.ps1 -Tfm 10 -configuration Debug -PublishFolder "$env:USERPROFILE\nuget-publish-net10" (-Tfm net10.0 and -Tfm 10.0 are equivalent). The explicit flag overrides the shared framework list for both build and pack; omitting it preserves all-framework Release packaging by default. Independently targeted projects retain their own frameworks, including the netstandard2.0 source generator and net10.0 template pack. Reduced packages retain the same package ID/version and replace matching filenames in the selected feed; keep them in a separate local feed and do not publish them as release packages. Matching versions are still removed from the local NuGet cache unless -DeleteFromlocalCache:$false is supplied.
After framework-policy changes, reload the solution and verify Visual Studio's framework selection before retrying Contoso.Aspire → Start Without Debugging. A successful CLI build or static-graph evaluation verifies MSBuild consistency, not the running IDE's configured-project state; no .vs deletion should be necessary.
We use NUnit for all unit testing.
- Tests need to be provided for every bug/feature that is completed.
- Tests only need to be present for issues that need to be verified by QA (for example, not tasks).
- If there is a scenario that is far too hard to test there does not need to be a test for it.
- "Too hard" is determined by the team as a whole.
We understand there is more work to be performed in generating a higher level of code coverage; this technical debt is on the backlog.
The CI workflow runs core validation, sample tests for each of .NET 8/9/10/11, sample Aspire E2E tests, Functions runtime proofs, and template validation as independent jobs on GitHub-hosted runners. Each infrastructure-dependent job owns its own Docker containers, networks, volumes, and test data; sample integration projects remain sequential within each framework job because they reset shared infrastructure. Sample E2E starts and seeds its own infrastructure rather than depending on prior sample tests.
Core and sample jobs upload uniquely named test results and raw coverage artifacts. A separate job merges coverage, and the final build status requires every validation job and coverage aggregation to succeed; failed, cancelled, or unexpectedly skipped jobs cannot produce a successful gate. Re-run the failing job when investigating an isolated failure rather than repeating every suite. Asynchronous E2E effects must use bounded polling with diagnostic timeout failures, not fixed sleeps or assumptions that replication has finished.
To help ensure that only the highest quality code makes its way into the project, please submit all your code changes to GitHub as PRs. This includes runtime code changes, unit test updates, and updates to the end-to-end demo.
For example, sending a PR for just an update to a unit test might seem like a waste of time but the unit tests are just as important as the product code and as such, reviewing changes to them is also just as important. This also helps create visibility for your changes so that others can observe what is going on.
The advantages are numerous: improving code quality, more visibility on changes and their potential impact, avoiding duplication of effort, and creating general awareness of progress being made in various areas.