443 строки
19 KiB
XML
443 строки
19 KiB
XML
<?xml version="1.0"?>
|
|
<doc>
|
|
<assembly>
|
|
<name>Gendarme.Rules.Exceptions</name>
|
|
</assembly>
|
|
<members>
|
|
<member name="T:Gendarme.Rules.Exceptions.AvoidArgumentExceptionDefaultConstructorRule">
|
|
<summary>
|
|
This rule checks that every <c>System.ArgumentException</c>,
|
|
<c>System.ArgumentNullException</c>, <c>System.ArgumentOutOfRangeException</c>, or
|
|
<c>System.DuplicateWaitObjectException</c> exception created is provided with some
|
|
useful information about the exception being thrown, minimally the parameter name.
|
|
</summary>
|
|
<example>
|
|
Bad example:
|
|
<code>
|
|
public void Add (object key, object value)
|
|
{
|
|
if ((obj == null) || (key == null)) {
|
|
throw new ArgumentNullException ();
|
|
}
|
|
Inner.Add (key, value);
|
|
}
|
|
</code></example>
|
|
<example>
|
|
Good example:
|
|
<code>
|
|
public void Add (object key, object value)
|
|
{
|
|
if (key == null) {
|
|
throw new ArgumentNullException ("key");
|
|
}
|
|
if (obj == value) {
|
|
throw new ArgumentNullException ("value");
|
|
}
|
|
Inner.Add (key, value);
|
|
}
|
|
</code></example>
|
|
<remarks>This rule is available since Gendarme 2.0</remarks>
|
|
</member>
|
|
<member name="T:Gendarme.Rules.Exceptions.AvoidThrowingBasicExceptionsRule">
|
|
<summary>
|
|
This rule checks for methods that create basic exceptions like <c>System.Exception</c>,
|
|
<c>System.ApplicationException</c> or <c>System.SystemException</c>. Those exceptions
|
|
do not provide enough information about the error to be helpful to the consumer
|
|
of the library.
|
|
</summary>
|
|
<example>
|
|
Bad example:
|
|
<code>
|
|
public void Add (object obj)
|
|
{
|
|
if (obj == null) {
|
|
throw new Exception ();
|
|
}
|
|
Inner.Add (obj);
|
|
}
|
|
</code></example>
|
|
<example>
|
|
Good example:
|
|
<code>
|
|
public void Add (object obj)
|
|
{
|
|
if (obj == null) {
|
|
throw new ArgumentNullException ("obj");
|
|
}
|
|
Inner.Add (obj);
|
|
}
|
|
</code></example>
|
|
<remarks>This rule is available since Gendarme 2.0</remarks>
|
|
</member>
|
|
<member name="T:Gendarme.Rules.Exceptions.DoNotDestroyStackTraceRule">
|
|
<summary>
|
|
This rule will fire if a catch handler throws the exception it caught. What it should
|
|
do instead is rethrow the original exception (e.g. use <c>throw</c> instead of
|
|
<c>throw ex</c>). This is helpful because rethrow preserves the stacktrace of the
|
|
original exception.
|
|
</summary>
|
|
<example>
|
|
Bad example:
|
|
<code>
|
|
try {
|
|
Int32.Parse ("Broken!");
|
|
}
|
|
catch (Exception ex) {
|
|
Assert.IsNotNull (ex);
|
|
throw ex;
|
|
}
|
|
</code></example>
|
|
<example>
|
|
Good example:
|
|
<code>
|
|
try {
|
|
Int32.Parse ("Broken!");
|
|
}
|
|
catch (Exception ex) {
|
|
Assert.IsNotNull (ex);
|
|
throw;
|
|
}
|
|
</code></example>
|
|
<remarks>Prior to Gendarme 2.0 this rule was named DontDestroyStackTraceRule.</remarks>
|
|
</member>
|
|
<member name="T:Gendarme.Rules.Exceptions.DoNotThrowInNonCatchClausesRule">
|
|
<summary>
|
|
This rule detects exceptions that are throw in <c>fault</c>, <c>filter</c> or
|
|
<c>finally</c> clauses. Such exceptions will make it much harder to debug your
|
|
applications since it will hide the original exception.
|
|
</summary>
|
|
<example>
|
|
Bad example:
|
|
<code>
|
|
int err = 0;
|
|
try {
|
|
err = Initialize ();
|
|
}
|
|
finally {
|
|
Cleanup ();
|
|
if (err != 0)
|
|
throw new NotSupportedException ();
|
|
}
|
|
</code></example>
|
|
<example>
|
|
Good example:
|
|
<code>
|
|
try {
|
|
if (Initialize () != 0)
|
|
throw new NotSupportedException ();
|
|
}
|
|
finally {
|
|
Cleanup ();
|
|
}
|
|
</code></example>
|
|
</member>
|
|
<member name="T:Gendarme.Rules.Exceptions.DoNotThrowInUnexpectedLocationRule">
|
|
<summary>
|
|
There are a number of methods which have constraints on the exceptions
|
|
which they may throw. This rule checks the following methods:
|
|
<list type="bullet"><item><description>Property getters - properties should work very much
|
|
like fields: they should execute very quickly and, in general, should
|
|
not throw exceptions. However they may throw System.InvalidOperationException,
|
|
System.NotSupportedException, or an exception derived from these.
|
|
Indexed getters may also throw System.ArgumentException or
|
|
System.Collections.Generic.KeyNotFoundException.</description></item><item><description>Event accessors - in general events should not throw
|
|
when adding or removing a handler. However they may throw
|
|
System.InvalidOperationException, System.NotSupportedException,
|
|
System.ArgumentException, or an exception derived from these.</description></item><item><description>Object.Equals and IEqualityComparer<T>.Equals - should
|
|
not throw. In particular they should do something sensible when passed
|
|
null arguments or unexpected types.</description></item><item><description>Object.GetHashCode - should not throw or the object
|
|
will not work properly with dictionaries and hash sets.</description></item><item><description>IEqualityComparer<T>.GetHashCode - may throw
|
|
System.ArgumentException.</description></item><item><description>Object.ToString - these are called by the debugger to display
|
|
objects and are also often used with printf style debugging so they should
|
|
not change the object's state and should not throw.</description></item><item><description>static constructors - should very rarely throw. If they
|
|
do throw then the type will not be useable within that application
|
|
domain.</description></item><item><description>finalizers - should not throw. If they do (as of .NET 2.0)
|
|
the process will be torn down.</description></item><item><description>IDisposable.Dispose - should not throw. If they do
|
|
it's much harder to guarantee that objects clean up properly.</description></item><item><description>Dispose (bool) - should not throw because that makes
|
|
it very difficult to clean up objects and because they are often
|
|
called from a finalizer.</description></item><item><description>operator== and operator!= - should not throw. In particular
|
|
they should do something sensible when passed null arguments or
|
|
unexpected types.</description></item><item><description>implicit cast operators - should not throw. These methods
|
|
are called implicitly so it tends to be quite surprising if they throw
|
|
exceptions.</description></item><item><description><c>TryParse</c> methods - should not throw. These methods
|
|
are designed to be executed without having to catch multiple exceptions
|
|
(unlike the <c>Parse</c> methods).</description></item></list>
|
|
Note that the rule does not complain if a method throws
|
|
System.NotImplementedException because
|
|
DoNotForgetNotImplementedMethodsRule will flag them. Also the rule
|
|
may fire with anonymous types with gmcs versions prior to 2.2, see
|
|
[https://bugzilla.novell.com/show_bug.cgi?id=462622] for more details.
|
|
</summary>
|
|
<example>
|
|
Bad example:
|
|
<code>
|
|
public override bool Equals (object obj)
|
|
{
|
|
if (obj == null) {
|
|
return false;
|
|
}
|
|
Customer rhs = (Customer) obj; // throws if obj is not a Customer
|
|
return name == rhs.name;
|
|
}
|
|
</code></example>
|
|
<example>
|
|
Good example:
|
|
<code>
|
|
public override bool Equals (object obj)
|
|
{
|
|
Customer rhs = obj as Customer;
|
|
if (rhs == null) {
|
|
return false;
|
|
}
|
|
return name == rhs.name;
|
|
}
|
|
</code></example>
|
|
<remarks>This rule is available since Gendarme 2.4</remarks>
|
|
</member>
|
|
<member name="T:Gendarme.Rules.Exceptions.DoNotThrowReservedExceptionRule">
|
|
<summary>
|
|
This rule will fire if an <c>System.ExecutionEngineException</c>, <c>System.IndexOutOfRangeException</c>,
|
|
<c>NullReferenceException</c>, or <c>System.OutOfMemoryException</c> class is
|
|
instantiated. These exceptions are for use by the runtime and should not be thrown by
|
|
user code.
|
|
</summary>
|
|
<example>
|
|
Bad example:
|
|
<code>
|
|
public void Add (object obj)
|
|
{
|
|
if (obj == null) {
|
|
throw new NullReferenceException ("obj");
|
|
}
|
|
Inner.Add (obj);
|
|
}
|
|
</code></example>
|
|
<example>
|
|
Good example:
|
|
<code>
|
|
public void Add (object obj)
|
|
{
|
|
if (obj == null) {
|
|
throw new ArgumentNullException ("obj");
|
|
}
|
|
Inner.Add (obj);
|
|
}
|
|
</code></example>
|
|
<remarks>This rule is available since Gendarme 2.0</remarks>
|
|
</member>
|
|
<member name="T:Gendarme.Rules.Exceptions.DoNotSwallowErrorsCatchingNonSpecificExceptionsRule">
|
|
<summary>
|
|
This rule will fire if a catch block catches <c>System.Exception</c> or
|
|
<c>System.SystemException</c> but does not rethrow the original
|
|
exception. This is problematic because you don't know what went wrong
|
|
so it's difficult to know that the error was handled correctly. It is better
|
|
to catch a more specific set of exceptions so that you do know what went
|
|
wrong and do know that it is handled correctly.
|
|
</summary>
|
|
<example>
|
|
Bad example:
|
|
<code>
|
|
try {
|
|
File.Open ("foo.txt", FileMode.Open);
|
|
}
|
|
catch (Exception) {
|
|
//Ooops what's failed ??? UnauthorizedException, FileNotFoundException ???
|
|
}
|
|
</code></example>
|
|
<example>
|
|
Good example (catch a specific exception):
|
|
<code>
|
|
try {
|
|
File.Open ("foo.txt", FileMode.Open);
|
|
}
|
|
catch (FileNotFoundException exception) {
|
|
//I know that the system can't find the file.
|
|
}
|
|
</code></example>
|
|
<example>
|
|
Good example (catch all and rethrow):
|
|
<code>
|
|
try {
|
|
File.Open ("foo.txt", FileMode.Open);
|
|
}
|
|
catch {
|
|
Console.WriteLine ("An error has happened.");
|
|
throw; // You don't swallow the error, because you rethrow the original exception.
|
|
}
|
|
</code></example>
|
|
<remarks>Prior to Gendarme 2.0 this rule was named DontSwallowErrorsCatchingNonspecificExceptionsRule.</remarks>
|
|
</member>
|
|
<member name="T:Gendarme.Rules.Exceptions.ExceptionShouldBeVisibleRule">
|
|
<summary>
|
|
This rule checks for non-visible exceptions which derive directly from
|
|
the most basic exceptions: <c>System.Exception</c>, <c>System.ApplicationException</c>
|
|
or <c>System.SystemException</c>. Those basic exceptions, being visible, will be the
|
|
only information available to the API consumer - but do not contain enough data to be
|
|
useful.
|
|
</summary>
|
|
<example>
|
|
Bad example:
|
|
<code>
|
|
internal class GeneralException : Exception {
|
|
}
|
|
</code></example>
|
|
<example>
|
|
Good example (visibility):
|
|
<code>
|
|
public class GeneralException : Exception {
|
|
}
|
|
</code></example>
|
|
<example>
|
|
Good example (base class):
|
|
<code>
|
|
internal class GeneralException : ArgumentException {
|
|
}
|
|
</code></example>
|
|
<remarks>This rule is available since Gendarme 2.0</remarks>
|
|
</member>
|
|
<member name="T:Gendarme.Rules.Exceptions.InstantiateArgumentExceptionCorrectlyRule">
|
|
<summary>
|
|
This rule will fire if the arguments to the <c>System.ArgumentException</c>,
|
|
<c>System.ArgumentNullException</c>, <c>System.ArgumentOutOfRangeException</c>,
|
|
and <c>System.DuplicateWaitObjectException</c> constructors are used incorrectly.
|
|
This is a common mistake because the position of the <c>parameterName</c> argument
|
|
is not consistent across these types.
|
|
</summary>
|
|
<example>
|
|
Bad example:
|
|
<code>
|
|
public void Show (string s)
|
|
{
|
|
if (s == null) {
|
|
// the first argument should be the parameter name
|
|
throw new ArgumentNullException ("string is null", "s");
|
|
}
|
|
if (s.Length == 0) {
|
|
// the second argument should be the parameter name
|
|
return new ArgumentException ("s", "string is empty");
|
|
}
|
|
Console.WriteLine (s);
|
|
}
|
|
</code></example>
|
|
<example>
|
|
Good example:
|
|
<code>
|
|
public void Show (string s)
|
|
{
|
|
if (s == null) {
|
|
throw new ArgumentNullException ("s", "string is null");
|
|
}
|
|
if (s.Length == 0) {
|
|
return new ArgumentException ("string is empty", "s");
|
|
}
|
|
Console.WriteLine (s);
|
|
}
|
|
</code></example>
|
|
<remarks>This rule is available since Gendarme 2.2</remarks>
|
|
</member>
|
|
<member name="T:Gendarme.Rules.Exceptions.MissingExceptionConstructorsRule">
|
|
<summary>
|
|
This rule will fire if an exception class is missing one or more of the following
|
|
constructors:
|
|
<list><item><description><c>public E ()</c> is required for XML serialization. Public access is required
|
|
in case the assembly uses CAS to prevent reflection on non-public members.</description></item><item><description><c>public E (string message)</c> is a .NET convention.</description></item><item><description><c>public E (string message, ..., Exception inner)</c> is a .NET convention.</description></item><item><description><c>(non)public E (SerializationInfo info, StreamingContext context)</c> is required for binary serialization.</description></item></list></summary>
|
|
<example>
|
|
Bad example:
|
|
<code>
|
|
public class GeneralException : Exception {
|
|
// access should be public
|
|
private GeneralException ()
|
|
{
|
|
}
|
|
}
|
|
</code></example>
|
|
<example>
|
|
Good example:
|
|
<code>
|
|
public class GeneralException : Exception {
|
|
public GeneralException ()
|
|
{
|
|
}
|
|
public GeneralException (string message) : base (message)
|
|
{
|
|
}
|
|
public GeneralException (string message, Exception inner) : base (message, inner)
|
|
{
|
|
}
|
|
protected GeneralException (SerializationInfo info, StreamingContext context) : base (info, context)
|
|
{
|
|
}
|
|
}
|
|
</code></example>
|
|
<remarks>This rule is available since Gendarme 2.0</remarks>
|
|
</member>
|
|
<member name="T:Gendarme.Rules.Exceptions.UseObjectDisposedExceptionRule">
|
|
<summary>
|
|
It's usually a very bad idea to attempt to use an object after it has been
|
|
disposed. Doing so may lead to crashes in native code or any number of
|
|
other problems. In order to prevent this, and to report the problem in
|
|
a clear way, classes should throw System.ObjectDisposedException from
|
|
public methods if the object has been disposed.
|
|
Note that there are some methods which should not throw ObjectDisposedException.
|
|
This includes constructors, finalizers, Equals, GetHashCode, ToString, and Dispose.
|
|
</summary>
|
|
<example>
|
|
Bad example:
|
|
<code>
|
|
internal sealed class WriteStuff : IDisposable
|
|
{
|
|
public WriteStuff (TextWriter writer)
|
|
{
|
|
this.writer = writer;
|
|
}
|
|
// Objects are generally not in a useable state after being disposed so
|
|
// their public methods should throw ObjectDisposedException.
|
|
public void Write (string message)
|
|
{
|
|
writer.Write (message);
|
|
}
|
|
public void Dispose ()
|
|
{
|
|
if (!disposed) {
|
|
writer.Dispose ();
|
|
disposed = true;
|
|
}
|
|
}
|
|
private bool disposed;
|
|
private TextWriter writer;
|
|
}
|
|
</code></example>
|
|
<example>
|
|
Good example:
|
|
<code>
|
|
internal sealed class WriteStuff : IDisposable
|
|
{
|
|
public WriteStuff (TextWriter writer)
|
|
{
|
|
this.writer = writer;
|
|
}
|
|
// In general all public methods should throw ObjectDisposedException
|
|
// if Dispose has been called.
|
|
public void Write (string message)
|
|
{
|
|
if (disposed) {
|
|
throw new ObjectDisposedException (GetType ().Name);
|
|
}
|
|
writer.Write (message);
|
|
}
|
|
public void Dispose ()
|
|
{
|
|
if (!disposed) {
|
|
writer.Dispose ();
|
|
disposed = true;
|
|
}
|
|
}
|
|
private bool disposed;
|
|
private TextWriter writer;
|
|
}
|
|
</code></example>
|
|
<remarks>This rule is available since Gendarme 2.6</remarks>
|
|
</member>
|
|
</members>
|
|
</doc>
|