akritikos
eea4ce7a0e
Refines conventions for ASP.NET API endpoints, C# documentation, Docker build arguments, MSBuild package management, and testing method naming and structure. These changes aim to enhance clarity and enforce best practices across the codebase.
1.9 KiB
description, applyTo
| description | applyTo |
|---|---|
| Use when editing MSBuild files (.csproj, .props, .targets). Covers central package management, artifacts layout, and property inheritance. | **/*.{csproj,props,targets} |
MSBuild Conventions
Central Package Management
All package versions are declared in Directory.Packages.props at the repo root. In Directory.Packages.props, ensure the last child element of the root <Project> tag is <Import Project="Directory.Packages.template.props" />. Directory.Packages.template.props is READ ONLY, never edit it. The template provides default <PackageVersion> entries; any entry with the same Include declared earlier in Directory.Packages.props takes precedence over the template default, because MSBuild uses first-definition-wins semantics and the import appears last.
In .csproj files:
<!-- Correct -->
<PackageReference Include="Newtonsoft.Json" />
<!-- Wrong — never specify Version -->
<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
To add or update a version, edit Directory.Packages.props:
<PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
If the package does not exist in the template, simply add a new <PackageVersion> entry in Directory.Packages.props. No override logic is needed; the entry will be the sole definition.
Properties Set Centrally (Do Not Override)
These are configured in the root Directory.Build.props — do not set them in individual projects:
LangVersion, Nullable, ImplicitUsings.
InternalsVisibleTo
Handled automatically via <InternalsVisibleToSuffix> in the root props. Default suffixes are .Tests and Tests. To add custom visibility:
<ItemGroup>
<InternalsVisibleTo Include="MyProject.IntegrationTests" />
</ItemGroup>
This is in addition to the automatically generated entries; do not remove or duplicate the default suffix entries.