Skip to content

Commit ef071a7

Browse files
gewarrengewarren
authored
Add assembly validation and MSBuild props (#38533)
1 parent cc25009 commit ef071a7

File tree

12 files changed

+434
-144
lines changed

12 files changed

+434
-144
lines changed

‎.openpublishing.redirection.fundamentals.json‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
{
22
"redirections": [
3+
{
4+
"source_path_from_root": "/docs/fundamentals/apicompat/package-validation/diagnostic-ids.md",
5+
"redirect_url": "/dotnet/fundamentals/apicompat/diagnostic-ids"
6+
},
37
{
48
"source_path_from_root": "/docs/fundamentals/code-analysis/quality-rules/ca1071.md",
59
"redirect_url": "/dotnet/fundamentals/code-analysis/quality-rules/index"
@@ -181,7 +185,7 @@
181185
},
182186
{
183187
"source_path_from_root": "/docs/fundamentals/package-validation/diagnostic-ids.md",
184-
"redirect_url": "/dotnet/fundamentals/apicompat/package-validation/diagnostic-ids",
188+
"redirect_url": "/dotnet/fundamentals/apicompat/diagnostic-ids",
185189
"redirect_document_id": true
186190
},
187191
{

‎docs/core/project-sdk/msbuild-props.md‎

Lines changed: 228 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: MSBuild properties for Microsoft.NET.Sdk
33
description: Reference for the MSBuild properties and items that are understood by the .NET SDK.
4-
ms.date: 11/09/2023
4+
ms.date: 12/01/2023
55
ms.topic: reference
66
ms.custom: updateeachrelease
77
---
@@ -12,6 +12,52 @@ This page is a reference for the MSBuild properties and items that you can use t
1212
> [!NOTE]
1313
> This page is a work in progress and does not list all of the useful MSBuild properties for the .NET SDK. For a list of common MSBuild properties, see [Common MSBuild properties](/visualstudio/msbuild/common-msbuild-project-properties).
1414
15+
## Assembly validation properties
16+
17+
These properties and items are passed to the `ValidateAssemblies` task. For more information about assembly validation, see [Assembly validation](../../fundamentals/apicompat/assembly-validation.md).
18+
19+
The following MSBuild properties are documented in this section:
20+
21+
- [ApiCompatStrictMode](#apicompatstrictmode)
22+
- [ApiCompatValidateAssemblies](#apicompatvalidateassemblies)
23+
24+
> [!NOTE]
25+
> These properties aren't part of the .NET SDK (yet). To use them, you must also add a `PackageReference` to [Microsoft.DotNet.ApiCompat.Task](https://www.nuget.org/packages/Microsoft.DotNet.ApiCompat.Task).
26+
27+
In addition, the following properties that are documented in the [Package validation properties](#package-validation-properties) also apply to assembly validation:
28+
29+
- [ApiCompatEnableRuleAttributesMustMatch](#apicompatenableruleattributesmustmatch)
30+
- [ApiCompatEnableRuleCannotChangeParameterName](#apicompatenablerulecannotchangeparametername)
31+
- [ApiCompatExcludeAttributesFile](#apicompatexcludeattributesfile)
32+
- [ApiCompatGenerateSuppressionFile](#apicompatgeneratesuppressionfile)
33+
- [ApiCompatPermitUnnecessarySuppressions](#apicompatpermitunnecessarysuppressions)
34+
- [ApiCompatPreserveUnnecessarySuppressions](#apicompatpreserveunnecessarysuppressions)
35+
- [ApiCompatRespectInternals](#apicompatrespectinternals)
36+
- [ApiCompatSuppressionFile](#apicompatsuppressionfile)
37+
- [ApiCompatSuppressionOutputFile](#apicompatsuppressionoutputfile)
38+
- [NoWarn](#nowarn)
39+
- [RoslynAssembliesPath](#roslynassembliespath)
40+
41+
### ApiCompatStrictMode
42+
43+
When set to `true`, the `ApiCompatStrictMode` property specifies that API compatibility checks should be performed in [strict mode](../../fundamentals/apicompat/overview.md#strict-mode).
44+
45+
```xml
46+
<PropertyGroup>
47+
<ApiCompatStrictMode>true</ApiCompatStrictMode>
48+
</PropertyGroup>
49+
```
50+
51+
### ApiCompatValidateAssemblies
52+
53+
The `ApiCompatValidateAssemblies` property enables a series of validations on the specified assemblies. For more information, see [Assembly validation](../../fundamentals/apicompat/assembly-validation.md).
54+
55+
```xml
56+
<PropertyGroup>
57+
<ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
58+
</PropertyGroup>
59+
```
60+
1561
## Framework properties
1662

1763
The following MSBuild properties are documented in this section:
@@ -159,14 +205,194 @@ The `PackRelease` property is similar to the [PublishRelease](#publishrelease) p
159205
> - Starting in the .NET 8 SDK, `PackRelease` defaults to `true`. For more information, see ['dotnet pack' uses Release configuration](../compatibility/sdk/8.0/dotnet-pack-config.md).
160206
> - .NET 7 SDK only: To use `PackRelease` in a project that's part of a Visual Studio solution, you must set the environment variable `DOTNET_CLI_ENABLE_PACK_RELEASE_FOR_SOLUTIONS` to `true` (or any other value). For solutions that have many projects, setting this variable increases the time required to pack.
161207
208+
## Package validation properties
209+
210+
These properties and items are passed to the `ValidatePackage` task. For more information about package validation, see [Package validation overview](../../fundamentals/apicompat/package-validation/overview.md).
211+
212+
For properties for the `ValidateAssemblies` task, see [Assembly validation properties](#assembly-validation-properties).
213+
214+
The following MSBuild properties and items are documented in this section:
215+
216+
- [ApiCompatEnableRuleAttributesMustMatch](#apicompatenableruleattributesmustmatch)
217+
- [ApiCompatEnableRuleCannotChangeParameterName](#apicompatenablerulecannotchangeparametername)
218+
- [ApiCompatExcludeAttributesFile](#apicompatexcludeattributesfile)
219+
- [ApiCompatGenerateSuppressionFile](#apicompatgeneratesuppressionfile)
220+
- [ApiCompatPermitUnnecessarySuppressions](#apicompatpermitunnecessarysuppressions)
221+
- [ApiCompatPreserveUnnecessarySuppressions](#apicompatpreserveunnecessarysuppressions)
222+
- [ApiCompatRespectInternals](#apicompatrespectinternals)
223+
- [ApiCompatSuppressionFile](#apicompatsuppressionfile)
224+
- [ApiCompatSuppressionOutputFile](#apicompatsuppressionoutputfile)
225+
- [EnablePackageValidation](#enablepackagevalidation)
226+
- [EnableStrictModeForBaselineValidation](#enablestrictmodeforbaselinevalidation)
227+
- [EnableStrictModeForCompatibleFrameworksInPackage](#enablestrictmodeforcompatibleframeworksinpackage)
228+
- [EnableStrictModeForCompatibleTfms](#enablestrictmodeforcompatibletfms)
229+
- [NoWarn](#nowarn)
230+
- [PackageValidationBaselineFrameworkToIgnore](#packagevalidationbaselineframeworktoignore)
231+
- [PackageValidationBaselineName](#packagevalidationbaselinename)
232+
- [PackageValidationBaselineVersion](#packagevalidationbaselineversion)
233+
- [PackageValidationReferencePath](#packagevalidationreferencepath)
234+
- [RoslynAssembliesPath](#roslynassembliespath)
235+
236+
### ApiCompatEnableRuleAttributesMustMatch
237+
238+
When set to `true`, the `ApiCompatEnableRuleAttributesMustMatch` property enables the validation rule that checks if attributes match. The default is `false`.
239+
240+
```xml
241+
<PropertyGroup>
242+
<ApiCompatEnableRuleAttributesMustMatch>true</ApiCompatEnableRuleAttributesMustMatch>
243+
</PropertyGroup>
244+
```
245+
246+
### ApiCompatEnableRuleCannotChangeParameterName
247+
248+
When set to `true`, the `ApiCompatEnableRuleCannotChangeParameterName` property enables the validation rule that checks whether parameter names have changed in public methods. The default is `false`.
249+
250+
```xml
251+
<PropertyGroup>
252+
<ApiCompatEnableRuleCannotChangeParameterName>true</ApiCompatEnableRuleCannotChangeParameterName>
253+
</PropertyGroup>
254+
```
255+
256+
### ApiCompatExcludeAttributesFile
257+
258+
The `ApiCompatExcludeAttributesFile` item specifies the path to a file that contains attributes to exclude in [DocId](../../csharp/language-reference/xmldoc/index.md#id-strings) format.
259+
260+
```xml
261+
<ItemGroup>
262+
<ApiCompatExcludeAttributesFile Include="ApiCompatExcludedAttributes.txt" />
263+
<ApiCompatExcludeAttributesFile Include="ApiCompatBaselineExcludedAttributes.txt" />
264+
</ItemGroup>
265+
```
266+
267+
### ApiCompatGenerateSuppressionFile
268+
269+
The `ApiCompatGenerateSuppressionFile` property specifies whether to generate a compatibility suppression file.
270+
271+
```xml
272+
<PropertyGroup>
273+
<ApiCompatGenerateSuppressionFile>true</ApiCompatGenerateSuppressionFile>
274+
</PropertyGroup>
275+
```
276+
277+
### ApiCompatPermitUnnecessarySuppressions
278+
279+
The `ApiCompatPermitUnnecessarySuppressions` property specifies whether to permit unnecessary suppressions in the suppression file.
280+
281+
The default is `false`.
282+
283+
```xml
284+
<PropertyGroup>
285+
<ApiCompatPermitUnnecessarySuppressions>true</ApiCompatPermitUnnecessarySuppressions>
286+
</PropertyGroup>
287+
```
288+
289+
### ApiCompatPreserveUnnecessarySuppressions
290+
291+
The `ApiCompatPreserveUnnecessarySuppressions` property specifies whether to preserve unnecessary suppressions when regenerating the suppression file. When an existing suppression file is regenerated, its content is read, deserialized into a set of suppressions, and then stored in a list. Some of the suppressions might no longer be necessary if the incompatibility has been fixed. When the suppressions are serialized back to disk, you can choose to keep *all* the existing (deserialized) expressions by setting this property to `true`.
292+
293+
The default is `false`.
294+
295+
```xml
296+
<PropertyGroup>
297+
<ApiCompatPreserveUnnecessarySuppressions>true</ApiCompatPreserveUnnecessarySuppressions>
298+
</PropertyGroup>
299+
```
300+
301+
### ApiCompatRespectInternals
302+
303+
The `ApiCompatRespectInternals` property specifies whether `internal` APIs should be checked for compatibility in addition to `public` APIs.
304+
305+
```xml
306+
<PropertyGroup>
307+
<ApiCompatRespectInternals>true</ApiCompatRespectInternals>
308+
</PropertyGroup>
309+
```
310+
311+
### ApiCompatSuppressionFile
312+
313+
The `ApiCompatSuppressionFile` item specifies the path to one or more suppression files to read from. If unspecified, the suppression file *\<project-directory>/CompatibilitySuppressions.xml* is read (if it exists).
314+
315+
```xml
316+
<ItemGroup>
317+
<ApiCompatSuppressionFile Include="CompatibilitySuppressions.xml;CompatibilitySuppressions.WasmThreads.xml" />
318+
</ItemGroup>
319+
```
320+
321+
### ApiCompatSuppressionOutputFile
322+
323+
The `ApiCompatSuppressionOutputFile` property specifies the path to a suppression file to write to when `<ApiCompatGenerateSuppressionFile>` is `true`. If unspecified, the first `ApiCompatSuppressionFile` item is used.
324+
325+
### EnablePackageValidation
326+
327+
The `EnablePackageValidation` property enables a series of validations on the package after the `Pack` task. For more information, see [package validation](../../fundamentals/apicompat/package-validation/overview.md).
328+
329+
```xml
330+
<PropertyGroup>
331+
<EnablePackageValidation>true</EnablePackageValidation>
332+
</PropertyGroup>
333+
```
334+
335+
### EnableStrictModeForBaselineValidation
336+
337+
When set to `true`, the `EnableStrictModeForBaselineValidation` property enables [strict mode](../../fundamentals/apicompat/overview.md#strict-mode) for package baseline checks. The default is `false`.
338+
339+
### EnableStrictModeForCompatibleFrameworksInPackage
340+
341+
When set to `true`, the `EnableStrictModeForCompatibleFrameworksInPackage` property enables [strict mode](../../fundamentals/apicompat/overview.md#strict-mode) for assemblies that are compatible based on their target framework. The default is `false`.
342+
343+
### EnableStrictModeForCompatibleTfms
344+
345+
When set to `true`, the `EnableStrictModeForCompatibleTfms` property enables [strict mode](../../fundamentals/apicompat/overview.md#strict-mode) for contract and implementation assemblies for all compatible target frameworks. The default is `true`.
346+
347+
### NoWarn
348+
349+
The `NoWarn` property specifies the diagnostic IDs to suppress.
350+
351+
```xml
352+
<PropertyGroup>
353+
<NoWarn>$(NoWarn);PKV0001</NoWarn>
354+
</PropertyGroup>
355+
```
356+
357+
### PackageValidationBaselineFrameworkToIgnore
358+
359+
The `PackageValidationBaselineFrameworkToIgnore` item specifies a target framework to ignore from the baseline package. The framework string must exactly match the folder name in the baseline package.
360+
361+
```xml
362+
<ItemGroup>
363+
<PackageValidationBaselineFrameworkToIgnore Include="netcoreapp2.1" />
364+
</ItemGroup>
365+
```
366+
367+
### PackageValidationBaselineName
368+
369+
The `PackageValidationBaselineName` property specifies the name of the baseline package to validate the current package against. If unspecified, the `PackageId` value is used.
370+
371+
### PackageValidationBaselineVersion
372+
373+
The `PackageValidationBaselineVersion` property specifies the version of the baseline package to validate the current package against.
374+
375+
### PackageValidationReferencePath
376+
377+
The `PackageValidationReferencePath` item specifies the directory path where the reference assembly can be found per TFM.
378+
379+
```xml
380+
<ItemGroup>
381+
<PackageValidationReferencePath Include="path/to/reference-assembly" TargetFramework="net7.0" />
382+
</ItemGroup>
383+
```
384+
385+
### RoslynAssembliesPath
386+
387+
The `RoslynAssembliesPath` property specifies the path to the directory that contains the Microsoft.CodeAnalysis assemblies you want to use. You only need to set this property if you want to test with a newer compiler than what's in the SDK.
388+
162389
## Publish-related properties
163390

164391
The following MSBuild properties are documented in this section:
165392

166393
- [AppendRuntimeIdentifierToOutputPath](#appendruntimeidentifiertooutputpath)
167394
- [AppendTargetFrameworkToOutputPath](#appendtargetframeworktooutputpath)
168395
- [CopyLocalLockFileAssemblies](#copylocallockfileassemblies)
169-
- [EnablePackageValidation](#enablepackagevalidation)
170396
- [ErrorOnDuplicatePublishOutputFiles](#erroronduplicatepublishoutputfiles)
171397
- [GenerateRuntimeConfigDevFile](#generateruntimeconfigdevfile)
172398
- [GenerateRuntimeConfigurationFiles](#generateruntimeconfigurationfiles)
@@ -237,18 +463,6 @@ The `ErrorOnDuplicatePublishOutputFiles` property relates to whether the SDK gen
237463

238464
This property was introduced in .NET 6.
239465

240-
### EnablePackageValidation
241-
242-
The `EnablePackageValidation` property enables a series of validations on the package after the `pack` task. For more information, see [package validation](../../fundamentals/apicompat/package-validation/overview.md).
243-
244-
```xml
245-
<PropertyGroup>
246-
<EnablePackageValidation>true</EnablePackageValidation>
247-
</PropertyGroup>
248-
```
249-
250-
This property was introduced in .NET 6.
251-
252466
### GenerateRuntimeConfigDevFile
253467

254468
Starting with the .NET 6 SDK, the *\[Appname].runtimesettings.dev.json* file is [no longer generated by default](../compatibility/sdk/6.0/runtimeconfigdev-file.md) at compile time. If you still want this file to be generated, set the `GenerateRuntimeConfigDevFile` property to `true`.

‎docs/fundamentals/apicompat/assembly-validation.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: Assembly validation
3+
description: Learn how assembly validation can be used to develop consistent and well-formed multi-targeting assemblies.
4+
ms.date: 12/01/2023
5+
ms.topic: overview
6+
---
7+
8+
# Assembly validation
9+
10+
Similar to [package validation](/dotnet/fundamentals/apicompat/package-validation/overview), assembly validation tooling allows you, as a library developer, to validate that your assemblies are consistent and well formed. It provides the following checks:
11+
12+
- Validates that there are no breaking changes across versions.
13+
- Validates that the assembly has the same set of public APIs for all the different runtime-specific implementations.
14+
- Catches any applicability holes.
15+
16+
You can run assembly validation either as an [MSBuild task](#enable-msbuild-task) or using the [Microsoft.DotNet.ApiCompat.Tool global tool](global-tool.md).
17+
18+
## Enable MSBuild task
19+
20+
You enable assembly validation in your .NET project by setting the [`ApiCompatValidateAssemblies`](../../core/project-sdk/msbuild-props.md#apicompatvalidateassemblies) property to `true`. You must also add a package reference to [Microsoft.DotNet.ApiCompat.Task](https://www.nuget.org/packages/Microsoft.DotNet.ApiCompat.Task). (The `targets` files in that package aren't part of the .NET SDK.)
21+
22+
```xml
23+
<Project Sdk="Microsoft.NET.Sdk">
24+
25+
<PropertyGroup>
26+
<TargetFrameworks>netstandard2.0;net6.0</TargetFrameworks>
27+
<ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
28+
</PropertyGroup>
29+
30+
<ItemGroup Condition="'$(ApiCompatValidateAssemblies)' == 'true'">
31+
<PackageReference Include="Microsoft.DotNet.ApiCompat.Task" Version="8.0.100" PrivateAssets="all" IsImplicitlyDefined="true" />
32+
</ItemGroup>
33+
34+
</Project>
35+
```
36+
37+
Assembly validation runs either in the outer build for multi-targeting projects (after the `DispatchToInnerBuilds` target) or in the inner build for a single-targeting project (as part of the `PrepareForRun` target). It's also fully incremental, meaning the comparison is only triggered if the inputs or outputs have changed.
38+
39+
## Suppress compatibility warnings
40+
41+
For information about suppressing compatibility warnings, see [How to suppress](diagnostic-ids.md#how-to-suppress).

0 commit comments

Comments
 (0)