System.ArgumentOutOfRangeException Class

Summary

The exception that is thrown when the value of an argument is outside the allowable range of values as defined by the invoked method.

C# Syntax:

[Serializable] public class ArgumentOutOfRangeException : ArgumentException

ArgumentOutOfRangeException is thrown when a method is invoked and at least one of the arguments passed to the method is not null and does not contain a valid value.

ArgumentOutOfRangeException is used extensively by:

• Classes in the System.Collections and System.IO namespaces.

• The Array class.

ArgumentOutOfRangeException behaves identically to ArgumentException. It is provided so that application code can differentiate between exceptions caused by invalid arguments that are not null, and exceptions caused by null arguments. For errors caused by null arguments, see ArgumentNullException.

ArgumentOutOfRangeException uses the HRESULT COR_E_ARGUMENTOUTOFRANGE, which has the value 0x80131502.

For a list of initial property values for an instance of ArgumentOutOfRangeException, see the ArgumentOutOfRangeException.#ctor constructors.

System Namespace | Exception | MSDN: handlingthrowingexceptions

System.ArgumentOutOfRangeException Member List:

Public Constructors

ctor #1	Overloaded: .ctor() Default constructor. This constructor is called by derived class constructors to initialize state in this type. Initializes a new instance of the ArgumentOutOfRangeException class.
ctor #2	Overloaded: .ctor(string paramName) Initializes a new instance of the ArgumentOutOfRangeException class with the name of the parameter that causes this exception.
ctor #4	Overloaded: .ctor(string paramName, string message) Initializes a new instance of the ArgumentOutOfRangeException class with a specified error message and the name of the parameter that causes this exception.
ctor #5	Overloaded: .ctor(string paramName, object actualValue, string message) Initializes a new instance of the ArgumentOutOfRangeException class with a specified error message, the parameter name, and the value of the argument.

Public Properties

ActualValue	Read-only Gets the argument value that causes this exception.
HelpLink (inherited from System.Exception)	Read-write See base class member description: System.Exception.HelpLink Gets or sets a link to the help file associated with this exception.
InnerException (inherited from System.Exception)	Read-only See base class member description: System.Exception.InnerException Gets the Exception instance that caused the current exception.
Message	Read-only Overridden: Gets the error message and the string representation of the invalid argument value, or only the error message if the argument value is null.
ParamName (inherited from System.ArgumentException)	Read-only See base class member description: System.ArgumentException.ParamName Gets the name of the parameter that causes this exception.
Source (inherited from System.Exception)	Read-write See base class member description: System.Exception.Source Gets or sets the name of the application or the object that causes the error.
StackTrace (inherited from System.Exception)	Read-only See base class member description: System.Exception.StackTrace Gets a string representation of the frames on the call stack at the time the current exception was thrown.
TargetSite (inherited from System.Exception)	Read-only See base class member description: System.Exception.TargetSite Gets the method that throws the current exception.

Public Methods

Equals (inherited from System.Object)	See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects.
GetBaseException (inherited from System.Exception)	See base class member description: System.Exception.GetBaseException When overridden in a derived class, returns the Exception that is the root cause of one or more subsequent exceptions.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetObjectData	Overridden: Sets the SerializationInfo object with the invalid argument value and additional exception information.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
ToString (inherited from System.Exception)	See base class member description: System.Exception.ToString Creates and returns a string representation of the current exception.

Protected Constructors

ctor #3

Overloaded: .ctor(SerializationInfo info, StreamingContext context) Initializes a new instance of the ArgumentOutOfRangeException class with serialized data.

Protected Properties

HResult (inherited from System.Exception)

Read-write See base class member description: System.Exception.HResult Gets or sets HRESULT, a coded numerical value that is assigned to a specific exception.

Protected Methods

Finalize (inherited from System.Object)	See base class member description: System.Object.Finalize Derived from System.Object, the primary base class for all objects.
MemberwiseClone (inherited from System.Object)	See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects.

Hierarchy:

• System.Object
• System.Exception
• System.SystemException
• System.ArgumentException
• System.ArgumentOutOfRangeException

System.ArgumentOutOfRangeException Member Details

Summary

Initializes a new instance of the ArgumentOutOfRangeException class.

Default constructor. This constructor is called by derived class constructors to initialize state in this type.

C# Syntax:

public ArgumentOutOfRangeException();

This constructor initializes the ArgumentException.Message property of the new instance to a system-supplied message that describes the error, such as "Nonnegative number required." This message takes into account the current system culture.

