Merge pull request #94 from Lombiq/issue/HAST-327

HAST-327: New instructions about nested Directory.Build.props usage
Lombiq · Oct 19, 2023 · 4883e67 · 4883e67
2 parents 518f61f + 8778087
commit 4883e67
Show file tree

Hide file tree

Showing 2 changed files with 18 additions and 7 deletions.
diff --git a/Lombiq.Analyzers/Docs/AddingAnalyzers.md b/Lombiq.Analyzers/Docs/AddingAnalyzers.md
@@ -17,9 +17,9 @@ You only need to reference a single project; e.g., even though Orchard Core apps
 If you don't want to stay on the cutting-edge version, nor do you intend to contribute to Lombiq .NET Analyzers, you can use one of the NuGet packages. Install the package suitable for your project, as described above. Check for the latest version number [on NuGet](https://www.nuget.org/packages/Lombiq.Analyzers/).
 
 ```csproj
-    <PackageReference Include="Lombiq.Analyzers" Version="<latest version>">
-      <PrivateAssets>all</PrivateAssets>
-    </PackageReference>
+<PackageReference Include="Lombiq.Analyzers" Version="<latest version>">
+    <PrivateAssets>all</PrivateAssets>
+</PackageReference>
 ```
 
 The `<PrivateAssets>all</PrivateAssets>` is necessary to prevent the analyzers "leaking" into other projects that may consume yours.

diff --git a/Lombiq.Analyzers/Docs/ConfiguringAnalyzers.md b/Lombiq.Analyzers/Docs/ConfiguringAnalyzers.md
@@ -8,18 +8,29 @@ Place a _Directory.Build.props_ file into the project's folder (or folder with s
 
 ```xml
 <Project>
-  <ItemGroup> 
-      <Analyzer Remove="@(Analyzer)" /> 
-  </ItemGroup>
 </Project>
 ```
 
-This will completely disable code analysis packages. To also disable .NET SDK analysis override them from a _.globalconfig_ file placed into the given project's folder. There you can disable any unwanted rules, like disabling .NET code style analysis completely:
+MSBuild only loads in the closest _Directory.Build.props_ file to the project being built. So this empty props file will supersede any parent _Directory.Build.props_. To also disable .NET SDK analysis override them from a _.globalconfig_ file placed into the given project's folder. There you can disable any unwanted rules, like disabling .NET code style analysis completely:
 
 ```editorconfig
 dotnet_analyzer_diagnostic.category-Style.severity = none
 ```
 
+If you rely on `Lombiq.Analyzers` to set up compiler properties such as `<LangVersion>` you may still want to import the parent _Directory.Build.props_ file and just disable the code analyzers. Put this into the _Directory.Build.props_ file instead:
+
+```xml
+<Project>
+    <PropertyGroup>
+        <RunCodeAnalysis>false</RunCodeAnalysis>
+    </PropertyGroup>
+
+    <Import Project="$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))" />
+</Project>
+```
+
+Or if you added `Lombiq.Analyzers` to only a single project as a package reference, you can just add the `<RunCodeAnalysis>false</RunCodeAnalysis>` element.
+
 ## How to disable all analyzers during `dotnet build`
 
 By default the `dotnet build` command runs analyzers and produces code analysis warnings if there are any but it makes the build slower. Pass the `/p:RunCodeAnalysis=false` parameter to disable analyzers during build, like: