tenacom/buildvana.sdk

Develop in a state of bliss.

buildvana.sdk's Issues

Merge the AssemblyInfo and LiteralAssemblyAttributes modules

Description

Buildvana SDK Version: 1.0.0-alpha.6

The AssemblyInfo module is mostly a leftover from Tenacom Build System and it's ripe for retirement.

All the AssemblyInfo module currently does is:

• enabling the generation of assembly information by default, which is completely redundant as the relevant properties are already defaulted to true in Microsoft.NET.Sdk;
• setting a default value for the CLSCompliant and ComVisible properties in Module.props, which is unnecessary, as a default may well be established in Module.targets the same way it's done with lots of other properties;
• defining two literal assembly attributes to reflect the values of the CLSCompliant and ComVisible properties, a functionality that can be argued to pertain to the LiteralAssemblyAttributes module.

While not strictly a bug, this situation compels us, for example, to keep a 100-number slot allocated for errors and warnings that AssemblyInfo will hardly ever need. Not to mention having one more module to document.

Configuration

All configurations are affected.

Regression?

This situation predates the Buildvana project, so it is not a regression.

Other information

The proposed change will be breaking in the sense that CLSCompliant and ComVisible will need to be set in project or common files. Since Buildvana SDK is currently only being used to build itself and two Tenacom projects, this looks like a good time for a breaking change, as it will not affect anyone else.

NuGet cannot find the license, third-party notices, and package icon files

Buildvana SDK version: 0.1.0

The files in question are added to the project as AdditionalFiles items.

They should be added as Content items in order for them to be recognized by PackTask.

Add evaluation-time messages

Buildvana SDK version: 0.1.0

Along with BV_EvaluationError and BV_EvaluationWarning items, it would be nice to have BV_EvaluationMessage.

One use case is outputting the full paths of automagically found files (LICENSE etc.) so they can be easily checked.

Incompatibility with centrally-managed package versions

Description

Package references added by Buildvana SDK always have a Version metadata. When using centrally-managed package versions, MSBuild expects package versions to be declared in PackageVersion items instead, and restore fails.

Configuration

Anytime ManagePackageVersionsCentrally is set to true.

Regression?

This is not a regression.

Other information

Allow customization of default constants in ThisAssembly class

Background and motivation

The automatically generated ThisAssembly class always contains some default constants, which are always present and not overridable,

It should be possible, at the least, to disable the generation of these constants through a property.

Proposed enhancement

Implement an EnableDefaultThisAssemblyConstants boolean-like property to enable the generation of said constants.

The default value for the property should be true for compatibility with previous versions.

Implementation proposals

I believe the preceding section is detailed enough to figure out the implementation.

Usage examples

<Project>

  <PropertyGroup>
    <!-- Suppress the creation of default constants -->
    <EnableDefaultThisAssemblyConstants>false</EnableDefaultThisAssemblyConstants>
  </PropertyGroup>

  <ItemGroup>
    <!-- This item had no effect in versions up to and including 1.0.0-alpha.6 -->
    <ThisAssemblyConstant Include="Title" Type="string" Value="Not necessarily the assembly title" />
    <!-- Note: all other default constants will be suppressed too! -->
  </ItemGroup>

</Project>

Risks

Projects where EnableDefaultThisAssemblyConstants is set to false will have to redefine all needed constants - but at least it will be possible, unlike the current situation.

Automatically reference Microsoft.NETFramework.ReferenceAssemblies when needed

Background and motivation

Projects that target .NET Framework cannot be built on non-Windows systems unless they include a PackageReference to Microsoft.NETFramework.ReferenceAssemblies, a NuGet package that provides the needed reference assemblies.

Even on Windows, without said reference builds would fail, unless the appropriate .NET Developer Pack is installed on the development machine.

Remembering to reference Microsoft.NETFramework.ReferenceAssemblies on projects targeting .NET Framework looks like a typical target for Buildvana-style automation.

Proposed enhancement

Check whether the current TFM refers to .NET Framework and if so automatically adds a package reference to Microsoft.NETFramework.ReferenceAssemblies.

That would remove the annoyance completely. No configuration required. TargetFramework is already there (except on cross-targeting "outer" builds, but we can just skip the check there).

