I developing a C# class library in Visual Studio, and I have been making use of XML Documentation Comments primarily for their integration with Intellisense. However, the bulk of comments has become quite cluttered, so now I am endeavoring to use the <include> tag, and an external XML document to reduce the clutter.
My issue is that when using the <include> tag Intellisense seems to not update with the information, not show any of the <summary> and <param> tags that I've assigned to some of my classes and methods.
For Example I could have a class 'Test' documented as shown:
/// <include file="docs.xml" path='extradoc/class[#name="Test"]/*' />
class Test { string foo = "bar"; }
And have docs.xml:
<?xml version="1.0" encoding="utf-8" ?>
<extradoc>
<class name="Test">
<summary>
Contains some Foo.
</summary>
</class>
</extradoc>
And upon build the output XML populates correctly:
<?xml version="1.0"?>
<doc>
<assembly>
<name>Example Program</name>
</assembly>
<members>
<member name="T:Example_Program.Program.Test">
<summary>
Contains some Foo.
</summary>
</member>
</members>
</doc>
The only issue is that, try as I might, this documentation will not appear in the intellisense boxes while appending my code. Is there some Visual Studio configuration setting I'm missing? I've scoured the msn documentation to no avail.
My issue is that when using the tag Intellisense seems to
not update with the information, not show any of the and
tags that I've assigned to some of my classes and methods.
1.Avoid that your issue is being not able to see summary in Intellisense in current project A.
You can get help from this document, this technology is used to provide better reading experience. So assuming you have the Test class in current priject A, when you see the content in VS code editor, you'll see something like:
It's expected behavior that you won't see that rich comments in project A any more cause they have been moved to docs.xml.
2.If you mean when you create a new Project B(or share the assembly to other developers), the Intellisense can't recognize your Test class.
Two possible causes:
1.The output xx.dll and xx.xml from project A are not in the same folder, so when you reference that xx.dll in your new project, Intellisense won't display the documentation comments.
2.I guess there's something wrong with your docs.xml file. (I can't find any official document which indicates this technology supports user-defined nodes like extradoc and class in docs.xml, I used these two nodes and the Intellisense did not work, after changing them to normal docs and members, it works now)
Try using docs.xml and include in this way:
<?xml version="1.0" encoding="utf-8" ?>
<docs>
<members name="MyTests">
<Test>
<summary>
This class is public, but do nothing
</summary>
<remarks>
Just write something here to indicate this is remarks.
</remarks>
</Test>
</members>
</docs>
and
/// <include file="docs.xml" path='docs/members[#name="MyTests"]/Test/*' />
public class Test { }
I suggest you use a public class to test... After that create a new project and reference that xx.dll, when calling Test class you can see the summary:
And if we F12 we can see detailed comments:
Hope it helps :)
I'm using StyleCop and want to suppress some warning which does not suit my style. I prefer to have solution for
1) in-line code suppressing
2) global setting suppressing
I've searched the internet but still not sure how to do the suppressing.
For method 1), They said to add the lines:
[assembly: SuppressMessage("Microsoft.Design",
"SA1202:All private methods must be placed after all public methods",
Scope = "namespace", Target = "Consus.Client.ClientVaultModule.Services.OnlineDetection")]
But they do not say where and which namespace to be used.
For method 2), they said to use GlobalSuppress file but it seems not easy to search for a how-to do it at the moment.
Please help.
[Edited]
In my case, I have the warning about SA1202: All private methods must be placed after all public methods which is bothering since I group my related codes into regions. I want to suppress those warning for just some certain methods.
Here's what you need:
[SuppressMessage("Microsoft.StyleCop.CSharp.OrderingRules", "SA1202:ElementsMustBeOrderedByAccess")]
An example of inline suppression would be similar to this - examine the namespaces in the code compared to the suppression
namespace Soapi
{
///<summary>
///</summary>
///<param name = "message"></param>
///<param name = "statusCode"></param>
///<param name = "innerException"></param>
[System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Globalization", "CA1305:SpecifyIFormatProvider", MessageId = "System.String.Format(System.String,System.Object,System.Object)")]
public ApiException(string message, ErrorCode statusCode, Exception innerException)
: base(String.Format("{0}\r\nStatusCode:{1}", message, statusCode), innerException)
{
this.statusCode = statusCode;
}
A global supression file is a file in the root of your project named GlobalSuppressions.cs and might look like this:
// This file is used by Code Analysis to maintain SuppressMessage
// attributes that are applied to this project.
// Project-level suppressions either have no target or are given
// a specific target and scoped to a namespace, type, member, etc.
//
// To add a suppression to this file, right-click the message in the
// Error List, point to "Suppress Message(s)", and click
// "In Project Suppression File".
// You do not need to add suppressions to this file manually.
[assembly: System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Globalization", "CA1305:SpecifyIFormatProvider", MessageId = "System.String.Format(System.String,System.Object,System.Object,System.Object)", Scope = "member", Target = "Soapi.ApiException.#.ctor(System.String,Soapi.ErrorCode,System.String,System.Exception)")]
And you can generate this code automatically by right-clicking on the warning.
Starting with StyleCop 4.3.2, it is possible to suppress the reporting of rule violations by adding suppression attributes within the source code.
Rule Suppressions
http://stylecop.soyuz5.com/Suppressions.html
but it says -
Global Suppressions
StyleCop does not support the notion of global suppressions or
file-level suppressions. Suppressions must be placed on a code
element.
If you've installed StyleCop, you can right-click your project and there will be a StyleCop option. Click this and you'll see you can prevent certain rules from even running against your project. Moreover, you can create a separate rules file to share between different projects. This means you can configure the rules once the way you want them and then share that configuration between all your projects.
For individual overrides, SuppressMessage is the way to go.
Go to Solution Explorer
Go to your project
Expand references
Expand Analyzers
Expand StyleCop.Analyzers
Right click on a particular rule which you want to disable at a global (project) level
Set Rule Set severity -> Select None
Read the admonition from Style Cop, looking for the alphanumeric code. In your case 'SA1202'. Then browse to the corresponding page on the Style Cop website. Change the URL as appropriate https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1202.md
Copy the line labelled 'How to Suppress Violations'. Paste the attribute above the class about which Style Cop moans
[SuppressMessage("StyleCop.CSharp.OrderingRules", "SA1202:ElementsMustBeOrderedByAccess", Justification = "Reviewed.")]
Cant you just remove the rule instead of soiling your code?
Same goes for FxCop...
1.
In your case, correct SuppressMessage attribute should like like the following:
[SuppressMessage("StyleCop.CSharp.OrderingRules", "SA1202:ElementsMustBeOrderedByAccess")]
private void SomeMethod()
{
}
Note that you can place it on any other element (e.g, on the class - then all similar violations in the entire class will be supressed).
I also agree that it's quite unobvious what to write in these fields.
Actually, the first one should be the fully qualified name of StyleCop analyser class and could be found from the source code (e.g. from here).
The second one should start with rule code, then colon and the name of the rule enumeration (luckily, it always looks like the rule name displayed in the Settings Editor, but with no whitespaces).
2.
Regarding suppressing rules "globally" - why don't just turn them off via Settings Editor? Settings files are inherited through the file system, so you could easily have one "main" settings file at the "top" of your folder structure, and some other files (holding the "difference" from main) with exceptions made for some projects, if you want so (like described here).
Good luck!
You can disable the rules you don't want in Settings.StyleCop file, which is in the project root folder.
You will need the namespace that contains the rule, which can be found here:
http://stylecop.soyuz5.com/StyleCop%20Rules.html
Settings.stylecop file code for your reference:
<StyleCopSettings Version="105">
<Analyzers>
<Analyzer AnalyzerId="StyleCop.CSharp.LayoutRules">
<Rules>
<Rule Name="ElementsMustBeSeparatedByBlankLine">
<RuleSettings>
<BooleanProperty Name="Enabled">False</BooleanProperty>
</RuleSettings>
</Rule>
</Rules>
<AnalyzerSettings />
</Analyzer>
</Analyzers>
</StyleCopSettings>
Alternatively you could move the code in regions into partial classes. Then the issue with the stylecop rule will go away.
In addition to the helpful answers already in place:
If you suppress a warning in the suppression file GlobalSuppressions.cs,
you can edit that [assembly: SuppressMessage(StyleCop...blabla line and entirely remove the Scope=... and Target=... tags. That makes the suppression global in the project.
The README.md for the StyleCop.Analyzers NuGet package used by Visual Studio 2015+ contains a link to the documentation for the rules. The documentation for each rule contains a "How to suppress violations" section. For the SA1202 rule, the options are:
[SuppressMessage("StyleCop.CSharp.OrderingRules", "SA1202:ElementsMustBeOrderedByAccess", Justification = "Reviewed.")]
and
#pragma warning disable SA1202 // ElementsMustBeOrderedByAccess
#pragma warning restore SA1202 // ElementsMustBeOrderedByAccess
in my uwp app I am using dynamic variables at many places, because the data is coming from the server backend api, so we want to keep it dynamic. it runs fine in Debug mode but I wanted to upload to store so I tried it on Release mode and it fails with following exception
system.reflection.missingmetadataexception
obviously this exception occurs, in one of my pages called "LoginPage.xaml.cs" at the first line where I am trying to use the dynamic data. following is the line which causes the exception.
ViewModel.backgroundURL = AppConfig.Login.background;
AppConfig here is a static object in a constants class. and its type is dynamic, I am succesfully get it from server API, but exception only occurs when I try to consume it in my app as you can see in the code line above.
after some research I found that using the following line in Default.rd.xml can solve this error I put the following line there.
<Namespace Name="bluebook.ViewModels" Seralize="All" />
as you can see I am putting this line in my directives tag as shown below.
<Directives xmlns="http://schemas.microsoft.com/netfx/2013/01/metadata">
<Application>
<!--
An Assembly element with Name="*Application*" applies to all assemblies in
the application package. The asterisks are not wildcards.
-->
<Assembly Name="*Application*" Dynamic="Required All" />
<!-- Add your application specific runtime directives here. -->
<Namespace Name="bluebook.ViewModels" Serialize="All" />
</Application>
</Directives>
I am trying to do the directives on ViewModels because the fields I am assigning to are in the ViewModel class. I also tried to do it on Views name space which has all the view classes like LoginPage and others, but in both cases the exception is still occuring, exactly at the same line.
Update 1
Exception Details
System.Reflection.MissingMetadataException: 'Reflection_InsufficientMetadata_NoHelpAvailable: EETypeRva:0x000a8990.
StackTrace : null
Source : null
Is "Serialize" misspelled in your directive file?
Try adding <Type Name="Microsoft.CSharp.RuntimeBinder.CSharpGetMemberBinder" Dynamic="Required All"/> to your Default.rd.xml.
(This answer may be relevant to you - answered by someone who works on .Net Native - Building with .NET Native tool chain causes error with missing property in dynamic object )
I'm new to monogame, and I'm trying to make a .spritefont file in order to draw string with the font I choose.
Strings with English characters can show well on the screen, but I wish to draw strings in multiple languages, like Japanese and Chinese.
So, I tried to load all characters in a Multi Language Font "Microsoft JhengHei".
The font's first character is !(U+0021) and the last one is ￮(U+FFEE).
But when I tried to compile the program, the compiler gave me an error:
.../Content/MyFont.spritefont : error : Importer 'FontDescriptionImporter' had unexpected failure!
System.Reflection.TargetInvocationException: Exception has been thrown by the target of an invocation. ---> System.ArgumentException: CharacterRegion.End must be greater than CharacterRegion.Start
at Microsoft.Xna.Framework.Content.Pipeline.Graphics.FontDescription.set_CharacterRegions(CharacterRegion[] value)
And when I changed the ￮ to 忮, MSBuild stucks and takes forever to proceed the content.
Code in MyFont.spritefont below:
<?xml version="1.0" encoding="utf-8"?>
<XnaContent xmlns:Graphics="Microsoft.Xna.Framework.Content.Pipeline.Graphics">
<Asset Type="Graphics:FontDescription">
<FontName>Microsoft JhengHei</FontName>
<Size>14</Size>
<Spacing>0</Spacing>
<UseKerning>true</UseKerning>
<Style>Regular</Style>
<CharacterRegions>
<CharacterRegion>
<Start>!</Start>
<End>￮</End>
</CharacterRegion>
</CharacterRegions>
</Asset>
</XnaContent>
I searched for the solution for a few days but in vain, any help is appreciated.
I was not able to reproduce the steps of the accepted answer from J3soon in Monogame 3.7.1.
However in Monogame 3.7.1, it is not longer necessary to use the Custom Content Pipeline because the pipeline tool now natively contains a LocalizedFontProcessor.
My steps were :
Set the .spritefont Processor to LocalizedFontProcessor in the pipeline tool
In the .spritefont, include the path to the resx file.
In the .spritefont, replace Asset Type="Graphics:FontDescription" with Asset Type="Graphics:LocalizedFontDescription"
Rebuild the Content
I would have thought step #1 would have done #3 behind the scenes but for me it was necessary to do this both in the pipeline tool and the .spritefont file.
spritefont file
<?xml version="1.0" encoding="utf-8"?>
<XnaContent xmlns:Graphics="Microsoft.Xna.Framework.Content.Pipeline.Graphics">
<Asset Type="Graphics:LocalizedFontDescription">
<FontName>Arial</FontName>
<Size>16</Size>
<Spacing>2</Spacing>
<UseKerning>true</UseKerning>
<Style>Regular</Style>
<CharacterRegions>
<CharacterRegion>
<Start> </Start>
<End>~</End>
</CharacterRegion>
</CharacterRegions>
<ResourceFiles>
<Resx>..\Strings.fr.resx</Resx>
</ResourceFiles>
</Asset>
</XnaContent>
Content file
#begin MyFont.spritefont
/importer:FontDescriptionImporter
/processor:LocalizedFontProcessor
/processorParam:PremultiplyAlpha=True
/processorParam:TextureFormat=Compressed
/build:MyFont.spritefont
Since processing all 65 thousand characters takes too much time. We should only process the characters we are using.
So the easiest way is to make a MonoGame Custom Content Pipeline and load the characters we are using by some .resx files.
It took me so much time searching for this solution. So I'll post how did I succeed, hope it can help someone who has the same question in the future.
Step-by-step Tutorial
Create a Class Library.
Reference the MonoGame.Framework.Content.Pipeline.Portable package using NuGet. (Make sure you checked the Include Prerelease checkbox )
Download the LocalizationSample here and unzip the file.
Under LocalizationPipeline\ copy LocalizedFontDescription.cs and LocalizedFontProcessor.cs into the class library
Build the class library so it outputs a LocalizationPipeline.dll file.
Open Myfont.spritefont and change its Asset Type to LocalizationPipeline.LocalizedFontDescription
Then add the resources <ResourceFiles><Resx>..\strings.resx</Resx></ResourceFiles> (these files should contain the string we want to draw)
Open Content.mgcb and reference to LocalizationPipeline.dll
Set the MyFont.spritefont's processor to LocalizedFontProcessor
ReBuild the project.
MyFont.spritefont
<?xml version="1.0" encoding="utf-8"?>
<XnaContent xmlns:Graphics="Microsoft.Xna.Framework.Content.Pipeline.Graphics">
<Asset Type="LocalizationPipeline.LocalizedFontDescription">
<FontName>Microsoft JhengHei</FontName>
<Size>14</Size>
<Spacing>0</Spacing>
<UseKerning>true</UseKerning>
<Style>Regular</Style>
<CharacterRegions>
<CharacterRegion>
<Start> </Start>
<End>~</End>
</CharacterRegion>
</CharacterRegions>
<ResourceFiles>
<Resx>..\strings.resx</Resx>
</ResourceFiles>
</Asset>
</XnaContent>
Content.mgcb
...
#-------------------------------- References --------------------------------#
/reference:..\LocalizationPipeline.dll
#---------------------------------- Content ---------------------------------#
...
#begin MyFont.spritefont
/importer:FontDescriptionImporter
/processor:LocalizedFontProcessor
/build:MyFont.spritefont
...
Sources
Part 1 of Creating custom content importers for the MonoGame Pipeline
How to: Create a Localized Game
LocalizationSample (Thanks to #Groo for giving me this link.)
I have a class like this one:
[System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Naming", "CA1709:IdentifiersShouldBeCasedCorrectly", MessageId = "Io")]
public void ParaQueFalleCalidadCodigoUnoIo_ReglaCA1709()
{
}
public void ParaQueFalleCalidadCodigoDosIo_ReglaCA1709()
{
}
I use a custom Ruleset file CustomRules.ruleset
<RuleSet Name="RulesNet" ToolsVersion="10.0">
<RuleHintPaths>
<Path>C:\Fxcop10.0\Rules</Path>
</RuleHintPaths>
<Rules AnalyzerId="Microsoft.Analyzers.ManagedCodeAnalysis" RuleNamespace="Microsoft.Rules.Managed">
<Rule Id="CA1709" Action="Warning" />
</Rules>
</RuleSet>
When I run VS2010 built in Code Analysis tool, I get this warning:
CA1709 : Microsoft.Naming : Correct the casing of 'Io' in member name
'_Default.ParaQueFalleCalidadCodigoDosIo_ReglaCA1709()' by changing it
to 'IO'.
Now, I can use this same rule set file CustomRules.ruleset in FxCopCmd.exe:
FxCopCmd.exe /gac /d:"C:\CompanyFramework\4.0.0.0" /f:"D:\TFS\Tests\WebApplication1\bin\WebApplication1.dll" /o:"resultsFxCop.xml" /ruleset:"=CustomRules.ruleset" /v
I get 2 errors (FixCategory Breaking, and Level Error)
CA1709 - Correct the casing of 'Io' in member name
'_Default.ParaQueFalleCalidadCodigoUnoIo_ReglaCA1709()' by changing it
to 'IO'.
CA1709 - Correct the casing of 'Io' in member name
'_Default.ParaQueFalleCalidadCodigoDosIo_ReglaCA1709()' by changing it
to 'IO'.
<Message Id="Io" TypeName="IdentifiersShouldBeCasedCorrectly" Category="Microsoft.Naming" CheckId="CA1709" Status="Active" Created="2013-02-05 10:24:01Z" FixCategory="Breaking">
<Issue Name="Member" Certainty="85" Level="Error" Path="D:\TFS\Tests\WebApplication1" File="Default.aspx.cs" Line="21">Correct the casing of 'Io' in member name '_Default.ParaQueFalleCalidadCodigoUnoIo_ReglaCA1709()' by changing it to 'IO'.</Issue>
</Message>
<Message Id="Io" TypeName="IdentifiersShouldBeCasedCorrectly" Category="Microsoft.Naming" CheckId="CA1709" Status="Active" Created="2013-02-05 10:24:01Z" FixCategory="Breaking">
<Issue Name="Member" Certainty="85" Level="Error" Path="D:\TFS\Tests\WebApplication1" File="Default.aspx.cs" Line="26">Correct the casing of 'Io' in member name '_Default.ParaQueFalleCalidadCodigoDosIo_ReglaCA1709()' by changing it to 'IO'.</Issue>
</Message>
In resultsFxcop.xml, I have seen CA1709: IdentifiersShouldBeCasedCorrectly rule:
<Rule TypeName="IdentifiersShouldBeCasedCorrectly" Category="Microsoft.Naming" CheckId="CA1709">
<Name>Identifiers should be cased correctly</Name>
<Description>Type, namespace, and... OMITED.</Description>
<Resolution Name="Member">Correct the casing of '{0}' in member name {1} by changing it to '{2}'.</Resolution>
<Owner />
<Url>http://msdn.microsoft.com/library/ms182240(VS.100).aspx</Url>
<Email>[none]</Email>
<MessageLevel Certainty="85">Error</MessageLevel>
<File Name="namingrules.dll" Version="10.0.0.0" />
</Rule>
MessageLevel for CA1709 rule:
<MessageLevel Certainty="85">Error</MessageLevel>
Two issues:
I get Errors but CA1709 rule Action is Warning
SuppressMessage is ignored using FxCopcmd.exe
Now, I modify CustomRules.ruleset and I execute FxCopcmd.exe again
<Rule Id="CA1709" Action="None" />
I get NO errors.
I modify CustomRules.ruleset and I execute FxCopcmd.exe again
<Rule Id="CA1709" Action="Ignore" />
I get the same 2 errors.
I need use FxCopCmd.exe and a custom ruleset.
Does SuppressMessage works for FxCopcmd.exe?
Why do I get errors if Action is Warning, using Fxcopcmd.exe?
What does MessageLevel Error for CA1709 rule mean? More priority than Rule Action "Warning"?
Any suggestions?
Update
http://social.msdn.microsoft.com/Forums/en/vstscode/thread/3f8931da-9a4d-47a6-b331-8b6b07aea8d6
http://social.msdn.microsoft.com/forums/en-US/vstscode/thread/3cb6c50c-7095-4551-a4e3-a3cbc7cb85be
For the default FxCop rules, there is no easy way to modify the message level,
MessageLevel is the importance of the message, e.g. if you had thousands of messages, it probably would be a good idea to start addressing the Critical (the exclamation mark) Errors first.
Certainty is the number the Rule writer assigns to each rule, it is the likelihood that a message leads to a code change. This number is built up based on feedback from domain experts & customers and how well the heuristic used in the rule is able to avoid false positives.
Fix Category: This indicates if the fix for a violation would be a binary breaking change if the code has previously shipped. e.g you have a library with a misspelling in it that you have already shipped to customers. You now start running FxCop on it and see the misspelling. FxCop will tell you this is a breaking change. If you fix the misspelling and ship a new version of your library to customers, they can't use the library without changing and recompiling their code. So you probably want to ignore the FxCop violation on this API. On the other hand, if you never shipped, it would be totally fine to fix the FxCop violation.
Does SuppressMessage works for FxCopcmd.exe?
Yes. You will need to compile with the CODE_ANALYSIS compilation symbol defined in order for your SuppressMessage attributes to be included in your assembly. Once they're in there, the FxCop engine will recognize them, regardless of the mechanism used to run the analysis.
Why I get errors if Action is Warning, using Fxcopcmd.exe?
The issue level written to the FxCop-produced report always uses the level specified by the rule author. When you run from within Visual Studio, the Visual Studio integration plug-in overrides this level with the one specified in the ruleset. When you run fxcopcmd.exe, the only difference between a configuring a rule as a warning vs an error is that detection of an error-level rule violation will cause fxcopcmd.exe to return a non-zero exit code, thereby allowing you to break an automated build.
If you would prefer that fxcopcmd.exe use your level overrides when generating its report, you may want to consider making a suggestion at http://visualstudio.uservoice.com/.