CA2208: Instantiate argument exceptions correctly

Cause

When a method has a parameter, and it throws an exception type that is, or derives from, System.ArgumentException, it is expected to call a constructor accepting a paramName parameter correctly. Possible causes include the following situations:

A call is made to the default (parameterless) constructor of an exception type that is, or derives from, System.ArgumentException that also has a constructor that accepts a paramName parameter.
An incorrect string argument is passed to a parameterized constructor of an exception type that is, or derives from, System.ArgumentException. For example, the paramName argument doesn't match the name of one of the method's parameters.
A parameter name is passed for the message argument of the constructor of an exception type that is, or derives from, System.ArgumentException.

Rule description

Instead of calling the default constructor, call one of the constructor overloads that allows a more meaningful exception message to be provided. The exception message should target the developer and clearly explain the error condition and how to correct or avoid the exception.

The signatures of the one and two string constructors of System.ArgumentException and its derived types are not consistent with respect to the position message and paramName parameters. Make sure these constructors are called with the correct string arguments. The signatures are as follows:

How to fix violations

To fix a violation of this rule, call a constructor that takes a message, a parameter name, or both, and make sure the arguments are proper for the type of System.ArgumentException being called.

When to suppress warnings

It's safe to suppress a warning from this rule only if a parameterized constructor is called with the correct string arguments.

Suppress a warning

If you just want to suppress a single violation, add preprocessor directives to your source file to disable and then re-enable the rule.

csharp

#pragma warning disable CA2208
// The code that's violating the rule is on this line.
#pragma warning restore CA2208

To disable the rule for a file, folder, or project, set its severity to none in the configuration file.

ini

[*.{cs,vb}]
dotnet_diagnostic.CA2208.severity = none

For more information, see How to suppress code analysis warnings.

Configure code to analyze

Use the following option to configure which parts of your codebase to run this rule on.

Include specific API surfaces

You can configure this option for just this rule, for all rules it applies to, or for all rules in this category (Design) that it applies to. For more information, see Code quality rule configuration options.

Include specific API surfaces

You can configure which parts of your codebase to run this rule on, based on their accessibility, by setting the api_surface option. For example, to specify that the rule should run only against the non-public API surface, add the following key-value pair to an .editorconfig file in your project:

ini

dotnet_code_quality.CAXXXX.api_surface = private, internal

By default, the CA2208 rule applies to all API surfaces (public, internal, and private).

Example

The following code shows a constructor that incorrectly instantiates an instance of System.ArgumentNullException.

sample · csharpdocs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/ca2208.cssnippet1

csharp

using System;

namespace ca2208
{
#pragma warning disable CA2208 // Instantiate argument exceptions correctly
    //<snippet1>
    public class Book
    {
        public Book(string title)
        {
            Title = title ??
                throw new ArgumentNullException("All books must have a title.", nameof(title));
        }

        public string Title { get; }
    }
    //</snippet1>
#pragma warning restore CA2208 // Instantiate argument exceptions correctly
}

namespace ca2208_2
{
    //<snippet2>
    public class Book
    {
        public Book(string title)
        {
            Title = title ??
                throw new ArgumentNullException(nameof(title), "All books must have a title.");
        }

        public string Title { get; }
    }
    //</snippet2>
}

namespace ca2208_3
{
#pragma warning disable CA2208 // Instantiate argument exceptions correctly
    //<snippet3>
    public class Product
    {
        public string? Description { get; set; }
        public string Name { get; set; } = string.Empty;
    }

    public class Example
    {
        // Violates CA2208: 'description' is not a parameter of this method.
        public void ProcessProduct(Product product)
        {
            string? description = product.Description;
            if (description is null)
            {
                throw new ArgumentNullException(nameof(description), $"Product named {product.Name} had no description!");
            }
            // Process description...
        }
    }
    //</snippet3>
#pragma warning restore CA2208 // Instantiate argument exceptions correctly
}

namespace ca2208_4
{
    //<snippet4>
    public class Product
    {
        public string? Description { get; set; }
        public string Name { get; set; } = string.Empty;
    }

