Name Generated files with the .g.cs convention

[pinkfloydx33]

Can the generator be updated to name (hint) the generated "files" using the .g.cs convention?

I just spent the last six hours trying to figure out why Coverlet stopped reporting coverage results for one of my projects. As it turns out, they identify generated sources using the .g.cs extension for the "file". If the extension is missing it breaks their logic as they now parse it as a missing file, silently breaking the rest of the process.

Now I realize this isn't a bug with this library per se, however this has been the typical naming convention for generated files for years (even prior to source generators). It also has impact when using the option to output the generated files to disk (EmitCompilerGeneratedFiles) as those coming from this project don't match everything else.

I was able to confirm this is truly the issue by updating one of my own generators to use a non-conforming file name.

I now need to remove this library from my project as I value the code coverage more than the constants...which is Incredibly unfortunate :-(

I plan on opening an issue with Coverlet, however their response in all the issues I scoured through this morning all say to "just name your generated files as .g.cs", which is all fine and good if you own the generator code. A similar report had surfaced related to Razor page source generators and it was dotnet that made the "fix" on their end, rather than Coverlet, so I'm not going to hold my breath.

[rdeago]

Can the generator be updated to name (hint) the generated "files" using the .g.cs convention?

Of course but, being just hints, this would guarantee exactly nothing.

ExcludeFromCodeCoverageAttribute applied to ThisAssembly would be a better guarantee, as it is probably recognized not only by Coverlet but by other similar tools too.

The problem is that ExcludeFromCodeCoverageAttribute cannot be applied more than once to the same type and currently ThisAssembly generators are each on its own, generating a partial class without knowing nor caring whether other "chunks" of the class are being added elsewhere.

We need to generate code like the following (or the VB equivalent of course) exactly once regardless of which ThisAssembly modules are referenced by a project:

//------------------------------------------------------------------------------
// <auto-generated>
//     This code was generated by a tool.
//
//     Changes to this file may cause incorrect behavior and will be lost if
//     the code is regenerated.
// </auto-generated>
//------------------------------------------------------------------------------

using System.Diagnostics.CodeAnalysis;

/// <summary>
/// Provides access to the current assembly information as pure constants, 
///  without requiring reflection.
/// </summary>
[ExcludeFromCodeCoverage]
partial class ThisAssembly
{
}

(Of course @pinkfloydx33 you can add the same code to your project as a quick workaround.)

This can be solved two different ways:

1. Add a source generator in a package referenced by all ThisAssembly packages (ThisAssembly.Prerequisites comes to mind as a good candidate) that generates code like the above;
2. Add the same generator in a separate package that can be referenced when necessary (ThisAssembly.ExcludeFromCodeCoverage may be an appropriate name, if a bit verbose).

Personally I'd go for number 1; the rationale is that ExcludeFromCodeCoverageAttribute is compatible with practically every runtime out there and can thus be applied inconditionally without any worry. Besides, the "common" code generator would be a good place for ThisAssembly's XML docs too.

@kzu, thoughts?

[pinkfloydx33]

It's been a while since I originally posted and I'm not near a computer to check, but I think it has nothing to do with the attribute itself. Most coverage tools (Coverlet included) know how to exclude generated code from the coverage process. In this case they identity such code by various means, one being the g.cs extension. I can't recall offhand exactly since it's been so long, but I seem to remember during debugging that Coverlet ends up with a broken compilation due to its handling of such files. Attribute or not it'd still fail. I can confirm later today with your work-around, which would be enough for me if it does actually fix things.

[pinkfloydx33]

It's actually part of how they match sources to files. They look for a physical file and if not found, check for the extension. If extension is there they "allow" it though, otherwise they ignore it, which then breaks their inproc compilation process. Quick search, but I think this is the offender:

https://github.com/coverlet-coverage/coverlet/blob/2bb04f21ec30978335ad00b5d52b473c45181070/src/coverlet.core/Helpers/InstrumentationHelper.cs#L186-L189

You can see the issue described here: coverlet-coverage/coverlet#1297 and it's linked issues.

One such example of "fix your generated file names" (I remember there being others): coverlet-coverage/coverlet#1084 (comment)

Obviously this is a Coverlet issue and not a ThisAssembly problem. However, the convention has existed for years. I'm sure there's other tools out there that interact with source and/or perform inproc-compilation and make such assumptions that could potentially be impacted. I haven't tried it with other tools, but I'd be interested in how Stryker behaves for example.

It seems such an easy/simple adjustment to make on this end, hence my original suggestion.

[rdeago]

Oh, now I see. Sorry @pinkfloydx33, you're right, the attribute would not help here - although it may be a good idea to add it nonetheless.

What bugs me is, if the .g extension prefix is such a universally recognized marker of generated files (I have used it myself for the same purpose) why doesn't Roslyn add it automatically to all generated source files? Instead, Roslyn gives us the mere possibility of "hinting", i.e. never be 100% sure the file name ends up being what we thought. This is the reason why your suggestion doesn't look like a good idea to me: it isn't deterministic. Basically the source generator should add a ".g" to the hint and hope Roslyn got up on the good side of the bed this morning, so to speak.

While I don't have a real, definitive solution to your problem, I'd suggest to research, as much as possible, a workaround that involves modifying your project, not source generators themselves. My rationale is that source generators are becoming nearly ubiquitous and your project could easily end up using three or four of them, some even from the SDK itself; good luck filing issues with every source generator whose output gets Coverlet confused.

A possible workaround, assuming you run Coverlet immediately after a build, may be to tell Roslyn to "materialize" generated source files on disk, by adding the following XML code to your project (or to a Directory.Build.props file, as you see fit):

  <PropertyGroup>
    <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
    <CompilerGeneratedFilesOutputPath>$(BaseIntermediateOutputPath)Generated</CompilerGeneratedFilesOutputPath>
  </PropertyGroup>

This way Coverlet will find generated all files on the local file system, regardless of the source generator involved.

I hope this helps you.

[kzu]

Could you confirm that the workaround works? That would indicate whether the issue is that coverlet does not find the files, rather than an issue with the code extension?

[pinkfloydx33]

I haven't tried yet. I'll try to check today.

In the past I've had issues when outputting source generated files to disk...specifically not being able to compile at all since the compiler finds both the source on disk and the generared "in memory" files, ending up with duplicate classes, etc. Though that was a while back so perhaps that's been fixed.

[rdeago]

I started writing generators only very recently (Roslyn 4.2 / VS 2022 17.2) and I've had no such problem. I have read all the titles of source-generator-related issues in Roslyn's repo (both open and closed) but I can't seem to find anything similar to what you describe. Hopefully they solved it before it was even reported.

[pinkfloydx33]

Ok so the trick to getting EmitCompilerGeneratedFiles to work is to not put CompilerGeneratedFilesOutputPath in a Directory.Build.props file because the variable is not known there. The files end up in [ProjectRoot]\Generated which causes duplicate classes/ambiguous references across all generators and subsequent compilations to fail. Sticking it in either Directory.Build.targets or the project files does work properly (files end up under obj), at least in the sense that secondary compilations/test runs don't break entirely.

In any event, this does not help Coverlet--it still fails to analyze the project. I'll just keep my work-around of using reflection in the app. I'm only grabbing two properties anyways. Maybe someday I'll update one of my generators to grab them.

[rdeago]

this does not help Coverlet--it still fails to analyze the project

Sorry to read that. I wonder whether there's some option to embed generated source files in the .pdb (and, of course, whether Coverlet would then be able to read them).

[znakeeye]

Ok so the trick to getting EmitCompilerGeneratedFiles to work is to not put CompilerGeneratedFilesOutputPath in a Directory.Build.props file because the variable is not known there. The files end up in [ProjectRoot]\Generated which causes duplicate classes/ambiguous references across all generators and subsequent compilations to fail. Sticking it in either Directory.Build.targets or the project files does work properly (files end up under obj), at least in the sense that secondary compilations/test runs don't break entirely.

In any event, this does not help Coverlet--it still fails to analyze the project. I'll just keep my work-around of using reflection in the app. I'm only grabbing two properties anyways. Maybe someday I'll update one of my generators to grab them.

It can be done in Directory.Build.Props if you combine it with a Directory.Build.targets file!

Directory.Build.props

<Project>
   <PropertyGroup Label="Code Generation">
      <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
      <CompilerGeneratedFilesOutputPath>Generated</CompilerGeneratedFilesOutputPath>
   </PropertyGroup>
</Project>

Directory.Build.targets

<Project>
   <Target Name="ExcludeGeneratedFiles" BeforeTargets="CoreCompile">
      <ItemGroup Condition="'$(CompilerGeneratedFilesOutputPath)' != ''">
         <!-- Don't include the output from a previous source generator execution into future runs; -->
         <!-- the */** trick here ensures that there's at least one subdirectory, which is our key  -->
         <!-- that it's coming from a source generator as opposed to something that is coming from  -->
         <!-- some other tool. -->
         <Compile Remove="$(CompilerGeneratedFilesOutputPath)/*/**/*.cs" />
         <None Include="$(CompilerGeneratedFilesOutputPath)/**" />
      </ItemGroup>
   </Target>
</Project>

[rdeago]

At about the time this issue came up, I did some research about the best way to inject code in projects, avoiding problems with Coverlet as well as other tools.

I've finally found the time to polish my results up and publish them as a blog post: here it is, should anyone care.

[znakeeye]

Very good resource! Thank you! A few doubts though.

Consider a partial class generator, where the members are merged from another class declaration. A good example is the PartialMixins generator. In this case - where code is merely moved from a "template" class to the partial class - wouldn't you want to have code/test coverage for generated properties/methods?

All in all, I believe violating "Rule of the House" 3, 4 and 5 makes sense for partial classes.

[rdeago]

My "Rules of the House" all descend from one fundamental rule: Code I didn't write must not be my concern.

That goes double for generated code, because it is not even meant to be read by a human, let alone debugged, covered by unit tests (except maybe as part of integration tests for the generator) or used to judge your code style.

PartialMixins is obviously an edge case, because it adds your own code - which you probably want to see, cover, and debug - to your project. As it is your own code, Rules of the House just don't apply to it.

[pinkfloydx33]

Coverlet has actually fixed the underlying problem finally! coverlet-coverage/coverlet#1164

The C# source generators are handled by identifying them using a best practice that the document names should end in ".g.cs", and similar logic can be added for the other issues. But the source generator naming is but a best practice and not all projects will follow it, and new compiler issues will likely turn up in the future, so this heuristic will continue to cause issues.

[kzu]

Great to know! In addition, all generators in this project use .g.cs now too, just in case.