attributes

1. Introduction

I think one of the most important features of Resharper is on-the-fly code quality analysis. Basically, every time Resharper finds possible pitfall in code, it indicates this with appropriate warning. The most common warning is “Possible System.NullReferenceException”. You can easily reproduce it by writing this code

List<object> objlList = new List<object>( );
var result = objlList.SingleOrDefault( );
Console.WriteLine( result.GetHashCode( ) );

List<object> objlList = new List<object>( );

var result = objlList.SingleOrDefault( );

Console.WriteLine( result.GetHashCode( ) );

As you can see R# is able to figure out, that LINQ SingleOrDefault function can return null. However there is no warning if we try to do something like that

private static void DisplayHashCode()
{
    var result = Foo();
    Console.WriteLine( result.GetHashCode( ) );
}

private static object Foo()
{
    return null;
}

private static void DisplayHashCode()

{

var result = Foo();

Console.WriteLine( result.GetHashCode( ) );

}

private static object Foo()

{

return null;

}

So it got me thinking, how Resharper recognizes whether or whether not to show warnings. It turned out, that it uses annotation attributes, which describe behavior of functions, properties, classes and interfaces.

2. Source code annotations

In order to use these attributes we have to place them in our project. First of all, let’s create Annotation.cs file and then copy default implementation of annotations into this file. The default implementation can be found in Code annotation option (Resharper->Options->Code Inspections->Code Annotations) under the button “Copy default implementation to clipboard”.

From now on we can decorate our functions with e.g. CanBeNull attribute

private static void DisplayHashCode()
{
    var result = Foo();
    Console.WriteLine( result.GetHashCode( ) );
}
       
[CanBeNull]
private static object Foo()
{
    return null;
}

private static void DisplayHashCode()

{

var result = Foo();

Console.WriteLine( result.GetHashCode( ) );

}

[CanBeNull]

private static object Foo()

{

return null;

}

and we will get warning if necessary

Of course there are a lot more of attributes to use. My favorites are:

StringFormatMethodAttribute
PathReferenceAttribute
NotifyPropertyChangedInvocatorAttribute

3. External code annotations

In case we do not have access to source code, we still are able to use annotation attributes. However we have to define annotations in xml configuration file. Let’s say we want to decorate NHibernte’s SaveOrUpdate function with NotNullAttribute. First of all we have to create xml file with appropriate declaration (This is standard XML Document Comment file. You can read specification here and here.)

<assembly name="NHibernate">
    <member name="M:NHibernate.ISession.SaveOrUpdate(System.Object)">
        <parameter name="obj">
            <attribute ctor="M:JetBrains.Annotations.NotNullAttribute.#ctor" />
        </parameter>
    </member>
</assembly>

</parameter>

</member>

</assembly>

Having prepared configuration file, we need to place it in appropriate location in order for Resharper to use it. It can be stored in

[ReSharper install directory]\Bin\ExternalAnnotations\[Assembly name].xml
[ReSharper install directory]\Bin\ExternalAnnotations\[Assembly name][Any name].xml.

So in my case the location is

C:\Program Files (x86)\JetBrains\ReSharper\v8.1\Bin\ExternalAnnotations\NHibernateNHibernate.xml

1	C:\Program Files (x86)\JetBrains\ReSharper\v8.1\Bin\ExternalAnnotations\NHibernateNHibernate.xml

After restarting Visual Studio, Resharper should load the file and show warning messages.

4. Generating initial XML annotation files

Creating xml annotation file for large library is very tedious task, fortunately Resharper have a hidden feature which can help us with generating initial xml file. First of all we have to run Visual Studio with /ReSharper.Internal parameter. In this mode we have an access to undocumented/hidden features of Resharper. Now, in the “Resharper” menu there is one additional menu item – Internal, where You can find Annotator submenu in which resides Annotate item.

Now You can specify for which dll Resharper should generate xml annotation file.

and after a while You should get complete xml declaration.

Please bear in mind, that Annotator is not official R# feature, so there is no guarantee that generating annotation files will succeed. Source code for this post can be found here

1. Introduction

It is a common practice to validate function arguments before running actual code. Usually validation looks like that:

public  void Update(Car entity)
{
    if(entity ==null)
        throw new ArgumentNullException("entity");
}

public void Update(Car entity)

{

if(entity ==null)

throw new ArgumentNullException("entity");

}