    public class Example
    {
        // Fixed: Use InvalidOperationException for invalid object state.
        public void ProcessProduct(Product product)
        {
            string? description = product.Description;
            if (description is null)
            {
                throw new InvalidOperationException($"Product named {product.Name} had no description!");
            }
            // Process description...
        }
    }
    //</snippet4>
}

sample · vbdocs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca2208-instantiate-argument-exceptions-correctly_1.vbsnippet1

Imports System

Namespace ca2208
#Disable Warning CA2208 ' Instantiate argument exceptions correctly
    '<snippet1>
    Public Class Book

        Private ReadOnly _Title As String

        Public Sub New(ByVal title As String)
            ' Violates this rule (constructor arguments are switched)            
            If (title Is Nothing) Then
                Throw New ArgumentNullException("title cannot be a null reference (Nothing in Visual Basic)", "title")
            End If
            _Title = title
        End Sub

        Public ReadOnly Property Title()
            Get
                Return _Title
            End Get
        End Property

    End Class
    '</snippet1>
#Enable Warning CA2208 ' Instantiate argument exceptions correctly

End Namespace

Namespace ca2208_2
    '<snippet2>
    Public Class Book

        Private ReadOnly _Title As String

        Public Sub New(ByVal title As String)
            If (title Is Nothing) Then
                Throw New ArgumentNullException("title", "title cannot be a null reference (Nothing in Visual Basic)")
            End If

            _Title = title
        End Sub

        Public ReadOnly Property Title()
            Get
                Return _Title
            End Get
        End Property

    End Class
    '</snippet2>

End Namespace

Namespace ca2208_3
#Disable Warning CA2208 ' Instantiate argument exceptions correctly
    '<snippet3>
    Public Class Product
        Public Property Description As String
        Public Property Name As String = String.Empty
    End Class

    Public Class Example
        ' Violates CA2208: 'description' is not a parameter of this method.
        Public Sub ProcessProduct(ByVal product As Product)
            Dim description As String = product.Description
            If description Is Nothing Then
                Throw New ArgumentNullException(NameOf(description), $"Product named {product.Name} had no description!")
            End If
            ' Process description...
        End Sub
    End Class
    '</snippet3>
#Enable Warning CA2208 ' Instantiate argument exceptions correctly

End Namespace

Namespace ca2208_4
    '<snippet4>
    Public Class Product
        Public Property Description As String
        Public Property Name As String = String.Empty
    End Class

    Public Class Example
        ' Fixed: Use InvalidOperationException for invalid object state.
        Public Sub ProcessProduct(ByVal product As Product)
            Dim description As String = product.Description
            If description Is Nothing Then
                Throw New InvalidOperationException($"Product named {product.Name} had no description!")
            End If
            ' Process description...
        End Sub
    End Class
    '</snippet4>

End Namespace

The following code fixes the previous violation by switching the constructor arguments.

sample · csharpdocs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/ca2208.cssnippet2

csharp

using System;

namespace ca2208
{
#pragma warning disable CA2208 // Instantiate argument exceptions correctly
    //<snippet1>
    public class Book
    {
        public Book(string title)
        {
            Title = title ??
                throw new ArgumentNullException("All books must have a title.", nameof(title));
        }

        public string Title { get; }
    }
    //</snippet1>
#pragma warning restore CA2208 // Instantiate argument exceptions correctly
}

namespace ca2208_2
{
    //<snippet2>
    public class Book
    {
        public Book(string title)
        {
            Title = title ??
                throw new ArgumentNullException(nameof(title), "All books must have a title.");
        }

        public string Title { get; }
    }
    //</snippet2>
}

namespace ca2208_3
{
#pragma warning disable CA2208 // Instantiate argument exceptions correctly
    //<snippet3>
    public class Product
    {
        public string? Description { get; set; }
        public string Name { get; set; } = string.Empty;
    }

    public class Example
    {
        // Violates CA2208: 'description' is not a parameter of this method.
        public void ProcessProduct(Product product)
        {
            string? description = product.Description;
            if (description is null)
            {
                throw new ArgumentNullException(nameof(description), $"Product named {product.Name} had no description!");
            }
            // Process description...
        }
    }
    //</snippet3>
#pragma warning restore CA2208 // Instantiate argument exceptions correctly
}

