5

I'm using a .Settings file in my Visual Studio 2008 project which auto-generates a Settings.Designer.cs file from the PublicSettingsSingleFileGenerator custom tool.

This works fine, but I also want to enable "Warnings as Error" in the compilation options, to force everyone to keep the XML comments up to date, but I don't know how to add comments to all of the elements within the auto-generated code.

The actual properties can have comments added by selecting the elements in the design view and adding a "Description" within the properties window. But there doesn't seem to be a way to do this for the class declaration, or the default instance property.

Steps to reproduce this problem are as follows

  1. Create a new project
  2. Add a Settings file to the project
  3. Set the "Access Modifier" of the setting file to Public
  4. Goto the project properties, Build section
  5. Set "Treat Warnings as Errors" to All
  6. Check the Output XML Documentation file option
  7. Build the Solution

and this is the code which is generated in the PublicSettingsSingleFileGenerator Settings.Designer.cs file 

namespace SettingsTest {

    [global::System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
    [global::System.CodeDom.Compiler.GeneratedCodeAttribute("Microsoft.VisualStudio.Editors.SettingsDesigner.SettingsSingleFileGenerator", "9.0.0.0")]
    public sealed partial class Settings1 : global::System.Configuration.ApplicationSettingsBase {

        private static Settings1 defaultInstance = ((Settings1)(global::System.Configuration.ApplicationSettingsBase.Synchronized(new Settings1())));

        public static Settings1 Default {
            get {
                return defaultInstance;
            }
        }
    }
}

Not sure if this extra info should be part of the question section, as it goes some way to pointing at an answer

According to this link the attributes applied to the class appear to be wrong.

http://blogs.msdn.com/b/codeanalysis/archive/2007/04/27/correct-usage-of-the-compilergeneratedattribute-and-the-generatedcodeattribute.aspx

"CompilerGenerateAttribute - This attribute is for compiler use only and indicates that a particular code element is compiler generated. This should never be used in source code whatsoever."

"GeneratedCodeAttribute - This attribute is for use by custom tools that generate code. It should only be applied to code that is re-generated over and over and should not be used by templates that the user is expected to modify. Nor should it be applied at the type level if the type being generated is a partial class. In this situation, it should be applied only against the individual members that are contained within the generated part of the type."

Update

I've raised a bug report for this on the Microsoft Connect site and will update, and accept an answer when we get some more information http://connect.microsoft.com/VisualStudio/feedback/details/634692/publicsettingssinglefilegenerator-code-fails-when-treat-warnings-as-errors-is-set-to-all-and-xml-documentation-is-on

J_men
  • 387
  • 1
  • 4
  • 14
  • What is the issue you are getting with treating warnings as errors? – Tim Lloyd Jan 04 '11 at 16:24
  • Sorry forgot to clarify, the compiler generates a warning whenever a public class/member does not have a XML comment header – J_men Jan 04 '11 at 16:31
  • How and why are you setting the Settings file to public? – Patrick McDonald Jan 05 '11 at 12:25
  • If you open the settings file in the designer view, there is a drop down box at the top of the grid, next to the "View Code" button (only in 2008). The default is internal, but I need the class to be public, as I want to be able to reference the class from another project. – J_men Jan 05 '11 at 13:27

4 Answers4

2

There's no good way to do this, you can't inject the #pragma warning disable in the auto-generated file. Also a problem with Winforms designer files btw. Project + Properties, Build tab, Suppress warnings = 1591. But that will disable the diagnostic also where you might want it turned on. A #pragma warning restore doesn't fix that.

Hans Passant
  • 922,412
  • 146
  • 1,693
  • 2,536
1

Unfortunately there are conflicting issues\settings here:

  • XML documentation generation will warn on all missing comments on public members.
  • You have "treat warnings as errors" turned on (a good thing).
  • Warnings are being raised regarding a class you cannot change i.e. the generated settings.

The result of this is that you have warnings being converted to compiler errors which you cannot fix. You cannot reliably add comments to the settings class manually as they will be lost next time the class is regenerated.

Consider placing your settings in a separate project and turning off XML documentation on that project.

Tim Lloyd
  • 37,954
  • 10
  • 100
  • 130
  • 1
    Thanks, I've amened the question now. Also using an extra project is a good idea, but I'm holding out for a cleaner solution at the moment, as it seems like quite a awkward way to solve a fairly simple problem. – J_men Jan 05 '11 at 11:45
0

See Documenting (XML) Application Settings in Visual Studio 2010

There's a description property for every setting and this will in turn create the XML comment in the generated code. Tested in VS2010 as working.

Community
  • 1
  • 1
Chris DaMour
  • 3,650
  • 28
  • 37
0

Settings is a partial class: create a second, empty part and comment it.

Kell
  • 3,252
  • 20
  • 19
  • Thanks, this idea works for the class declaration, but there is also a default instance (singleton) property. Is there any way to comment this as well? – J_men Jan 04 '11 at 16:55
  • I've had a bit of a look into this. According to http://blogs.msdn.com/b/codeanalysis/archive/2007/04/27/correct-usage-of-the-compilergeneratedattribute-and-the-generatedcodeattribute.aspx, you should not have to comment this class at all as the CompilerGeneratedAttribute on the class should prevent the warning being raised as an error. I've ried to duplicate your problem in VS2005 and VS2008 but in both IDEs I can compile with warnings as errors(all), xml documentation on, and no comments in the settings.Desiginer.cs file at all. – Kell Jan 04 '11 at 17:26
  • I'll update my question with steps to recreate the problem, as from your link I think that the tool is actual generating the wrong code – J_men Jan 05 '11 at 11:22
  • 1
    OK, based on this I would create a wrapper for the setting. Keep the setting internal and create a new XSettings class and make that class public. Give it an indexed property or a SettingByName method that returns the string value of the named setting. Add a HasSetting method to check for the existence of settings. That way you can comment it to your heart's content and change the underlying settings file without breaking the build. – Kell Jan 05 '11 at 17:33