The following table shows the initial property values for an instance of ArgumentOutOfRangeException.

Property	Value
Exception.InnerException	A null reference ( not set or empty in Visual Basic). (Visual Basic not implemented in the shared source CLI)
ArgumentOutOfRangeException.Message	The localized error message string.

Return to top

Summary

Initializes a new instance of the ArgumentOutOfRangeException class with the name of the parameter that causes this exception.

C# Syntax:

public ArgumentOutOfRangeException(    string paramName );

paramName

The name of the parameter that caused the exception.

This constructor initializes the ArgumentException.Message property of the new instance to a system-supplied message that describes the error, such as "Nonnegative number required." This message takes into account the current system culture.

This constructor initializes the ArgumentException.ParamName property of the new instance using paramName. The content of paramName is intended to be understood by humans.

The following table shows the initial property values for an instance of ArgumentOutOfRangeException.

Property	Value
Exception.InnerException	A null reference ( not set or empty in Visual Basic). (Visual Basic not implemented in the shared source CLI)
ArgumentOutOfRangeException.Message	The empty string ("").
ParamName	The parameter name string.

Return to top

Summary

Initializes a new instance of the ArgumentOutOfRangeException class with serialized data.

C# Syntax:

protected ArgumentOutOfRangeException(    SerializationInfo info,    StreamingContext context );

info

The object that holds the serialized object data.

context

The contextual information about the source or destination.

This constructor is called during deserialization to reconstitute the exception object transmitted over a stream. For more information, see the conceptual topic at MSDN: serialization.

Return to top

Summary

Initializes a new instance of the ArgumentOutOfRangeException class with a specified error message and the name of the parameter that causes this exception.

C# Syntax:

public ArgumentOutOfRangeException(    string paramName,    string message );

paramName

The name of the parameter that caused the exception.

message

The message that describes the error.

This constructor initializes the ArgumentOutOfRangeException.Message property of the new instance using the value of message parameter. The content of the message parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture.

This constructor initializes the ArgumentException.ParamName property of the new instance using paramName. The content of paramName is intended to be understood by humans.

The following table shows the initial property values for an instance of ArgumentOutOfRangeException.

Property	Value
Exception.InnerException	null .
ArgumentOutOfRangeException.Message	The error message string.
ArgumentException.ParamName	The parameter name string.

Return to top

Summary

Initializes a new instance of the ArgumentOutOfRangeException class with a specified error message, the parameter name, and the value of the argument.

C# Syntax:

public ArgumentOutOfRangeException(    string paramName,    object actualValue,    string message );

paramName

The name of the parameter that caused the exception.

actualValue

The value of the argument that causes this exception.

message

The message that describes the error.

This constructor initializes the ArgumentException.ParamName property of the new instance using paramName, the ArgumentOutOfRangeException.ActualValue property using actualValue, and the ArgumentException.Message property using message. The content of the paramName and message parameters is intended to be understood by humans. The caller of this constructor is required to ensure that these strings have been localized for the current system culture.

This constructor with the additional argument actualValue is not used within the .NET Framework class library. The ArgumentOutOfRangeException.ActualValue property is provided so that applications can make use of the available argument value.

The actualValue parameter contains an invalid value that is passed to the method and causes this exception to be thrown. This value is stored in the ArgumentOutOfRangeException.ActualValue property and its string representation is appended to the message string held in the ArgumentOutOfRangeException.Message property.

The following table shows the initial property values for an instance of ArgumentOutOfRangeException.

Property	Value
ArgumentOutOfRangeException.ActualValue	The argument value.
Exception.InnerException	The null reference ( not set or empty in Visual Basic). (Visual Basic not implemented in the shared source CLI)
ArgumentOutOfRangeException.Message	The error message string.
ArgumentException.ParamName	The parameter name string.

Return to top

Summary

Gets the argument value that causes this exception.

C# Syntax:

public virtual object ActualValue {get;}

Use this property to retrieve the invalid argument.

The ActualValue property returns the same value as was passed into the constructor, or null if no value was supplied.

The ArgumentOutOfRangeException.ActualValue property is assigned a value at the time of object construction. If the ArgumentOutOfRangeException.ActualValue property value is not null, a string representation of the value is then appended to the message string held by the ArgumentOutOfRangeException.Message property.

The ArgumentOutOfRangeException.ActualValue property is not used within the .NET Framework class library. It carries a null value in all the ArgumentOutOfRangeException objects thrown by the .NET Framework class library. The ArgumentOutOfRangeException.ActualValue property is provided so that applications can make use of the available argument value.

