ReSharper Help

Code Annotation Attributes

The JetBrains.Annotations framework provides the following attributes:

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 null sometimes, so the check for null is necessary before its usage.

Example

[CanBeNull] public object Test() { return null; } public void UseTest() { var p = Test(); var s = p.ToString(); // Warning: Possible 'System.NullReferenceException' }

For more information, see Value Analysis

NotNullAttribute

Indicates that the value of the marked element could never be null.

Example

[NotNull] public object Foo() { return null; // Warning: Possible 'null' assignment }

For more information, see Value Analysis

ItemNotNullAttribute

Indicates that a collection or an enumerable does not contain elements whose value is null.

Example

public void Foo([ItemNotNullA]List<Book> books) { foreach (var book in books) { if (book != null) // Warning: Expression is always true Console.WriteLine(book.ToString()); } }

For more information, see Value Analysis

ItemCanBeNullAttribute

Indicates that a collection or an enumerable can contain elements whose value is null.

Example

public void Foo([ItemCanBeNull]List<Book> books) { foreach (var book in books) { Console.WriteLine(book.ToString()); // Warning: Possible 'System.NullReferenceException' } }

For more information, see Value 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")] public void ShowError(string message, params object[] args) { /* do something */ } public 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 Defining Custom String Formatting Methods

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.

Example

public void 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 System.ComponentModel.INotifyPropertyChanged interface and this method is used to notify that some property value changed.

The method should be non-static and conform to one of the supported signatures:

  • NotifyChanged(string)
  • NotifyChanged(params string[])
  • NotifyChanged{T}(Expression{Func{T}})
  • NotifyChanged{T,U}(Expression{Func{T,U}})
  • SetProperty{T}(ref T, T, string)

Example

public class Foo : INotifyPropertyChanged { public event PropertyChangedEventHandler PropertyChanged; [NotifyPropertyChangedInvocator] protected virtual void NotifyChanged(string propertyName) { ... } private string _name; public string Name { get { return _name; } set { _name = value; NotifyChanged("LastName"); /* Warning */ } } }
Examples of generated notifications:
  • NotifyChanged("Property")
  • NotifyChanged(() => Property)
  • NotifyChanged((VM x) => x.Property)
  • SetProperty(ref myField, value, "Property")

For more information, see INotifyPropertyChanged Support

ContractAnnotationAttribute

Describes dependency between method input and output.

Syntax

Function Definition Table syntax:

  • FDT ::= FDTRow [;FDTRow]*
  • FDTRow ::= Input => Output | Output <= Input
  • Input ::= ParameterName: Value [, Input]*
  • Output ::= [ParameterName: Value]* {halt|stop|void|nothing|Value}
  • Value ::= true | false | null | notnull | canbenull
If method has single input parameter, it's name could be omitted.
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

  • [ContractAnnotation("=> halt")] public void TerminationMethod()
  • [ContractAnnotation("halt <= condition: false")] public void Assert(bool condition, string text) // regular assertion method
  • [ContractAnnotation("s:null => true")] public bool IsNullOrEmpty(string s) // string.IsNullOrEmpty()
  • // A method that returns null if the parameter is null, // and not null if the parameter is not null [ContractAnnotation("null => null; notnull => notnull")] public object Transform(object data)
  • [ContractAnnotation("s:null=>false; =>true,result:notnull; =>false, result:null")] public bool TryParse(string s, out Person result)

LocalizationRequiredAttribute

Indicates that marked element should be localized or not.

Example

[LocalizationRequiredAttribute(true)] public class Foo { private 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 Equals() should be used instead. However, using '==' or '!=' for comparison with null is always permitted.

Example

[CannotApplyEqualityOperator] class NoEquality { } class UsesNoEquality { public 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 public class ComponentAttribute : Attribute { } [Component] // ComponentAttribute requires implementing IComponent interface public 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 System.Diagnostics.Contracts.PureAttribute.

Example

[Pure] private int Multiply(int x, int y) { return x * y; } public void Foo() { const int a = 2, b = 2; Multiply(a, b); // Waring: Return value of pure method is not used }

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.

Example

In 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.

Example

Applying 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$ } }
Applying the attribute on a template method parameter:
[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); */ }

Members

Expression

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 System.Web.Mvc.Html.ChildActionExtensions.RenderAction(HtmlHelper, String).

AspMvcAreaAttribute

ASP.NET MVC attribute. Indicates that a parameter is an MVC area. Use this attribute for custom wrappers similar to System.Web.Mvc.Html.ChildActionExtensions.RenderAction(HtmlHelper, String).

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 System.Web.Mvc.Html.ChildActionExtensions.RenderAction(HtmlHelper, String, String).

AspMvcMasterAttribute

ASP.NET MVC attribute. Indicates that a parameter is an MVC Master. Use this attribute for custom wrappers similar to System.Web.Mvc.Controller.View(String, String).

AspMvcModelTypeAttribute

ASP.NET MVC attribute. Indicates that a parameter is an MVC model type. Use this attribute for custom wrappers similar to System.Web.Mvc.Controller.View(String, Object).

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 System.Web.Mvc.Html.RenderPartialExtensions.RenderPartial(HtmlHelper, String).

AspMvcSupressViewErrorAttribute

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 System.Web.Mvc.Html.DisplayExtensions.DisplayForModel(HtmlHelper, String).

AspMvcEditorTemplateAttribute

ASP.NET MVC attribute. Indicates that a parameter is an MVC editor template. Use this attribute for custom wrappers similar to System.Web.Mvc.Html.EditorExtensions.EditorForModel(HtmlHelper, String).

AspMvcTemplateAttribute

ASP.NET MVC attribute. Indicates that a parameter is an MVC template. Use this attribute for custom wrappers similar to System.ComponentModel.DataAnnotations.UIHintAttribute(System.String).

AspMvcViewAttribute

ASP.NET MVC attribute. If applied to a parameter, indicates that the parameter is an MVC view. If applied to a method, the MVC view name is calculated implicitly from the context. Use this attribute for custom wrappers similar to System.Web.Mvc.Controller.View(Object).

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 System.Web.WebPages.WebPageBase.RenderSection(String).

CollectionAccessAttribute

Indicates a collection class method and defines how its invocation affects content of the collection. Use CollectionAccessType to define the access type.

Using this attribute only makes sense if all collection methods aare marked with this attribute.

Example

public 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 an 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 the 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 (AssertionConditionType).

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.

XamlItemsControlAttribute

XAML attribute. Indicates the type that has ItemsSource property and should be treated as ItemsControl-derived type, to enable inner items DataContext type resolve.

XamlItemBindingOfItemsControlAttribute

XAML attibute. Indicates the property of some BindingBase-derived type, that is used to bind some item of ItemsControl-derived type. This annotation will enable the DataContext type resolve for XAML bindings for such properties.

Property should have the tree ancestor of the ItemsControl type or marked with the XamlItemsControlAttribute attribute.

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
ImplicitUseKindFlags

Specify the details of implicitly used symbol. The symbol must be marked with MeansImplicitUseAttribute or UsedImplicitlyAttribute.

Members

Access

Only entity marked with attribute considered to be used.

Assign

Indicates implicit assignment to a member.

InstantiatedWithFixedConstructorSignature

Indicates implicit instantiation of a type with fixed constructor signature. That means any unused constructor parameters won't be reported as such.

InstantiatedNoFixedConstructorSignature

Indicates implicit instantiation of a type.

ImplicitUseTargetFlags

Specify what is considered to be used implicitly when marked with the MeansImplicitUseAttribute or UsedImplicitlyAttribute.

Members

Members

Members of entity marked with attribute are considered used.

WithMembers

Entity marked with attribute and all its members considered used.

CollectionAccessType

Provides a value for the CollectionAccessAttribute to define how the collection class method invocation affects the content of the collection.

Members

None

Method does not use or modify content of the collection.

Read

Method only reads content of the collection but does not modify it.

ModifyExistingContent

Method can change content of the collection but does not add new elements.

UpdatedContent

Method can add new elements to the collection.

AssertionConditionType

Specifies assertion type for AssertionConditionAttribute. If the assertion method argument satisfies the condition, then the execution continues. Otherwise, execution is assumed to be halted.

Members

IS_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.

See Also

Last modified: 30 June 2015