dotnet-project-file-analyzers · CptWesley · Jan 27, 2025 · Jan 26, 2025 · Jan 27, 2025 · Jan 27, 2025
diff --git a/README.md b/README.md
@@ -101,6 +101,12 @@ reported a the [GibHub repository](https://github.com/dotnet-project-file-analyz
 * [**Proj0244** Generate documentation file](rules/Proj0244.md)
 * [**Proj0245** Don't mix Version and VersionPrefix/VersionSuffix](rules/Proj0245.md)
 * [**Proj0246** Define VersionPrefix if VersionSuffix is defined](rules/Proj0246.md)
+* [**Proj0247** Enable strict mode for package baseline validation](rules/Proj0247.md)
+* [**Proj0248** Enable strict mode for package runtime compatibility validation](rules/Proj0248.md)
+* [**Proj0249** Enable strict mode for package framework compatibility validation](rules/Proj0249.md)
+* [**Proj0250** Generate API compatibility suppression file](rules/Proj0250.md)
+* [**Proj0251** Enable API compatibility attribute checks](rules/Proj0251.md)
+* [**Proj0252** Enable API compatibility parameter name checks](rules/Proj0252.md)
 * [**Proj0600** Avoid generating packages on build if not packable](rules/Proj0600.md)
 
 ### Publishing

diff --git a/rules/Proj0247.md b/rules/Proj0247.md
@@ -0,0 +1,53 @@
+---
+parent: Packaging
+ancestor: Rules
+---
+
+# Proj0247: Enable strict mode for package baseline validation
+When ensuring backwards compatibility of the API surface
+of your package, it is adviced to do this in strict mode.
+This helps preventing any unintentional API changes.
+
+More information can be found [here](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/overview), [here](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/baseline-version-validator) and [here](https://learn.microsoft.com/en-us/dotnet/core/project-sdk/msbuild-props#enablestrictmodeforbaselinevalidation).
+
+## Non-compliant
+``` xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <EnablePackageValidation>true</EnablePackageValidation>
+    <PackageValidationBaselineVersion>1.0.0</PackageValidationBaselineVersion>
+    <EnableStrictModeForBaselineValidation>false</EnableStrictModeForBaselineValidation>
+  </PropertyGroup>
+
+</Project>
+```
+
+Or:
+
+``` xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <EnablePackageValidation>true</EnablePackageValidation>
+    <PackageValidationBaselineVersion>1.0.0</PackageValidationBaselineVersion>
+  </PropertyGroup>
+
+</Project>
+```
+
+## Compliant
+``` xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <EnablePackageValidation>true</EnablePackageValidation>
+    <PackageValidationBaselineVersion>1.0.0</PackageValidationBaselineVersion>
+    <EnableStrictModeForBaselineValidation>true</EnableStrictModeForBaselineValidation>
+  </PropertyGroup>
+
+</Project>
+```
diff --git a/rules/Proj0248.md b/rules/Proj0248.md
@@ -0,0 +1,52 @@
+---
+parent: Packaging
+ancestor: Rules
+---
+
+# Proj0248: Enable strict mode for package runtime compatibility validation
+When building your package for multiple runtimes it
+is adviced to enable the strict mode of the runtime
+compatibility validation.
+
+Note that the default value is `true` and can therefore be omitted.
+
+More information can be found [here](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/overview), [here](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/compatible-framework-validator) and [here](https://learn.microsoft.com/en-us/dotnet/core/project-sdk/msbuild-props#enablestrictmodeforcompatibletfms).
+
+## Non-compliant
+``` xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <EnablePackageValidation>true</EnablePackageValidation>
+    <EnableStrictModeForCompatibleTfms>false</EnableStrictModeForCompatibleTfms>
+  </PropertyGroup>
+
+</Project>
+```
+
+## Compliant
+``` xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <EnablePackageValidation>true</EnablePackageValidation>
+  </PropertyGroup>
+
+</Project>
+```
+
+Or:
+
+``` xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <EnablePackageValidation>true</EnablePackageValidation>
+    <EnableStrictModeForCompatibleTfms>true</EnableStrictModeForCompatibleTfms>
+  </PropertyGroup>
+
+</Project>
+```
diff --git a/rules/Proj0249.md b/rules/Proj0249.md
@@ -0,0 +1,50 @@
+---
+parent: Packaging
+ancestor: Rules
+---
+
+# Proj0249: Enable strict mode for package framework compatibility validation
+When building your package for multiple target
+frameworks it is adviced to enable the strict
+mode of the framework compatibility validation.
+
+More information can be found [here](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/overview), [here](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/compatible-framework-in-package-validator) and [here](https://learn.microsoft.com/en-us/dotnet/core/project-sdk/msbuild-props#enablestrictmodeforcompatibleframeworksinpackage).
+
+## Non-compliant
+``` xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <EnablePackageValidation>true</EnablePackageValidation>
+    <EnableStrictModeForCompatibleFrameworksInPackage>false</EnableStrictModeForCompatibleFrameworksInPackage>
+  </PropertyGroup>
+
+</Project>
+```
+
+Or:
+
+``` xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <EnablePackageValidation>true</EnablePackageValidation>
+  </PropertyGroup>
+
+</Project>
+```
+
+## Compliant
+``` xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <EnablePackageValidation>true</EnablePackageValidation>
+    <EnableStrictModeForCompatibleFrameworksInPackage>true</EnableStrictModeForCompatibleFrameworksInPackage>
+  </PropertyGroup>
+
+</Project>
+```
diff --git a/rules/Proj0250.md b/rules/Proj0250.md
@@ -0,0 +1,62 @@
+---
+parent: Packaging
+ancestor: Rules
+---
+
+# Proj0250: Generate API compatibility suppression file
+When [package validation](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/overview) is enabled, it is required to
+provide a [suppression file](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/diagnostic-ids#how-to-suppress) for all differences that
+occur in the API:
+- [Changes between different package versions](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/baseline-version-validator)
+- [Differences between different runtimes (e.g. windows vs unix)](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/compatible-framework-validator)
+- [Differences between different target frameworks (e.g. netstandard2.0 vs net8.0)](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/compatible-framework-in-package-validator)
+
+This suppression file can be created manually, or automatically generated
+by enabling the `GenerateCompatibilitySuppressionFile` property. It is adviced
+to enable this property in the project file to ensure that file is kept
+up-to-date automatically.
+
+Additionally, it is adviced to keep changes to the generated file tracked in
+your version control system to ensure any API changes are explicitly included
+in code reviews.
+
+More information can be found [here](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/overview), [here](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/diagnostic-ids#how-to-suppress) and [here](https://learn.microsoft.com/en-us/dotnet/core/project-sdk/msbuild-props#apicompatgeneratesuppressionfile).
+
+## Non-compliant
+``` xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <EnablePackageValidation>true</EnablePackageValidation>
+    <ApiCompatGenerateSuppressionFile>false</ApiCompatGenerateSuppressionFile>
+  </PropertyGroup>
+
+</Project>
+```
+
+Or:
+
+``` xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <EnablePackageValidation>true</EnablePackageValidation>
+  </PropertyGroup>
+
+</Project>
+```
+
+## Compliant
+``` xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <EnablePackageValidation>true</EnablePackageValidation>
+    <ApiCompatGenerateSuppressionFile>true</ApiCompatGenerateSuppressionFile>
+  </PropertyGroup>
+
+</Project>
+```
diff --git a/rules/Proj0251.md b/rules/Proj0251.md
@@ -0,0 +1,49 @@
+---
+parent: Packaging
+ancestor: Rules
+---
+
+# Proj0251: Enable API compatibility attribute checks
+When [package validation](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/overview)
+is enabled, it is adviced to opt-in to the strict attribute compatibility checks.
+
+More information can be found [here](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/overview) and [here](https://learn.microsoft.com/en-us/dotnet/core/project-sdk/msbuild-props#apicompatenableruleattributesmustmatch).
+
+## Non-compliant
+``` xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <EnablePackageValidation>true</EnablePackageValidation>
+    <ApiCompatEnableRuleAttributesMustMatch>false</ApiCompatEnableRuleAttributesMustMatch>
+  </PropertyGroup>
+
+</Project>
+```
+
+Or:
+
+``` xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <EnablePackageValidation>true</EnablePackageValidation>
+  </PropertyGroup>
+
+</Project>
+```
+
+## Compliant
+``` xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <EnablePackageValidation>true</EnablePackageValidation>
+    <ApiCompatEnableRuleAttributesMustMatch>true</ApiCompatEnableRuleAttributesMustMatch>
+  </PropertyGroup>
+
+</Project>
+```
diff --git a/rules/Proj0252.md b/rules/Proj0252.md
@@ -0,0 +1,53 @@
+---
+parent: Packaging
+ancestor: Rules
+---
+
+# Proj0252: Enable API compatibility parameter name checks
+When [package validation](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/overview)
+is enabled, it is adviced to opt-in to the strict parameter name compatibility checks.
+While renaming parameters does not directly break runtime compatibility, it can break
+source compatibility when a consuming application uses
+[explicit parameter names](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/named-and-optional-arguments#named-arguments)
+when calling one of your methods.
+
+More information can be found [here](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/overview), [here](https://learn.microsoft.com/en-us/dotnet/core/project-sdk/msbuild-props#apicompatenablerulecannotchangeparametername) and [here](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/named-and-optional-arguments#named-arguments).
+
+## Non-compliant
+``` xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <EnablePackageValidation>true</EnablePackageValidation>
+    <ApiCompatEnableRuleCannotChangeParameterName>false</ApiCompatEnableRuleCannotChangeParameterName>
+  </PropertyGroup>
+
+</Project>
+```
+
+Or:
+
+``` xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <EnablePackageValidation>true</EnablePackageValidation>
+  </PropertyGroup>
+
+</Project>
+```
+
+## Compliant
+``` xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <EnablePackageValidation>true</EnablePackageValidation>
+    <ApiCompatEnableRuleCannotChangeParameterName>true</ApiCompatEnableRuleCannotChangeParameterName>
+  </PropertyGroup>
+
+</Project>
+```