This property is read-only and should only be overridden in order to customize the content or format of the value.

Return to top

Inherited
See base class member description: System.Exception.HelpLink

Summary

Gets or sets a link to the help file associated with this exception.

C# Syntax:

public virtual string HelpLink {get; set;}

The return value, which represents a help file, is a URN or URL. For example, the HelpLink value could be:

"file:///C:/Applications/Bazzal/help.html#ErrorNum42"

Return to top

Inherited
See base class member description: System.Exception.HResult

Summary

Gets or sets HRESULT, a coded numerical value that is assigned to a specific exception.

C# Syntax:

protected int HResult {get; set;}

HRESULT is a 32-bit value, divided into three different fields: a severity code, a facility code, and an error code. The severity code indicates whether the return value represents information, warning, or error. The facility code identifies the area of the system responsible for the error. The error code is a unique number that is assigned to represent the exception. Each exception is mapped to a distinct HRESULT. When managed code throws an exception, the runtime passes the HRESULT to the COM client. When unmanaged code returns an error, the HRESULT is converted to an exception, which is then thrown by the runtime.

Return to top

Inherited
See base class member description: System.Exception.InnerException

Summary

Gets the Exception instance that caused the current exception.

C# Syntax:

public Exception InnerException {get;}

When an exception X is thrown as a direct result of a previous exception Y, the InnerException property of X should contain a reference to Y.

Use the InnerException property to obtain the set of exceptions that led to the current exception.

You can create a new exception that catches an earlier exception. The code that handles the second exception can make use of the additional information from the earlier exception to handle the error more appropriately.

Suppose that there is a function that reads a file and formats the data from that file. In this example, as the code tries to read the file, an IOException is thrown. The function catches the IOException and throws a FileNotFoundException. The IOException could be saved in the Exception.InnerException property of the FileNotFoundException, enabling the code that catches the FileNotFoundException to examine what causes the initial error.

The Exception.InnerException property, which holds a reference to the inner exception, is set upon initialization of the exception object.

The following example demonstrates throwing and catching an exception that references an inner exception.

using System;
public class MyAppException:ApplicationException 
{
   public MyAppException (String message) : base (message) 
   {}
   public MyAppException (String message, Exception inner) : base(message,inner) {}	
   }
public class ExceptExample 
{
   public void ThrowInner () 
   {
   throw new MyAppException("ExceptExample inner exception");
   }
   public void CatchInner() 
   {
      try 
      {
      this.ThrowInner();
      }
         catch (Exception e) 
         {
         throw new MyAppException("Error caused by trying ThrowInner.",e);
         }
      }
   }
public class Test 
{
   public static void Main() 
   {
   ExceptExample testInstance = new ExceptExample();
      try 
      {
      testInstance.CatchInner();
      }
         catch(Exception e) 
         {
         Console.WriteLine ("In Main catch block. Caught: {0}", e.Message);
         Console.WriteLine ("Inner Exception is {0}",e.InnerException);
         }
      }
}

    

This code has the following output:

In Main catch block. Caught: Error caused by trying ThrowInner. Inner Exception is MyAppException: ExceptExample inner exception at ExceptExample.ThrowInner() at ExceptExample.CatchInner()

Return to top

Summary

Gets the error message and the string representation of the invalid argument value, or only the error message if the argument value is null.

C# Syntax:

public override string Message {get;}

This property overrides ArgumentException.Message.

The error message should describe the expected values of the parameter that causes this exception. The error message should be localized.

Return to top

Inherited
See base class member description: System.ArgumentException.ParamName

Summary

Gets the name of the parameter that causes this exception.

C# Syntax:

public virtual string ParamName {get;}

Every ArgumentException should carry the name of the parameter that causes this exception. The parameter name should not be localized.

This property is read-only, and returns the same value as was passed into the constructor. Overriding methods should be used solely to customize the content or format of the parameter name.

Return to top

Inherited
See base class member description: System.Exception.Source

Summary

Gets or sets the name of the application or the object that causes the error.

C# Syntax:

public virtual string Source {get; set;}

If Exception.Source is not set, the name of the assembly where the exception originated is returned.

Return to top

Inherited
See base class member description: System.Exception.StackTrace

Summary

Gets a string representation of the frames on the call stack at the time the current exception was thrown.

C# Syntax:

public virtual string StackTrace {get;}

