WindowsAppSDK
WindowsAppSDK copied to clipboard
microsoft
WindowsAppSDK-VersionInfo.cs and MddBootstrapAutoInitializer.cs cause warnings in analyzers
Describe the bug
Setting <GenerateDocumentationFile>True</GenerateDocumentationFile> in the project causes the following warnings to appear:
Another issue is reported here: DotNetAnalyzers/StyleCopAnalyzers/#3441
Steps to reproduce the bug
1.) Create a new WinUI 3 app with the template: Blank App, Packaged (WinUI 3 in Desktop) 2.) Enable documentation generation 3.) Build the app
Expected behavior
Warnings from nuget packages should not appear in any project that uses them.
Screenshots
No response
NuGet package version
1.0.0
Packaging type
Packaged (MSIX), Unpackaged
Windows version
Windows 10 version 2004 (19041, May 2020 Update)
IDE
Visual Studio 2022
Additional context
No response
In version 1.1.0-preview2 I don't get warnings but I do get several messages. I think this is caused by me having many of my VS code style settings set to "Suggestion" instead of "Refactoring Only". Is there a way to exclude this file from being checked against the VS code style settings (ie. Tools | options | Text Editor | C# | Code Style)
@DrusTheAxe It appears that there are additional StyleCop warnings that aren't covered by #2533; is that expected?
I did some digging...
Workaround here => https://github.com/dotnet/roslyn/issues/53729#issuecomment-850016824
Official word is it's a feature => https://github.com/dotnet/roslyn/issues/53729#issuecomment-879400025
Closing because this behavior is "By Design" and I don't really see us changing it here. The compiler itself has very little understanding of generated code in terms of how it handles diagnostics. That is true for the types of files that we register as generated as well as the behavior we tweak for those files (think it's pretty much just nullable diagnostics at this point).
The solution here is to either generate the correct code or to disable the warning in editorconfig for that pattern of files (as you showed in the sample above)
Another discussion with the full menu of options => https://stackoverflow.com/questions/7982525/visual-studio-disabling-missing-xml-comment-warning
To summarise, the ways around the warning would be to:
- Suppress the warning by changing the project Properties > Build > Errors and warnings > Suppress warnings by entering 1591
- Add the XML documentation tags (GhostDoc can be quite handy for that)
- Suppress the warning via compiler options Uncheck the "XML documentation file" checkbox in project Properties > Build > Output
- Add #pragma warning disable 1591 at the top of the respective file and #pragma warning restore 1591 at the bottom
and a little later in that thread a C# specific answer which looks most promising
You can also modify your project's .csproj file to include a <noWarn>1591</noWarn> tag inside of the first <PropertyGroup>. Originally from Alexandru Bucur's Article Here
... ...1591
@DefaultRyan is it possible to declare that <PropertyGroup> in one of our nuget's .props to address this?
We do e.g. https://docs.microsoft.com/en-us/windows/apps/api-reference/cs-bootstrapper-apis/cs-bootstrapper-apis-constants.
This isn't about documenting our stuff, but a matter of how, or more precisely, where.
Is it just the warning noise that's an issue?
Does having doccomments in source bring any additional value (or issues)?
Just for files like MddBootstrapAutoInitialize.cs that are compiled into your binaries or others as well e.g. WinAPI APIs available to C# developers via C#/WinRT like `Microsoft.Windows.ApplicationModel.DynamicDependency'?
Imho it is noise. Noise that should not be there as i as developer have no control over those files. I should not have to do anything to work around those warnings.
Imho it is noise.
Gotcha. Thanks for the input.
I should not have to do anything to work around those warnings.
No disagreement, just trying to figure out the needs and best ways to squash the issue. I have a simple fix for the surface issue and we're discussing if a bigger change is warranted for the larger picture. I've teed up a patch for main and will bring it for 1.1-servicing consideration for our next servicing update.
Developing .NET MAUI app with .NET 7.0, I can still see some warnings from WindowsAppSDK-VersionInfo.cs from time to time. Is it just me or can you see it too?
I can see it too, also on MAUI.
This file really needs to start with:
/// <auto-generated>
Also, I'm not sure, but I suspect that it is related to setting the property GenerateDocumentationFile to true, and could likely be fixed by setting it to false. Setting it to true probably isn't really necessary unless you are building a library for public consumption.
But this is clearly a bug.
WindowsAppSDK-VersionInfo.cs was missed in the pass previously fixing this. in other files.
That's generated out of another repo so I'll cook a fix over there. Thanks for reporting this.
I'm still seeing this. Maybe because <auto-generated> isn't on the very first line?
Tagging it with the GeneratedCodeAttribute may also fix it