Code Annotation Attributes
The JetBrains.Annotations
framework provides the following attributes:
- AspMvcActionAttribute
- AspMvcActionSelectorAttribute
- AspMvcAreaAttribute
- AspMvcControllerAttribute
- AspMvcDisplayTemplateAttribute
- AspMvcEditorTemplateAttribute
- AspMvcMasterAttribute
- AspMvcModelTypeAttribute
- AspMvcPartialViewAttribute
- AspMvcSuppressViewErrorAttribute
- AspMvcTemplateAttribute
- AspMvcViewAttribute
- AspMvcViewComponentAttribute
- AspMvcViewComponentTypeAttribute
- AspMvcViewComponentViewAttribute
- AssertionConditionAttribute
- AssertionMethodAttribute
- BaseTypeRequiredAttribute
- CanBeNullAttribute
- CannotApplyEqualityOperatorAttribute
- CollectionAccessAttribute
- ContractAnnotationAttribute
- InstantHandleAttribute
- InvokerParameterNameAttribute
- ItemCanBeNullAttribute
- ItemNotNullAttribute
- LinqTunnelAttribute
- LocalizationRequiredAttribute
- MacroAttribute
- MeansImplicitUseAttribute
- MustUseReturnValueAttribute
- NoEnumerationAttribute
- NoReorder
- NotifyPropertyChangedInvocatorAttribute
- NotNullAttribute
- PathReferenceAttribute
- ProvidesContextAttribute
- PublicAPIAttribute
- PureAttribute
- RazorSectionAttribute
- RegexPatternAttribute
- SourceTemplateAttribute
- StringFormatMethodAttribute
- TerminatesProgramAttribute
- UsedImplicitlyAttribute
- ValueProviderAttribute
- XamlItemBindingOfItemsControlAttribute
- XamlItemsControlAttribute
To use these attributes in your code, you need to reference JetBrains.Annotations
as described in the Annotations in Source Code section.
Annotation attributes
Annotation Attribute | Description |
---|---|
CanBeNullAttribute | Indicates that the value of the marked element could be Example[CanBeNull] object Test() => null;
void UseTest() {
var p = Test();
var s = p.ToString(); // Warning: Possible 'System.NullReferenceException'
} For more information, see Value and Nullability Analysis. |
NotNullAttribute | Indicates that the value of the marked element could never be Example[NotNull] object Foo() {
return null; // Warning: Possible 'null' assignment
} For more information, see Value and Nullability Analysis. |
ItemNotNullAttribute | Can be appplied to symbols of types derived from IEnumerable as well as to symbols of Task and Lazy classes to indicate that the value of a collection item, of the Task.Result property or of the Lazy.Value property can never be null. Examplepublic void Foo([ItemNotNull]List<string> books)
{
foreach (var book in books)
{
if (book != null) // Warning: Expression is always true
Console.WriteLine(book.ToUpper());
}
} For more information, see Value and Nullability Analysis. |
ItemCanBeNullAttribute | Can be appplied to symbols of types derived from IEnumerable as well as to symbols of Task and Lazy classes to indicate that the value of a collection item, of the Task.Result property or of the Lazy.Value property can be null. Examplepublic void Foo([ItemCanBeNull]List<string> books)
{
foreach (var book in books)
{
Console.WriteLine(book.ToUpper()); // Warning: Possible 'System.NullReferenceException'
}
} For more information, see Value and Nullability Analysis. |
StringFormatMethodAttribute | Indicates that the marked method builds string by format pattern and (optional) arguments. Parameter, which contains format string, should be given in constructor. The format string should be in System.String.Format(System.IFormatProvider,System.String,System.Object[])-like form. Example[StringFormatMethod("message")]
void ShowError(string message, params object[] args) { /* do something */ }
void Foo() {
ShowError("Failed: {0}"); // Warning: Non-existing argument in format string
} Members#ctor(System.String) Specifies which parameter of an annotated method should be treated as format-string For more information, see Code Analysis and Helpers for String Literals. |
ValueProviderAttribute | For a parameter that is expected to be one of the limited set of values. Specify fields of which type should be used as values for this parameter. |
InvokerParameterNameAttribute | Indicates that the function argument should be string literal and match one of the parameters of the caller function. For example, ReSharper annotates the parameter of System.ArgumentNullException. Examplevoid Foo(string param) {
if (param == null)
throw new ArgumentNullException("par"); // Warning: Cannot resolve symbol
} |
NotifyPropertyChangedInvocatorAttribute | Indicates that the method is contained in a type that implements The method should be non-static and conform to one of the supported signatures:
Examplepublic class Foo : INotifyPropertyChanged {
public event PropertyChangedEventHandler PropertyChanged;
[NotifyPropertyChangedInvocator]
protected virtual void NotifyChanged(string propertyName) { ... }
string _name;
public string Name {
get { return _name; }
set { _name = value; NotifyChanged("LastName"); /* Warning */ }
}
}
For more information, see INotifyPropertyChanged Support. |
ContractAnnotationAttribute | Describes dependency between method input and output. SyntaxFunction Definition Table syntax:
Using halt (or void /nothing , which is the same) for method output means that the methos doesn't return normally.canbenull annotation is only applicable for output parameters.You can use multiple [ContractAnnotation] for each FDT row, or use single attribute with rows separated by semicolon.Examples
For more information, see Contract Annotations. |
LocalizationRequiredAttribute | Indicates that marked element should be localized or not. Example[LocalizationRequiredAttribute(true)]
class Foo {
string str = "my string"; // Warning: Localizable string
} |
CannotApplyEqualityOperatorAttribute | Indicates that the value of the marked type (or its derivatives) cannot be compared using '==' or '!=' operators and Example[CannotApplyEqualityOperator]
class NoEquality { }
class UsesNoEquality {
void Test() {
var ca1 = new NoEquality();
var ca2 = new NoEquality();
if (ca1 != null) { // OK
bool condition = ca1 == ca2; // Warning
}
}
} |
BaseTypeRequiredAttribute | When applied to a target attribute, specifies a requirement for any type marked with the target attribute to implement or inherit specific type or types. Example[BaseTypeRequired(typeof(IComponent)] // Specify requirement
class ComponentAttribute : Attribute { }
[Component] // ComponentAttribute requires implementing IComponent interface
class MyComponent : IComponent { } |
UsedImplicitlyAttribute | Indicates that the marked symbol is used implicitly (e.g. via reflection, in external library), so this symbol will not be marked as unused (as well as by other usage inspections). |
MeansImplicitUseAttribute | Should be used on attributes and causes ReSharper to not mark symbols marked with such attributes as unused (as well as by other usage inspections) |
PublicAPIAttribute | This attribute is intended to mark publicly available API which should not be removed and so is treated as used. |
InstantHandleAttribute | Tells code analysis engine if the parameter is completely handled when the invoked method is on stack. If the parameter is a delegate, indicates that delegate is executed while the method is executed. If the parameter is an enumerable, indicates that it is enumerated while the method is executed. |
PureAttribute | Indicates that a method does not make any observable state changes. The same as Example[Pure] int Multiply(int x, int y) => x * y;
void M() {
Multiply(123, 42); // Waring: Return value of pure method is not used
} |
MustUseReturnValueAttribute | Indicates that the return value of method invocation must be used. Methods decorated with this attribute (in contrast to pure methods) might change state, but make no sense without using their return value. Similarly to the [PureAttribute], this attribute will help you detect usages of the method when the return value in not used. Additionally, you can optionally specify a custom message, which will be used when showing warnings, e.g. |
ProvidesContextAttribute | Indicates the type member or parameter of some type, that should be used instead of all other ways to get the value that type. This annotation is useful when you have some "context" value evaluated and stored somewhere, meaning that all other ways to get this value must be consolidated with existing one. Exampleclass Foo {
[ProvidesContext] IBarService _barService = ...;
void ProcessNode(INode node) {
DoSomething(node, node.GetGlobalServices().Bar);
// ^ Warning: use value of '_barService' field
}
} |
PathReferenceAttribute | Indicates that a parameter is a path to a file or a folder within a web project. Path can be relative or absolute, starting from web root (~). |
SourceTemplateAttribute | An extension method marked with this attribute is processed by ReSharper code completion as a 'Source Template'. When extension method is completed over some expression, it's source code is automatically expanded like a template at call site. Template method body can contain valid source code and/or special comments starting with '$'. Text inside these comments is added as source code when the template is applied. Template parameters can be used either as additional method parameters or as identifiers wrapped in two '$' signs. Use the MacroAttribute attribute to specify macros for parameters. ExampleIn this example, the 'forEach' method is a source template available over all values of enumerable types, producing ordinary C# 'foreach' statement and placing caret inside block: [SourceTemplate]
public static void forEach<T>(this IEnumerable<T> xs) {
foreach (var x in xs) {
//$ $END$
}
} For more information, see Source Templates. |
MacroAttribute | Allows specifying a macro for a parameter of a SourceTemplateAttribute. You can apply the attribute on the whole method or on any of its additional parameters. The macro expression is defined in the Expression property. When applied on a method, the target template parameter is defined in the Target property. To apply the macro silently for the parameter, set the Editable property value = -1. ExampleApplying the attribute on a source template method: [SourceTemplate, Macro(Target = "item", Expression = "suggestVariableName()")]
public static void forEach<T>(this IEnumerable<T> collection) {
foreach (var item in collection) {
//$ $END$
}
} [SourceTemplate]
public static void something(this Entity x, [Macro(Expression = "guid()", Editable = -1)] string newguid) {
/*$ var $x$Id = "$newguid$" + x.ToString();
x.DoSomething($x$Id); */
} MembersExpression Allows specifying a macro that will be executed for a SourceTemplateAttribute parameter when the template is expanded. Editable Allows specifying which occurrence of the target parameter becomes editable when the template is deployed. If the target parameter is used several times in the template, only one occurrence becomes editable; other occurrences are changed synchronously. To specify the zero-based index of the editable occurrence, use values >= 0. To make the parameter non-editable when the template is expanded, use -1. >Target Identifies the target parameter of a SourceTemplateAttribute if the MacroAttribute is applied on a template method. For more information, see Source Templates. |
AspMvcActionAttribute | ASP.NET MVC attribute. If applied to a parameter, indicates that the parameter is an MVC action. If applied to a method, the MVC action name is calculated implicitly from the context. Use this attribute for custom wrappers similar to |
AspMvcAreaAttribute | ASP.NET MVC attribute. Indicates that a parameter is an MVC area. Use this attribute for custom wrappers similar to |
AspMvcControllerAttribute | ASP.NET MVC attribute. If applied to a parameter, indicates that the parameter is an MVC controller. If applied to a method, the MVC controller name is calculated implicitly from the context. Use this attribute for custom wrappers similar to |
AspMvcMasterAttribute | ASP.NET MVC attribute. Indicates that a parameter is an MVC Master. Use this attribute for custom wrappers similar to |
AspMvcModelTypeAttribute | ASP.NET MVC attribute. Indicates that a parameter is an MVC model type. Use this attribute for custom wrappers similar to |
AspMvcPartialViewAttribute | ASP.NET MVC attribute. If applied to a parameter, indicates that the parameter is an MVC partial view. If applied to a method, the MVC partial view name is calculated implicitly from the context. Use this attribute for custom wrappers similar to |
AspMvcSuppressViewErrorAttribute | ASP.NET MVC attribute. Allows disabling inspections for MVC views within a class or a method. |
AspMvcDisplayTemplateAttribute | ASP.NET MVC attribute. Indicates that a parameter is an MVC display template. Use this attribute for custom wrappers similar to |
AspMvcEditorTemplateAttribute | ASP.NET MVC attribute. Indicates that a parameter is an MVC editor template. Use this attribute for custom wrappers similar to |
AspMvcTemplateAttribute | ASP.NET MVC attribute. Indicates that a parameter is an MVC template. Use this attribute for custom wrappers similar to |
AspMvcViewAttribute | ASP.NET MVC attribute. If applied to a parameter, indicates that the parameter is an MVC view component. If applied to a method, the MVC view name is calculated implicitly from the context. Use this attribute for custom wrappers similar to |
AspMvcViewComponentTypeAttribute | ASP.NET MVC attribute. If applied to a parameter, indicates that the parameter is an MVC view component type. |
AspMvcViewComponentAttribute | ASP.NET MVC attribute. If applied to a parameter, indicates that the parameter is an MVC view component name. |
AspMvcViewComponentViewAttribute | ASP.NET MVC attribute. If applied to a parameter, indicates that the parameter is an MVC view component view. If applied to a method, the MVC view component view name is default. |
AspMvcActionSelectorAttribute | ASP.NET MVC attribute. When applied to a parameter of an attribute, indicates that this parameter is an MVC action name. Example[ActionName("Foo")]
public ActionResult Login(string returnUrl) {
ViewBag.ReturnUrl = Url.Action("Foo"); // OK
return RedirectToAction("Bar"); // Error: Cannot resolve action
} |
RazorSectionAttribute | Razor attribute. Indicates that a parameter or a method is a Razor section. Use this attribute for custom wrappers similar to |
CollectionAccessAttribute | Indicates how method, constructor invocation or property access over collection type affects content of the collection. Use Using this attribute only makes sense if all collection methods are marked with this attribute. Examplepublic class MyStringCollection : List<string>
{
[CollectionAccess(CollectionAccessType.Read)]
public string GetFirstString()
{
return this.ElementAt(0);
}
}
class Test
{
public void Foo()
{
// Warning: Contents of the collection is never updated
var col = new MyStringCollection();
string x = col.GetFirstString();
}
} |
AssertionMethodAttribute | Indicates that the marked method is assertion method, i.e. it halts control flow if one of the conditions is satisfied. To set the condition, mark one of the parameters with AssertionConditionAttribute attribute. |
AssertionConditionAttribute | Indicates the condition parameter of the assertion method. The method itself should be marked by AssertionMethodAttribute attribute. The mandatory argument of the attribute is the assertion type. |
TerminatesProgramAttribute | Indicates that the marked method unconditionally terminates control flow execution. For example, it could unconditionally throw exception. |
LinqTunnelAttribute | Indicates that method is pure LINQ method, with postponed enumeration (like Enumerable.Select,.Where). This annotation allows inference of [InstantHandle] annotation for parameters of delegate type by analyzing LINQ method chains. |
NoEnumerationAttribute | Indicates that IEnumerable, passed as parameter, is not enumerated. |
RegexPatternAttribute | Indicates that parameter is regular expression pattern. For more information, see Regular Expressions Assistance. |
XamlItemsControlAttribute | XAML attribute. Indicates the type that has |
XamlItemBindingOfItemsControlAttribute | XAML attribute. Indicates the property of some Property should have the tree ancestor of the |
NoReorder | Prevents the Member Reordering feature from tossing members of the marked class. The attribute must be mentioned in your member reordering patterns For more information, see File and Type Layout. |
Helper types
Helper Types | Description |
---|---|
ImplicitUseTargetFlags | Specify what is considered used implicitly when marked with MeansImplicitUseAttribute or UsedImplicitlyAttribute. MembersMembers Members of entity marked with attribute are considered used. WithMembers Entity marked with attribute and all its members considered used. |
AssertionConditionType | Specifies assertion type. If the assertion method argument satisfies the condition, then the execution continues. Otherwise, execution is assumed to be halted. MembersIS_TRUE Marked parameter should be evaluated to true. IS_FALSE Marked parameter should be evaluated to false. IS_NULL Marked parameter should be evaluated to null value. IS_NOT_NULL Marked parameter should be evaluated to not null value. |