There is nothing wrong with this code, however we have to repeat this piece of code in every function. Of course we could create some helper class for argument validation and call approperiate validation function before launching rest of the code

public static class ValidationHelper
{
    public static void CheckNotNull(object entity, string argumentName)
    {
        if (entity == null)
            throw new ArgumentNullException(argumentName);
    }
}

public  void Update(Car entity)
{
    ValidationHelper.CheckNotNull(entity, "entity");
    //rest of the code
}

public static class ValidationHelper

{

public static void CheckNotNull(object entity, string argumentName)

{

if (entity == null)

throw new ArgumentNullException(argumentName);

}

public void Update(Car entity)

{

ValidationHelper.CheckNotNull(entity, "entity");

//rest of the code

}

However I was searching for more universal way for argument validation. That is why, I decided to try function interceptors and attributes.

2. Creating validation attributes

Let’s start for creating base attribute

[AttributeUsage(AttributeTargets.Parameter)]
public abstract class ArgumentValidationAttribute : Attribute
{
    public abstract void ValidateArgument(object value, string argumentName);
}

[AttributeUsage(AttributeTargets.Parameter)]

public abstract class ArgumentValidationAttribute : Attribute

{

public abstract void ValidateArgument(object value, string argumentName);

}

In the next step let’s create specialized attribute for “not null” validation. This argument may look this way:

public class NotNullAttribute : ArgumentValidationAttribute
{
    public override void ValidateArgument(object value,string argumentName)
    {
        if (value == null)
            throw new ArgumentNullException(argumentName, string.Format("Value {0} can not be null", argumentName));
    }
}

public class NotNullAttribute : ArgumentValidationAttribute

{

public override void ValidateArgument(object value,string argumentName)

{

if (value == null)

throw new ArgumentNullException(argumentName, string.Format("Value {0} can not be null", argumentName));

}

3. Using IInterceptor interface

That was an easy part, now it’s necessary to somehow intercept function execution and run attribute validation.In .NET there is no build-in mechanism to do that,that is why I’ll use extension for Ninject – Ninject Interception. First of all we have to add to our project three dll’s

Ninject
Ninject.Extensions.Interception
Ninject.Extensions.Interception.LinFu

You can easily add them using NuGet. Having all necessary files added to solution,let’s create function interceptor – ValidaitionInterceptor.

public class ValidationInterceptor : IInterceptor
{
    public void Intercept(IInvocation invocation)
    {
        var parameters = invocation.Request.Method.GetParameters();
        for (int index = 0; index < parameters.Length; index++)
        {
            foreach (ArgumentValidationAttribute attr in parameters[index].GetCustomAttributes(typeof(ArgumentValidationAttribute), true))
                attr.ValidateArgument(invocation.Request.Arguments[index], parameters[index].Name);
        }
        invocation.Proceed();       
    }
}

public class ValidationInterceptor : IInterceptor

{

public void Intercept(IInvocation invocation)

{

var parameters = invocation.Request.Method.GetParameters();

for (int index = 0; index < parameters.Length; index++)

{

foreach (ArgumentValidationAttribute attr in parameters[index].GetCustomAttributes(typeof(ArgumentValidationAttribute), true))

attr.ValidateArgument(invocation.Request.Arguments[index], parameters[index].Name);

}

invocation.Proceed();

}

As You can see ValidationInterceptor implements interface IInterceptorwhich belongs to Ninject.Extensions.Interception. This interface has one method Intercept which is called before function from registered component is called. In this function I iterate over all function attributes of type ArgumentValidationAttribute and call ValidateArgument function. If validation passess function invocation.Proceed() is called, which continues execution of original function.

4. Example of usage

In order to take advantage of benefits of function interceptors, we have to resolve objects from Ninject container. First of all I’ll create some examplorary classes

public interface IRepository<T> where T:class
{
    List<T> GetAll();
    void Update([NotNull] T entity);
}

public class Car
{
    public int Id { get; set; }
    public string Model { get; set; }
}

public class CarRepository : IRepository<Car>
{
    public  List<Car> GetAll()
    {
        return null;
    }

    public  void Update(Car entity)
    {
            
    }
}

public interface IRepository<T> where T:class

{

List<T> GetAll();

void Update([NotNull] T entity);

}

public class Car

{

public int Id { get; set; }

public string Model { get; set; }

}

public class CarRepository : IRepository<Car>

{

public List<Car> GetAll()

{

return null;

}

public void Update(Car entity)

{

}

In the next step I’ll create simple wrapper for Ninject container and register CarRepository in Kernel

public static class IOCContainer
{
    private static readonly IKernel Kernel;
    static IOCContainer()
    {
        Kernel = new StandardKernel();
    }

