Determinism end-user experience is poor

[IanKemp]

I created a new .NET Standard 2.0 class library in Visual Studio 2017 (15.6.6) this morning and set the Assembly Version to 1.0.*. Upon build, I was confronted with the error message:

The specified version string contains wildcards, which are not compatible with determinism. Either remove wildcards from the version string, or disable determinism for this compilation

Cue research into what the heck determinism means in the context of C# compilation, leading me to know that I do, in fact, want it disabled for my use case. Cue more research into how to disable it, which finally lead me to this answer on Stack Overflow. Not very discoverable!

I see that #22660 and #22973 somewhat addressed this issue by making the error more explicit, but in my opinion it's still not useful or helpful enough:

• It does not explain what determinism is and why it is desirable, as was suggested by https://github.com/dotnet/roslyn/issues/22660#issuecomment-340123621
• It does not explain how to disable determinism

This is compounded by the fact that there doesn't seem to be a Microsoft documentation page explaining how to control determinism from the command-line or in a .csproj. The closest I have found is this.

tl;dr this is all a bit of a mess and it's definitely not a great experience for someone who is dipping their toe in .NET Standard. Suggestions to make things better:

• Add a checkbox for determinism to the Visual Studio "Project Properties" UI for .NET Standard projects to allow the user to control this setting (I appreciate this is probably not the appropriate repo to make this request, please advise where I should open a ticket if not)
• Create an official documentation page discussing what determinism is and how to enable or disable it from the command-line (MSBuild and csc) and in a csproj (via Visual Studio UI and manually editing)
• Update the error message to link to the aforementioned page

[sharwell]

This is a great report covering the complete user experience. Thanks for taking the time to report the details of the various pain points you hit!

leading me to know that I do, in fact, want it disabled for my use case

My biggest initial concern is the documentation led someone to this conclusion.

[IanKemp]

@sharwell from the linked SO answer:

However if you are using TeamCity, TFS or other CI/CD tool, it's probably better to keep the version number controlled and incremented by them and pass to build as a parameter

which is exactly my scenario. I would very much like to enable determinism, but right now it's not an option.

Regarding documentation, @jaredpar's blog post is pretty complete, but obviously in no way official.

[sharwell]

@IanKemp I believe you misread the SO answer. When you pass those two properties to the build, it will generate an assembly info file containing the values from it. Here is an example of the properties specified in a manually-incremented file (AssemblyVersion defaults to the value of Version if not specified separately):

https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/f01be7a8262f146766af90138530ee0f21ddfba1/StyleCop.Analyzers/Directory.Build.props#L11-L13

When using these properties, you do not want wildcard versioning, which means determinism can be enabled.

[IanKemp]

@sharwell Thank you - this is what happens when I am sick... and when there isn't appropriate documentation. (Insert sound of dead horse beating.)

So then I guess the only remaining question is: why would you ever want to use in the `Version` properties, and is it worth updating the documentation and whatnot to handle that case in a nicer manner?

[sharwell]

why would you ever want to use in the Version properties

Aside from backwards compatibility (avoiding breaking projects that used it in the past), I am not aware of any reason.

[maxima120]

it has to be in the project properties UI.. whatever reason for using it or not using it..

[BoCoKeith]

Two thumbs up for adding a determinism checkbox to the project properties. Having to add a tags to the project file to enable auto-versioning is just not right.

At the least: how about adding a comment in the Assembly.cs templates that tells you what to do if you want to enable auto-versioning. Simple fix, no code change, less confusion.

[tmat]

Some doc improvements: https://github.com/dotnet/dotnet-api-docs/pull/9892