The execution stack keeps track of all the methods that are in execution at a given instant. A trace of the method calls is called a stack trace. The stack trace listing provides a means to follow the call sequence to the line number in the method where the exception occurs.

StackTrace may not report as many method calls as expected, due to code transformations, such as inlining, that occur during optimization.

Notes to inheritors: The StackTrace property is overridden in classes that require control over the stack trace content or format.

By default, the stack trace is captured immediately before an exception object is thrown. Use Environment.StackTrace to get stack trace information when no exception is being thrown.

Return to top

Inherited
See base class member description: System.Exception.TargetSite

Summary

Gets the method that throws the current exception.

C# Syntax:

public MethodBase TargetSite {get;}

If the method that throws this exception is not available and the stack trace is not a null reference (not set or empty), Exception.TargetSite obtains the method from the stack trace. If the stack trace is a null reference , Exception.TargetSite also returns a null reference.

Return to top

Inherited
See base class member description: System.Object.Equals

C# Syntax:

public virtual bool Equals(    object obj );

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.Finalize

C# Syntax:

~ArgumentOutOfRangeException();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Exception.GetBaseException

Summary

When overridden in a derived class, returns the Exception that is the root cause of one or more subsequent exceptions.

C# Syntax:

public virtual Exception GetBaseException();

Return Value:

The first exception thrown in a chain of exceptions. If the Exception.InnerException property of the current exception is a null reference (not set or empty), this property returns the current exception.

A chain of exceptions consists of a set of exceptions such that each exception in the chain was thrown as a direct result of the exception referenced in its InnerException property. For a given chain, there can be exactly one exception that is the root cause of all other exceptions in the chain. This exception is called the base exception and its InnerException property always contains a null reference.

For all exceptions in a chain of exceptions, the GetBaseException method must return the same object (the base exception).

Use the GetBaseException method when you want to find the root cause of an exception but do not need information about exceptions that may have occurred between the current exception and the first exception.

Notes to inheritors: The GetBaseException method is overridden in classes that require control over the exception content or format.

Return to top

Inherited
See base class member description: System.Object.GetHashCode

C# Syntax:

public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Sets the SerializationInfo object with the invalid argument value and additional exception information.

C# Syntax:

public override void GetObjectData(    SerializationInfo info,    StreamingContext context );

info

The object that holds the serialized object data.

context

The contextual information about the source or destination.

Exceptions

Exception Type	Condition
ArgumentNullException	The info object is null.

Implements:

ISerializable.GetObjectData

ArgumentOutOfRangeException.GetObjectData sets a SerializationInfo with all the exception object data targeted for serialization. During deserialization, the exception object is reconstituted from the SerializationInfo transmitted over the stream.

For more information, see SerializationInfo.

Return to top

Inherited
See base class member description: System.Object.GetType

C# Syntax:

public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.MemberwiseClone

C# Syntax:

protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Exception.ToString

Summary

Creates and returns a string representation of the current exception.

C# Syntax:

public override string ToString();

Return Value:

A string representation of the current exception.

ToString returns a representation of the current exception that is intended to be understood by humans. Where the exception contains culture-sensitive data, the string representation returned by ToString is required to take into account the current system culture. Although there are no exact requirements for the format of the returned string, it should attempt to reflect the value of the object as perceived by the user.

The default implementation of Exception.ToString obtains the name of the class that threw the current exception, the message, the result of calling ToString on the inner exception, and the result of calling Environment.StackTrace. If any of these members is a null reference (not set or empty), its value is not included in the returned string.

If there is no error message or if it is an empty string (""), then no error message is returned. The name of the inner exception and the stack trace are returned only if they are not a null reference.

This method overrides Object.ToString.

Notes to inheritors: It is recommended, but not required, that ToString be overridden to return information about members declared in the derived class. For example, the ArgumentException class implements ToString so that it returns the value of the ParamName property, if that value is not a null reference.

The following example causes an exception and displays the result of calling ToString on that exception.

using System;

public class MyClass {}
public class ArgExceptionExample 
   {
   public static void Main()
      {
      MyClass my = new MyClass();
      string s = "sometext";
      try 
         {
         int i = s.CompareTo(my);
         }
            catch (Exception e) 
            {
            Console.WriteLine("Error: {0}",e.ToString());
            }
      }
}

    

This code has the following output:

Error: System.ArgumentException: Object must be of type String. at System.String.CompareTo(Object value) at ArgExceptionExample.Main()

Return to top

Top of page