Implementation proposals

This feature is independent from the rest of the SDK, so it should probably be implemented as a new module.

There should be some way to disable this feature if unwanted, for example by setting UseNETFrameworkReferenceAssemblies to false in a project or common file.

Usage examples

Given the usual Buildvana scaffolding, this very minimal library project would build with dotnet build on Linux:

<Project Sdk>

  <PropertyGroup>
    <TargetFrameworks>net471;netstandard2.0</TargetFrameworks>
  </PropertyGroup>

</Project>

Risks

No breaking changes, negligible performance impact, no incompatibilities AFAIK.

Version file cannot be parsed any longer (compiled task missing)

Current version

1.0.0-alpha.20, after committing #158 and #161

Description

TL;DR: I messed up. Badly.

The code generation tasks are gone... and with them the ParseVersionFile task!

Yeah, I'm a forking genius. The need to get alpha 21 out the door ASAP made me skip serious testing. I should know better, I do know better, but sometimes I let rush (and sleep deprivation) get the better of me.

Configuration

All configurations, even when setting UseVersionFile to false (because #161 is buggy, too).

Regression?

It's a regression with respect to 1.0.0-alpha.20.

Other information

Version file parsing has to generate MSBuild properties, thus it just cannot be implemented with a source generator.

Bringing back the compiled tasks, for a feature I'm trying to kill, just doesn't feel right.

The best thing to do is probably to just ditch version file parsing completely, wrap up the experiments with Nerdback.GitVersioning and/or other versioning systems, and implement one of those instead.

Use source generators instead of code generation tasks

Current version

1.0.0-alpha.20

Background and motivation

Buildvana SDK uses compiled tasks to generate code. This was fine a couple years ago, when the project started, mostly because there was no choice. Now, however, we can accomplish the same results with source generators.

Pros

• Package size: Only the source generator DLL would need to be included in the package. Buildvana.Sdk.1.0.0-alpha.20.nupkg is a tad over 22Mb; a version using source generators would most probably be well under 1Mb.
• Performance: Loading and executing our MSBuild tasks is rather costly in terms of both time and memory; source generators, on the other hand, are loaded by Roslyn as part of the well-tested and optimized analyzer infrastructure.
• Simplification: The same DLL can work with both Visual Studio (which uses the .NET Framework) and .NET SDK; no more custom MSBuild targets; no more chasing moving targets (pun intended) with every new version of every component involved (MSBuild, Roslyn, .NET SDK, Visual Studio); "one code to rule them all".
• Better integration: Source generators integrate naturally into the build process, no tricks, custom targets etc. needed.
• Responsiveness: Source generators (specifically, incremental generators) can update the generated code in real time in response to changes in inputs. For example, adding a ThisAssemblyConstant item in a project file would instantly make that constant available for use in code. Now, instead, an explicit rebuild of the project is needed to update generated code.

Cons

• Visual Basic compatibility: Although incremental generators can declare the languages they work with, Visual Basic still doesn't seem to support generators at all. (actually, VB has been supporting generators since November 2020)
• ** F# compatibility:** the F# compiler does not support source generators. There are type providers but, even assuming a type provider can generate assembly attributes, it would have to be written in F#.

Proposed enhancement

Replace code generation tasks with source generators.

Useful links

• C# Source Generators by Amadeusz Sadowski
• Source Generators Cookbook in Roslyn documentation
• Incremental generators in Roslyn documentation
• Source generator updates: incremental generators (Exploring .NET 6 - Part 9) by Andrew Lock
• Creating an incremental generator by Andrew Lock
• Incremental Roslyn Source Generators In .NET 6: Code Sharing Of The Future – Part 1 by Pawel Gerr
• Using MSBuild Items and Properties in C# 9 Source Generators by Uno Platform Team
• The pain points of C# source generators: February 2022 Update by James Turner

Implementation proposals

• Incremental generators are to prefer over source generators, as they provide responsiveness to code (or, in our case, project file) changes.
• Configuration properties and items can most probably remain the same.
• Visual Basic support can be implemented from the beginning at almost no cost, as the necessary code can be copied over from current code generation tasks. When the VB compiler starts using generators, we'll be ready. Support can be removed later if the Roslyn team decides that VB is never going to use generators.

Usage examples

Usage of the SDK would not change.

Risks

• Modules currently relying on code generation tasks will lose compatibility with F# projects.

Use compiled tasks instead of inline tasks

Background and motivation

Some modules in Buildvana SDK use RoslynCodeTaskFactory to create inline tasks. The list of inline tasks in Buildvana SDK, as of version 1.0.0-alpha.6, is the following:

Module	Task name	Purpose
AssemblySigning	Buildvana.Tasks.ConvertPfxToSnk	Extract a key pair from a .pfx file into a .snk file.
LiteralAssemblyAttributes	Buildvana.Tasks.WriteLiteralAssemblyAttributes	Generate a source file with configured assembly attributes.
ParseVersionFile	Buildvana.Tasks.ParseVersionFile	Read a SemVer 2.0 version from a text file.
ThisAssemblyClass	Buildvana.Tasks.WriteThisAssemblyClass	Generate a source file for the ThisAssembly class.

While inline tasks have so far served their purpose, they present some non-trivial problems:

• they are compiled at build time, with an obvious negative impact on build performance and CI infrastructure costs;
• each task's source code must be a single file, which can get messy pretty quickly (see for example the source code for WriteThisAssemblyClass);
• each task must "reinvent the wheel" (see the common structure of Execute methods, or the BuildErrorException class defined here, here, and again here);
• they are harder and slower to test with respect to compiled classes;
• no static code analysis, Intellisense, or even basic IDE support is available for inline tasks: even a typo can go undetected until the SDK is built, packaged, and used. While this is also part of the bigger issue of the lack of tests, it is clear that inline tasks are unnecessarily hard to develop and even harder to maintain.

Proposed enhancement

Buildvana SDK should contain compiled tasks instead of inline tasks.

Implementation proposals

For examples of MSBuild SDK projects containing inline tasks, see microsoft/MSBuildSdks. They seem to have worked out all the details.

Usage examples

No changes in the usage of Buildvana SDK should derive from the implementation of compiled tasks.

Risks

There's the possibility of incompatibilities arising from changes in the Microsoft.Build.* libraries. Again, The MSBuildSDKs team seem to have done the heavy lifting already: see for example their selection of compiled task TFM according to MSBuild version and runtime type.

Test project type not detected when building with .NET CLI

Description

Using the dotnet build command to build a solution containing test projects results in a series of RS0016 warnings in the test projects.

Same results with .NET Core SDK v3.1.402 and .NET SDK v5.0.100-preview.8.20417.9.

This does not happen when building from Visual Studio (I'm currently using VS2019 Community v16.7.3), nor with the dotnet msbuild command (with both the above-mentioned SDK versions).

This is the relevant output, captured when building Cecil.XmlDocNames with dotnet build -c Release (messages are in Italian):

StringBuilderExtensionsTest.cs(18,18): warning RS0016: Il simbolo 'StringBuilderExtensionsTest' non fa parte dell'API dichiarata. [d:\Projects\OpenSource\Cecil.XmlDocNames\tests\Cecil.XmlDocNames.Tests\Cecil.XmlDocNames.Tests.csproj]
StringBuilderExtensionsTest.cs(21,21): warning RS0016: Il simbolo 'AppendXmlDocName_WithNullMember_ThrowsArgumentNullException' non fa parte dell'API dichiarata. [d:\Projects\OpenSource\Cecil.XmlDocNames\tests\Cecil.XmlDocNames.Tests\Cecil.XmlDocNames.Tests.csproj]
StringBuilderExtensionsTest.cs(18,18): warning RS0016: Il simbolo 'costruttore implicito per 'StringBuilderExtensionsTest'' non fa parte dell'API dichiarata. [d:\Projects\OpenSource\Cecil.XmlDocNames\tests\Cecil.XmlDocNames.Tests\Cecil.XmlDocNames.Tests.csproj]
StringBuilderExtensionsTest.cs(28,21): warning RS0016: Il simbolo 'AppendXmlDocName_WithNonGenericType_ReturnsCorrectValue' non fa parte dell'API dichiarata. [d:\Projects\OpenSource\Cecil.XmlDocNames\tests\Cecil.XmlDocNames.Tests\Cecil.XmlDocNames.Tests.csproj]
StringBuilderExtensionsTest.cs(38,21): warning RS0016: Il simbolo 'AppendXmlDocName_WithGenericType_ReturnsCorrectValue' non fa parte dell'API dichiarata. [d:\Projects\OpenSource\Cecil.XmlDocNames\tests\Cecil.XmlDocNames.Tests\Cecil.XmlDocNames.Tests.csproj]
StringBuilderExtensionsTest.cs(48,21): warning RS0016: Il simbolo 'AppendXmlDocName_WithField_ReturnsCorrectValue' non fa parte dell'API dichiarata. [d:\Projects\OpenSource\Cecil.XmlDocNames\tests\Cecil.XmlDocNames.Tests\Cecil.XmlDocNames.Tests.csproj]
StringBuilderExtensionsTest.cs(60,21): warning RS0016: Il simbolo 'AppendXmlDocName_WithEvent_ReturnsCorrectValue' non fa parte dell'API dichiarata. [d:\Projects\OpenSource\Cecil.XmlDocNames\tests\Cecil.XmlDocNames.Tests\Cecil.XmlDocNames.Tests.csproj]
StringBuilderExtensionsTest.cs(72,21): warning RS0016: Il simbolo 'AppendXmlDocName_WithProperty_ReturnsCorrectValue' non fa parte dell'API dichiarata. [d:\Projects\OpenSource\Cecil.XmlDocNames\tests\Cecil.XmlDocNames.Tests\Cecil.XmlDocNames.Tests.csproj]
StringBuilderExtensionsTest.cs(84,21): warning RS0016: Il simbolo 'AppendXmlDocName_WithConstructorOfNonGenericType_ReturnsCorrectValue' non fa parte dell'API dichiarata. [d:\Projects\OpenSource\Cecil.XmlDocNames\tests\Cecil.XmlDocNames.Tests\Cecil.XmlDocNames.Tests.csproj]
StringBuilderExtensionsTest.cs(96,21): warning RS0016: Il simbolo 'AppendXmlDocName_WithConstructorOfGenericType_ReturnsCorrectValue' non fa parte dell'API dichiarata. [d:\Projects\OpenSource\Cecil.XmlDocNames\tests\Cecil.XmlDocNames.Tests\Cecil.XmlDocNames.Tests.csproj]
StringBuilderExtensionsTest.cs(108,21): warning RS0016: Il simbolo 'AppendXmlDocName_WithNonGenericMethodOfNonGenericType_ReturnsCorrectValue' non fa parte dell'API dichiarata. [d:\Projects\OpenSource\Cecil.XmlDocNames\tests\Cecil.XmlDocNames.Tests\Cecil.XmlDocNames.Tests.csproj]
StringBuilderExtensionsTest.cs(120,21): warning RS0016: Il simbolo 'AppendXmlDocName_WithGenericMethodOfNonGenericType_ReturnsCorrectValue' non fa parte dell'API dichiarata. [d:\Projects\OpenSource\Cecil.XmlDocNames\tests\Cecil.XmlDocNames.Tests\Cecil.XmlDocNames.Tests.csproj]
StringBuilderExtensionsTest.cs(132,21): warning RS0016: Il simbolo 'AppendXmlDocName_WithNonGenericMethodOfGenericType_ReturnsCorrectValue' non fa parte dell'API dichiarata. [d:\Projects\OpenSource\Cecil.XmlDocNames\tests\Cecil.XmlDocNames.Tests\Cecil.XmlDocNames.Tests.csproj]
StringBuilderExtensionsTest.cs(144,21): warning RS0016: Il simbolo 'AppendXmlDocName_WithGenericMethodOfGenericType_ReturnsCorrectValue' non fa parte dell'API dichiarata. [d:\Projects\OpenSource\Cecil.XmlDocNames\tests\Cecil.XmlDocNames.Tests\Cecil.XmlDocNames.Tests.csproj]

Configuration

Buildvana SDK v1.0.0-alpha.2

• .NET Core SDK v3.1.402, dotnet build: warnings
• .NET Core SDK v3.1.402, dotnet msbuild: OK
• .NET SDK v5.0.100-preview.8.20417.9, dotnet build: warnings
• .NET SDK v5.0.100-preview.8.20417.9, dotnet msbuild: OK
• Visual Studio 2019 Community v16.7.3, building from IDE: OK

Regression?

This is the first time I try building Cecil.XmlDocNames using Buildvana SDK, so I can't really tell.

Other information

By examining MSBuild's binary logs and diagnostic output, I've discovered that BV_IsTestProject is only set to true during restore. When actually building, BV_IsLibraryProject is true instead.

Apparently we can't trust the Microsoft.NET.Test.Sdk package to reliably set IsTestProject to true, so some other detection method for test projects is probably needed.

Literal assembly attributes are never generated

Description

Literal assembly attributes (ClsCompliant, ComVisible) are nowhere to be found in compiled assemblies.

Configuration

Buildvana SDK v1.0.0-alpha.3

Regression?

Definitely not a regression. The files in Modules\LiteralAssemblyAttributes haven't been touched since before 1.0.0-alpha.1.

Other information

The direct cause of the issue is that src\Buildvana.Sdk\Modules\LiteralAssemblyAttributes\AfterModule.targets should be named AfterModules.targets. The targets it contains never run because the file is never imported.

Unfortunately, correctly renaming the file opens the door to the horrible mess that is the LiteralAssemblyAttributes module. Looks like unfinished code, that made its way into releases only because 1) it doesn't generate errors (because it is not imported to start with) and 2) there are no automated tests for the SDK.

There are no workarounds, but this is beyond workarounds. This is a critical bug that must be fixed ASAP.

Add messages to show which files are being automagically included in a NuGet package

Background and motivation

Automagically including license, third-party notices, and package icon files is cool. Unfortunately, there's no way of knowing they have actually been detected and included in a package, short of examining the package contents post-build.

Furthermore, when more than one file recognizable as e.g. icon package is present, one should look at the documentation (or, currently, at the SDK source) to know which one will be included.

Let's see a practical, if somewhat extreme, example. Assuming a library called MyLibrary, part of a product called MyProduct (thus with <Product>MyProduct</Product> somewhere probably in a Common.props file), can you tell which of the following files will end up as the package icon for MyLibrary.nupkg?

<home_directory>\
|
+--- branding\
|    |
|    +--- icon.png
|    +--- MyLibrary.package.png
|    +--- MyProduct.package.png
|    +--- PackageIcon.png
|
+--- graphics\
|    |
|    +--- icon.png
|    +--- MyLibrary.package.png
|    +--- MyProduct.package.png
|    +--- PackageIcon.png
|
+--- src\
|    |
|    +--- branding\
|    |    |
|    |    +--- icon.png
|    |    +--- MyLibrary.package.png
|    |    +--- MyProduct.package.png
|    |    +--- PackageIcon.png
|    |
|    +--- graphics\
|    |    |
|    |    +--- icon.png
|    |    +--- MyLibrary.package.png
|    |    +--- MyProduct.package.png
|    |    +--- PackageIcon.png
|    |
|    +--- MyLibrary\
|    |    |
|    |    +--- branding\
|    |    |    |
|    |    |    +--- icon.png
|    |    |    +--- MyLibrary.package.png
|    |    |    +--- MyProduct.package.png
|    |    |    +--- PackageIcon.png
|    |    |
|    |    +--- graphics\
|    |    |    |
|    |    |    +--- icon.png
|    |    |    +--- MyLibrary.package.png
|    |    |    +--- MyProduct.package.png
|    |    |    +--- PackageIcon.png
|    |    |
|    |    + icon.png
|    |    + MyLibrary.package.png
|    |    + MyProduct.package.png
|    |    + PackageIcon.png
|    |
|    +--- icon.png
|    +--- MyLibrary.package.png
|    +--- MyProduct.package.png
|    +--- PackageIcon.png
|
+--- icon.png
+--- MyLibrary.package.png
+--- MyProduct.package.png
+--- PackageIcon.png

A look at the SDK sources will tell us that the answer is src\MyLibrary\MyLibrary.package.png... but, putting aside the lack of related documentation for the moment, a build-time message stating which file is actually being used would help in identifying problems when, for example, the intended package icon was graphics\PackageIcon.png.

Proposed enhancement

Once #9 is implemented, add evaluation-phase messages to make the choice of license, third-party notices, and package icon evident.

Implementation proposals

In order not to clutter the build output, the messages could have an Importance of High for debug builds and Normal for release builds.

Usage examples

The example above pretty much says it all.

Risks

Since it's just a matter of adding a few messages. none of which should possibily contain sensitive data, there should be no risk involved.

Issue labels are not configured according to labels.json

Description

Issue labels on this repository are not configured according to the contents of .github/labels.json.

Configuration

(n/a)

Regression?

(n/a)

Other information

The define-labels workflow is failing due to invalid JSON.

This is an extract of a define-labels run:

Run lannonbr/[email protected]
(node:2628) UnhandledPromiseRejectionWarning: SyntaxError: Unexpected token { in JSON at position 3116
    at JSON.parse (<anonymous>)
    at c (/home/runner/work/_actions/lannonbr/issue-label-manager-action/2.0.0/lib/index.js:202:893)
    at processTicksAndRejections (internal/process/task_queues.js:93:5)
(node:2628) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). (rejection id: 1)
(node:2628) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

XML documentation files not created

Current version

1.0.0-aplha.10 through 1.0.0-aplha.12

Description

XML documentation files for libraries are not created.

Forcing XmlDocs to true has no effect.

MSBuild binary logs reveal that the GenerateDocumentationFile property remains false throughout the build process.

Configuration

Happens to Resharper.ExportAnnotations.Core, building with .NET CLI 5.0.400 on a Windows 10/x64 system.

Regression?

This is a regression with respect to version 1.0.0-alpha.9.

Other information

The probable cause is that .props files for modules are not included any more by Buildvana's Sdk.props.

I couldn't find any workaround for this issue.

Make evaluation-phase errors and warnings part of the public-facing features

Background and motivation

Evaluation-phase errors and warnings are a cool feature that can also be useful in project and / or Common.* files.

Proposed enhancement

Make evaluation-phase errors and warnings part of the public-facing features of the SDK.

Implementation proposals

Just rename the BV_EvaluationError and BV_EvaluationWarning items to EvaluationError and EvaluationWarning respectively.

Usage examples

<Project>

  <ItemGroup>
    <!-- The "error code" can be anything, as long as there is no collision with existing prefixes. -->
    <EvaluationError
      Condition="'$(Something)' != 'right'"
      Include="MYERR0001"
      Text="Something is not right." />
  </ItemGroup>

</Project>

Risks

Since the affected feature is currently only used internally, this requires no breaking changes and there is no risk of incompatibilities.

The ThisAssembly class is never generated

Description

Buildvana SDK version: 1.0.0-alpha.6

The ThisAssembly class is never present in assemblies built using Buildvana SDK.

Configuration

All configurations are affected (see below).

Regression?

Not a regression.

Other information

The problem seems to be in an erroneous condition check.

Make automatic inclusion of files in package less verbose

Current version: 1.0.0-alpha.9

Background and motivation

Using '...' as license file in ... package.
Using '...' as third-party copyright notices file in ... package.
Using '...' as package icon in ... package.

The above messages, generated by the NuGet.Pack module, are output by MSBuild at every invocation, for every project.

Since MSBuild re-invokes itself (or better, its engine) via MSBuild tasks in several occasions (inner builds, dependency walking, etc.) a project with three target frameworks and a couple project references may easily see its output clogged by several instances of these messages, even when they have nothing to do with the originally invoked target, e.g. when restoring or building.

I don't object to the usefulness of the messages, but they'd be better shown just before packing.

Proposed enhancement

Add a target in Modules\NuGetPack\Module.Core.targets that runs just before Pack and shows the same information. Remove the three corresponding EvaluationMessage items.

Implementation proposals

See above.

Usage examples

(n/a)

Risks

The biggest risk here is that a user may notice they're using the wrong icon or license file in a package only when actually packing, instead of at build time. Honestly, though, the messages get so pervasive that I, for one, hardly look at them at all after a while.

Support more TFMs for compiled tasks

Background and motivation

See Tenacom/ReSharper.ExportAnnotations#20

We should probably take a hint from Microsoft.Build.Artifacts as to which TFMs to support and how to choose the right binary to use in a build.

We should, too.

Proposed enhancement

Support more TFMs for compiled tasks, in order to support more use cases.

Implementation proposals

• Modify TargetFrameworks to read net46;net472;netcoreapp2.1;netcoreapp3.1;net5.0.
• Use conditional package references for Microsoft.Build.* packages, as last versions do not support net46.
• Select the appropriate compiled assembly to use, the same way ReSharper.Annotations.Task does it.

Usage examples

No changes in usage.

Risks

The net46 TFM could require us to downgrade the code to C# 7.3, thus losing nullable reference types. In that case, we can use ReSharper to check for nullability issues; how to perform the necessary checks in CI remains to be researched.

Warning BVW1900 incorrectly issued on all projects using TargetFrameworks

Current version: 1.0.0-alpha.9

Description

For every project containing a <TargetFrameworks> property and having ThisAssembly class generation enabled, warning BVW1900 (ThisAssembly class generation is only supported in C# and Visual Basic projects) is issued during build, regardless of the actual project language.

This does not happen on projects having a <TargetFramework> property; however, it happens even when <TargetFrameworks> specifies a single TFM.

Configuration

Any configuration / tooolchain.

Regression?

Although not 100% sure, looking at Git history I'd say it has always been this way.

Other information

The problem is in the condition check for warning BVW1900. The check should be skipped if TargetFramework is not defined (i.e. during outer builds) because the Language property will not be set yet.

BV_IsLibraryProject property is always false

Buildvana SDK version: 0.1.0

Turns out we cannot determine the project type in Sdk.props, because the logic relies on the value of OutputType, which is usually left empty in library project files and set to 'Library' later in the evaluation process.

Unfortunately, the only way out is to move the project type evaluation logic to Sdk.targets and document the fact that this information is available neither in .props files, nor in project files.

Buildvana SDK breaks Omnisharp in VS Code

Current version: 1.0.0-alpha.10

Description

When a repository using Buildvana SDK is opened as folder in Visual Studio Code, a pop-up windows appears after a few seconds, warning that "one or more projects failed to load", even if the solution has already been successfully built with Visual Studio, .NET SDK, or both.

The "Omnisharp log" window reports a compiled task failure, as follows:

[fail]: OmniSharp.MSBuild.ProjectLoader
        The "WriteLiteralAssemblyAttributes" task could not be instantiated from "C:\Users\{{path of NuGet package cache}}\buildvana.sdk\1.0.0-alpha.10\bin\net472\Buildvana.Sdk.Tasks.dll". Could not load file or assembly 'Microsoft.Build, Version=15.1.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a' or one of its dependencies. The system cannot find the file specified.
[fail]: OmniSharp.MSBuild.ProjectLoader
        The "WriteLiteralAssemblyAttributes" task has been declared or used incorrectly, or failed during construction. Check the spelling of the task name and the assembly name.
[warn]: OmniSharp.MSBuild.ProjectManager
        Failed to load project file '{{full name of project file}}'.
{{full name of project file}}
{{path of NuGet package cache}}\buildvana.sdk\1.0.0-alpha.10\Modules\LiteralAssemblyAttributes\Module.Core.targets(52,5): Error: The "WriteLiteralAssemblyAttributes" task could not be instantiated from "{{path of NuGet package cache}}\buildvana.sdk\1.0.0-alpha.10\bin\net472\Buildvana.Sdk.Tasks.dll". Could not load file or assembly 'Microsoft.Build, Version=15.1.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a' or one of its dependencies. The system cannot find the file specified.
{{path of NuGet package cache}}\buildvana.sdk\1.0.0-alpha.10\Modules\LiteralAssemblyAttributes\Module.Core.targets(52,5): Error: The "WriteLiteralAssemblyAttributes" task has been declared or used incorrectly, or failed during construction. Check the spelling of the task name and the assembly name.

The same is reported for all projects in the solution, or at least for those that use literal assembly attributes (in my case, all of them).

What's even weirder is that no error is reported about the WriteThisAssemblyClass task, which is used in the same solution. The two tasks share the same loading method (they are both loaded in separate AppDomains) by both subclassing Buildvana.Sdk.Tasks.BuildvanaSdkCodeGeneratorTask, which in turn derives from Buildvana.Sdk.Tasks.BuildvanaSdkIsolatedTask: it seems logical that an issue regarding the availability of Microsoft.Build.dll would affect both of them.

Configuration

VS Code 1.52.1 on Windows 10.0.10942 (20H2) x64.

Solution built successfully on the same machine with both .NET SDK 5.0.1 and Visual Studio 2019 v16.8.4.

Regression?

This is definitely a regression, as it didn't happen before the compiled tasks overhaul in 1.0.0-alpha.10.

Other information

Nothing else of relevance that I can think of.

Use the SDK to build itself

Summary

Buildvana SDK should be used to build itself.

Advantages

• more credibility due to dogfooding
• no more need to keep the VERSION file and the <Version> tag in Buildvana.Sdk.csproj in sync manually
• less clutter in project-specific files
• ability to build more SDKs without duplicating build scripts

Disadvantages

• none that I can see

PR template doesn't work

Description

When opening a PR, the template doesn't appear.

Configuration

(n/a)

Regression?

No regression - it has never worked.

Other information

An obvious workaround is copying the template from the raw view and pasting it into the PR post.

Standard analyzers are not used by default in test projects

Description

Buildvana SDK disables standard analyzers by default for test projects. There seems to be no good reason for this.

Configuration

(n/a)

Regression?

(n/a)

Other information

An obvious workaround is to explicitly enable standard analyzers in each test project file, or in a Common.props file.

No way to opt out of using the VERSION file

Current version

1.0.0-alpha.20

Description

The VERSION file was born as a temporary, quick-and-dirty fix. By now it's definitely overstayed its welcome... by years!

The problem is that I cannot explore other options (for example Nerdbank.GitVersioning, but there are more out there) because there's no way to opt out of the use of the VERSION file.

Configuration

Happens on any configuration.

Regression?

Not a regression.

Other information

Just not parsing the VERSION file if it doesn't exist is not feasible for two reasons:

• The name is configurable. If a user defines VersionFileName in a project, they probably prefer the SDK to issue a diagnostic if it doesn't exist instead of silently skipping it; and even if they use the default name VERSION the reasoning is the same.
• Other versioning systems could potentially require a file of the same name, thus also reactivating the parsing logic as by (black) magic.

A UseVersionFile property, defaulting to true for compatibility, looks like a possible solution. Mentioning a feature in a project that doesn't use it looks weird (that was also the reasoning behind changing the default for UseJetBrainsAnnotations to false in 1.0.0-alpha.20); however, once a suitable versioning system is found, VERSION file parsing is bound to be replaced in its entirety.

In other words, I'm proposing a temporary fix to a problem caused by another temporary fix. Cringeworthy as it is, at least it's a step towards getting rid of both of them.

XML documentation is never generated

Buildvana SDK version: 0.1.0

The GenerateDocumentationFile property is set to its default of false in Microsoft.NET.Sdk.BeforeCommon.props, that is long before we have a chance of setting our default.

Use another property not known to Microsoft's SDKs, for example XmlDocs, so it remains untouched unless by a project or Common file; then set GenerateDocumentationFile accordingly in Modules\XmlDocumentation\Module.targets.

Suppress CA1707 by default in test projects

Background and motivation

Test projects usually have long, underscore-separated method names, like AppendXmlDocName_WithNullMember_ThrowsArgumentNullException or AppendXmlDocName_WithField_ReturnsCorrectValue, that trigger code quality warning CA1707.

While said warning has an agreeable rationale, I find myself routinely disabling CA1707 on test projects, like this. This is exactly the kind of repetitive task I wanted to avoid with Buildvana SDK.

Proposed enhancement

Disable CA1707 by default in test projects.

Implementation proposals

• Add a public-facing property AllowUnderscoresInMemberNames.
• If said property is left unset by project / common files, set it to true for test projects, false for other projects.
• If the property is true, suppress warning CA1707 by appending the string ";CA1707" to the NoWarn property.

Usage examples

Normal usage: nothing to do in projects / common files. (The Buildvana way! 😄)

Enable CA1707 in a test project:

  <AllowUnderscoresInMemberNames>false</AllowUnderscoresInMemberNames>

Risks

If a test project already suppresses CA1707, the warning will appear twice in the NoWarn property: no consequences AFAIK.