    public static void Configure()
    {
        Kernel.Bind(typeof(IRepository<Car>)).To(typeof(CarRepository)).Intercept().With<ValidaitionInterceptor>();
    }

    public static T Get<T>()
    {
        return Kernel.Get<T>();
    }
}

public static class IOCContainer

{

private static readonly IKernel Kernel;

static IOCContainer()

{

Kernel = new StandardKernel();

}

public static void Configure()

{

Kernel.Bind(typeof(IRepository<Car>)).To(typeof(CarRepository)).Intercept().With<ValidaitionInterceptor>();

}

public static T Get<T>()

{

return Kernel.Get<T>();

}

Please, notice that registration of CarRepository was used with option Intercept().With(). Thanks to this configuration,everytime we call method from CarRepository, Intercept method from ValidaitionInterceptor will be called first. Now, it is time to use our repository,we could do that this way

class Program
{
    static void Main(string[] args)
    {
        IOCContainer.Configure();
        var carRepository = IOCContainer.Get<IRepository<Car>>();
        carRepository.Update(null);
    }
}

class Program

{

static void Main(string[] args)

{

IOCContainer.Configure();

var carRepository = IOCContainer.Get<IRepository<Car>>();

carRepository.Update(null);

}

Argument entity in method Update from interface IRepository was decorated with NotNull, that is why our validation mechanism should throw exception.

5. Validation of return value

Using IInterceptor we could go one step further and also validate return value of method. In order to do that, we have to slightly modify Intercept method in ValidaitionInterceptor class.

public class ValidaitionInterceptor : IInterceptor
{
    public void Intercept(IInvocation invocation)
    {
        var parameters = invocation.Request.Method.GetParameters();
        for (int index = 0; index < parameters.Length; index++)
        {
            foreach (ArgumentValidationAttribute attr in parameters[index].GetCustomAttributes(typeof(ArgumentValidationAttribute), true))
                attr.ValidateArgument(invocation.Request.Arguments[index], parameters[index].Name);
        }

        invocation.Proceed();

        foreach (ArgumentValidationAttribute attr in invocation.Request.Method.ReturnTypeCustomAttributes.GetCustomAttributes(typeof(ArgumentValidationAttribute), true))
        {
            attr.ValidateArgument(invocation.ReturnValue, "return value");
        }
    }
}

public class ValidaitionInterceptor : IInterceptor

{

public void Intercept(IInvocation invocation)

{

var parameters = invocation.Request.Method.GetParameters();

for (int index = 0; index < parameters.Length; index++)

{

foreach (ArgumentValidationAttribute attr in parameters[index].GetCustomAttributes(typeof(ArgumentValidationAttribute), true))

attr.ValidateArgument(invocation.Request.Arguments[index], parameters[index].Name);

}

invocation.Proceed();

foreach (ArgumentValidationAttribute attr in invocation.Request.Method.ReturnTypeCustomAttributes.GetCustomAttributes(typeof(ArgumentValidationAttribute), true))

{

attr.ValidateArgument(invocation.ReturnValue, "return value");

}

We also have to change attribute usage of ArgumentValidationAttribute to

[AttributeUsage(AttributeTargets.Parameter | AttributeTargets.ReturnValue)]

1	[AttributeUsage(AttributeTargets.Parameter \| AttributeTargets.ReturnValue)]

Now, we can decorate function GetAll with NotNullattribute

[return: NotNull]
List<T> GetAll();

1 2	[return: NotNull] List<T> GetAll();

Since this moment, everytime function GetAll returns null, the ArgumentNullException will be thrown.

6. Drawbacks

Unfortunately using attributes for argument validation have some drawbacks. First of all, argument validation is based on function interceptors, and as I mentioned before only function, which are in objects, which are resolved from IoC container can be intercepted. What is more, interceptors allow us to intercept only functions marked as virtual or inhirited from interface. Source code for this post can be found here

.NET BLOG

.NET, C# blog

Resharper – annotation attributes

1. Introduction

2. Source code annotations

3. External code annotations

4. Generating initial XML annotation files

Argument validation with attributes and Ninject interceptor

1. Introduction

2. Creating validation attributes

3. Using IInterceptor interface

4. Example of usage

5. Validation of return value

6. Drawbacks