namespace ca2208_4
{
    //<snippet4>
    public class Product
    {
        public string? Description { get; set; }
        public string Name { get; set; } = string.Empty;
    }

    public class Example
    {
        // Fixed: Use InvalidOperationException for invalid object state.
        public void ProcessProduct(Product product)
        {
            string? description = product.Description;
            if (description is null)
            {
                throw new InvalidOperationException($"Product named {product.Name} had no description!");
            }
            // Process description...
        }
    }
    //</snippet4>
}

sample · vbdocs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca2208-instantiate-argument-exceptions-correctly_1.vbsnippet2

Imports System

Namespace ca2208
#Disable Warning CA2208 ' Instantiate argument exceptions correctly
    '<snippet1>
    Public Class Book

        Private ReadOnly _Title As String

        Public Sub New(ByVal title As String)
            ' Violates this rule (constructor arguments are switched)            
            If (title Is Nothing) Then
                Throw New ArgumentNullException("title cannot be a null reference (Nothing in Visual Basic)", "title")
            End If
            _Title = title
        End Sub

        Public ReadOnly Property Title()
            Get
                Return _Title
            End Get
        End Property

    End Class
    '</snippet1>
#Enable Warning CA2208 ' Instantiate argument exceptions correctly

End Namespace

Namespace ca2208_2
    '<snippet2>
    Public Class Book

        Private ReadOnly _Title As String

        Public Sub New(ByVal title As String)
            If (title Is Nothing) Then
                Throw New ArgumentNullException("title", "title cannot be a null reference (Nothing in Visual Basic)")
            End If

            _Title = title
        End Sub

        Public ReadOnly Property Title()
            Get
                Return _Title
            End Get
        End Property

    End Class
    '</snippet2>

End Namespace

Namespace ca2208_3
#Disable Warning CA2208 ' Instantiate argument exceptions correctly
    '<snippet3>
    Public Class Product
        Public Property Description As String
        Public Property Name As String = String.Empty
    End Class

    Public Class Example
        ' Violates CA2208: 'description' is not a parameter of this method.
        Public Sub ProcessProduct(ByVal product As Product)
            Dim description As String = product.Description
            If description Is Nothing Then
                Throw New ArgumentNullException(NameOf(description), $"Product named {product.Name} had no description!")
            End If
            ' Process description...
        End Sub
    End Class
    '</snippet3>
#Enable Warning CA2208 ' Instantiate argument exceptions correctly

End Namespace

Namespace ca2208_4
    '<snippet4>
    Public Class Product
        Public Property Description As String
        Public Property Name As String = String.Empty
    End Class

    Public Class Example
        ' Fixed: Use InvalidOperationException for invalid object state.
        Public Sub ProcessProduct(ByVal product As Product)
            Dim description As String = product.Description
            If description Is Nothing Then
                Throw New InvalidOperationException($"Product named {product.Name} had no description!")
            End If
            ' Process description...
        End Sub
    End Class
    '</snippet4>

End Namespace

The following code shows a method that incorrectly throws System.ArgumentNullException with a paramName that doesn't match any of the method's parameters. The rule fires because description is a local variable, not a method parameter.

sample · csharpdocs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/ca2208.cssnippet3

csharp

using System;

namespace ca2208
{
#pragma warning disable CA2208 // Instantiate argument exceptions correctly
    //<snippet1>
    public class Book
    {
        public Book(string title)
        {
            Title = title ??
                throw new ArgumentNullException("All books must have a title.", nameof(title));
        }

        public string Title { get; }
    }
    //</snippet1>
#pragma warning restore CA2208 // Instantiate argument exceptions correctly
}

namespace ca2208_2
{
    //<snippet2>
    public class Book
    {
        public Book(string title)
        {
            Title = title ??
                throw new ArgumentNullException(nameof(title), "All books must have a title.");
        }

        public string Title { get; }
    }
    //</snippet2>
}

namespace ca2208_3
{
#pragma warning disable CA2208 // Instantiate argument exceptions correctly
    //<snippet3>
    public class Product
    {
        public string? Description { get; set; }
        public string Name { get; set; } = string.Empty;
    }

    public class Example
    {
        // Violates CA2208: 'description' is not a parameter of this method.
        public void ProcessProduct(Product product)
        {
            string? description = product.Description;
            if (description is null)
            {
                throw new ArgumentNullException(nameof(description), $"Product named {product.Name} had no description!");
            }
            // Process description...
        }
    }
    //</snippet3>
#pragma warning restore CA2208 // Instantiate argument exceptions correctly
}

namespace ca2208_4
{
    //<snippet4>
    public class Product
    {
        public string? Description { get; set; }
        public string Name { get; set; } = string.Empty;
    }

    public class Example
    {
        // Fixed: Use InvalidOperationException for invalid object state.
        public void ProcessProduct(Product product)
        {
            string? description = product.Description;
            if (description is null)
            {
                throw new InvalidOperationException($"Product named {product.Name} had no description!");
            }
            // Process description...
        }
    }
    //</snippet4>
}

sample · vbdocs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca2208-instantiate-argument-exceptions-correctly_1.vbsnippet3

Imports System

Namespace ca2208
#Disable Warning CA2208 ' Instantiate argument exceptions correctly
    '<snippet1>
    Public Class Book

        Private ReadOnly _Title As String

        Public Sub New(ByVal title As String)
            ' Violates this rule (constructor arguments are switched)            
            If (title Is Nothing) Then
                Throw New ArgumentNullException("title cannot be a null reference (Nothing in Visual Basic)", "title")
            End If
            _Title = title
        End Sub

        Public ReadOnly Property Title()
            Get
                Return _Title
            End Get
        End Property

    End Class
    '</snippet1>
#Enable Warning CA2208 ' Instantiate argument exceptions correctly

End Namespace

Namespace ca2208_2
    '<snippet2>
    Public Class Book

        Private ReadOnly _Title As String

        Public Sub New(ByVal title As String)
            If (title Is Nothing) Then
                Throw New ArgumentNullException("title", "title cannot be a null reference (Nothing in Visual Basic)")
            End If

            _Title = title
        End Sub

        Public ReadOnly Property Title()
            Get
                Return _Title
            End Get
        End Property

    End Class
    '</snippet2>

End Namespace

Namespace ca2208_3
#Disable Warning CA2208 ' Instantiate argument exceptions correctly
    '<snippet3>
    Public Class Product
        Public Property Description As String
        Public Property Name As String = String.Empty
    End Class

    Public Class Example
        ' Violates CA2208: 'description' is not a parameter of this method.
        Public Sub ProcessProduct(ByVal product As Product)
            Dim description As String = product.Description
            If description Is Nothing Then
                Throw New ArgumentNullException(NameOf(description), $"Product named {product.Name} had no description!")
            End If
            ' Process description...
        End Sub
    End Class
    '</snippet3>
#Enable Warning CA2208 ' Instantiate argument exceptions correctly

End Namespace

Namespace ca2208_4
    '<snippet4>
    Public Class Product
        Public Property Description As String
        Public Property Name As String = String.Empty
    End Class

    Public Class Example
        ' Fixed: Use InvalidOperationException for invalid object state.
        Public Sub ProcessProduct(ByVal product As Product)
            Dim description As String = product.Description
            If description Is Nothing Then
                Throw New InvalidOperationException($"Product named {product.Name} had no description!")
            End If
            ' Process description...
        End Sub
    End Class
    '</snippet4>

End Namespace

The following code fixes the previous violation by using System.InvalidOperationException instead, which is appropriate when an object's state is invalid.

sample · csharpdocs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/ca2208.cssnippet4

csharp

using System;

namespace ca2208
{
#pragma warning disable CA2208 // Instantiate argument exceptions correctly
    //<snippet1>
    public class Book
    {
        public Book(string title)
        {
            Title = title ??
                throw new ArgumentNullException("All books must have a title.", nameof(title));
        }

        public string Title { get; }
    }
    //</snippet1>
#pragma warning restore CA2208 // Instantiate argument exceptions correctly
}

namespace ca2208_2
{
    //<snippet2>
    public class Book
    {
        public Book(string title)
        {
            Title = title ??
                throw new ArgumentNullException(nameof(title), "All books must have a title.");
        }

        public string Title { get; }
    }
    //</snippet2>
}

namespace ca2208_3
{
#pragma warning disable CA2208 // Instantiate argument exceptions correctly
    //<snippet3>
    public class Product
    {
        public string? Description { get; set; }
        public string Name { get; set; } = string.Empty;
    }

    public class Example
    {
        // Violates CA2208: 'description' is not a parameter of this method.
        public void ProcessProduct(Product product)
        {
            string? description = product.Description;
            if (description is null)
            {
                throw new ArgumentNullException(nameof(description), $"Product named {product.Name} had no description!");
            }
            // Process description...
        }
    }
    //</snippet3>
#pragma warning restore CA2208 // Instantiate argument exceptions correctly
}

namespace ca2208_4
{
    //<snippet4>
    public class Product
    {
        public string? Description { get; set; }
        public string Name { get; set; } = string.Empty;
    }

    public class Example
    {
        // Fixed: Use InvalidOperationException for invalid object state.
        public void ProcessProduct(Product product)
        {
            string? description = product.Description;
            if (description is null)
            {
                throw new InvalidOperationException($"Product named {product.Name} had no description!");
            }
            // Process description...
        }
    }
    //</snippet4>
}

sample · vbdocs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca2208-instantiate-argument-exceptions-correctly_1.vbsnippet4

Imports System

Namespace ca2208
#Disable Warning CA2208 ' Instantiate argument exceptions correctly
    '<snippet1>
    Public Class Book

        Private ReadOnly _Title As String

        Public Sub New(ByVal title As String)
            ' Violates this rule (constructor arguments are switched)            
            If (title Is Nothing) Then
                Throw New ArgumentNullException("title cannot be a null reference (Nothing in Visual Basic)", "title")
            End If
            _Title = title
        End Sub

        Public ReadOnly Property Title()
            Get
                Return _Title
            End Get
        End Property

    End Class
    '</snippet1>
#Enable Warning CA2208 ' Instantiate argument exceptions correctly

End Namespace

Namespace ca2208_2
    '<snippet2>
    Public Class Book

        Private ReadOnly _Title As String

        Public Sub New(ByVal title As String)
            If (title Is Nothing) Then
                Throw New ArgumentNullException("title", "title cannot be a null reference (Nothing in Visual Basic)")
            End If

            _Title = title
        End Sub

        Public ReadOnly Property Title()
            Get
                Return _Title
            End Get
        End Property

    End Class
    '</snippet2>

End Namespace

Namespace ca2208_3
#Disable Warning CA2208 ' Instantiate argument exceptions correctly
    '<snippet3>
    Public Class Product
        Public Property Description As String
        Public Property Name As String = String.Empty
    End Class

    Public Class Example
        ' Violates CA2208: 'description' is not a parameter of this method.
        Public Sub ProcessProduct(ByVal product As Product)
            Dim description As String = product.Description
            If description Is Nothing Then
                Throw New ArgumentNullException(NameOf(description), $"Product named {product.Name} had no description!")
            End If
            ' Process description...
        End Sub
    End Class
    '</snippet3>
#Enable Warning CA2208 ' Instantiate argument exceptions correctly

End Namespace

Namespace ca2208_4
    '<snippet4>
    Public Class Product
        Public Property Description As String
        Public Property Name As String = String.Empty
    End Class

    Public Class Example
        ' Fixed: Use InvalidOperationException for invalid object state.
        Public Sub ProcessProduct(ByVal product As Product)
            Dim description As String = product.Description
            If description Is Nothing Then
                Throw New InvalidOperationException($"Product named {product.Name} had no description!")
            End If
            ' Process description...
        End Sub
    End Class
    '</snippet4>

End Namespace

CA1507: Use nameof in place of string

#Cause

#Rule description

#How to fix violations

#When to suppress warnings

#Suppress a warning

#Configure code to analyze

#Include specific API surfaces

#Example

#Related rules

Cause

Rule description

How to fix violations

When to suppress warnings

Suppress a warning

Configure code to analyze

Include specific API surfaces

Example

Related rules