Как зарегистрировать вызванные исключительные ситуации в [закрытом] c#/.net

Можно сделать процесс документации легче при помощи нескольких больших дополнений. Один из них GhostDoc, свободное дополнение для Visual Studio, которая генерирует комментарии XML-документа. Кроме того, если Вы используете ReSharper, взглянули на превосходное Плагин Agent Johnson для ReSharper, который добавляет опцию генерировать XML-комментарии для вызванных исключительных ситуаций.

Обновление: кажется, что Снова Johnson не доступен для R# 8, контроль Исключительный для ReSharper как альтернатива...

Шаг 1: GhostDoc генерирует XML-комментарий (Ctrl-Shift-D), в то время как плагин Agent Johnson для ReSharper предлагает документировать исключение также:

Шаг 2: Используйте сочетание клавиш ReSharper (Alt-Enter) для добавления документации исключения также:

шаг 2 http://i41.tinypic.com/osdhm

Hope, которая помогает :)

Необходимо использовать стандарт xml документация .

/// <exception cref="InvalidOperationException">Why it's thrown.</exception>
/// <exception cref="FileNotFoundException">Why it's thrown.</exception>
/// <exception cref="DivideByZeroException">Why it's thrown.</exception>
public void MyMethod1()
{
    MyMethod2();
    // ... other stuff here
}

/// <exception cref="FileNotFoundException">Why it's thrown.</exception>
/// <exception cref="DivideByZeroException">Why it's thrown.</exception>
public void MyMethod2()
{
    System.IO.File.Open(somepath...);
}

/// <exception cref="FileNotFoundException">Why it's thrown.</exception>
public void MyMethod3()
{
    try
    {
        MyMethod2();
    }
    catch (DivideByZeroException ex)
    {
        Trace.Warning("We tried to divide by zero, but we can continue.");
    }
}

значение в выполнении его этот путь состоит в том, что Вы предоставляете документацию известных исключений, которые могут произойти. Эта документация доступна в intellisense, если Вы используете Visual Studio и можете напомнить Вам (или другие) позже исключений, что можно ожидать.

Вы хотите указать определенные типы исключительной ситуации, потому что Вы можете обрабатывать один тип исключения, в то время как другие типы являются результатом серьезной проблемы и не могут быть исправлены.

Из того, что я понимаю, намерение использовать < exception> элемент должен использовать его при украшении методов, не исключений:

/// <summary>Does something!</summary>
/// <exception cref="DidNothingException">Thrown if nothing is actually done.</exception>
public void DoSomething()
{
// There be logic here
}

Исключения, которые могут быть брошены другими методами, которые называют, должны быть пойманы, обработаны и зарегистрированы в те методы. Должны быть зарегистрированы исключения, которые могли возможно брошенный.NET или исключениями, которые являются явно брошены Вашим собственным кодом.

До получения еще конкретного, чем это, возможно, можно ли поймать и выдать ли собственные специализированные исключения?

Часть контракта для Вашего метода должна быть должна проверить, что предварительные условия допустимы, таким образом:

public void MyMethod2()
{
    System.IO.File.Open(somepath...); // this may throw FileNotFoundException
}

становится

/// <exception cref="FileNotFoundException">Thrown when somepath isn't a real file.</exception>
public void MyMethod2()
{
    FileInfo fi = new FileInfo( somepath );
    if( !fi.Exists )
    {
        throw new FileNotFoundException("somepath doesn't exists")
    }
    // Maybe go on to check you have permissions to read from it.

    System.IO.File.Open(somepath...); // this may still throw FileNotFoundException though
}

С этим подходом, легче зарегистрировать все исключения, которые Вы явно выдаете, не имея необходимость к также документу, который OutOfMemoryException мог бы быть брошенным, и т.д.

Необходимо зарегистрировать все исключения, которые могли возможно быть выданы методом.

Для сокрытия деталей реализации я попытался бы обработать некоторые исключения от MyMethod2 сам.

Вы могли считать повторно верение ими, если Вы не можете обработать или решить исключение. Главным образом упаковал/перенес в более многозначительном исключении для вызывающей стороны.

Ожидаемые исключения документа в Вашем методе, в Вашем примере, я позволил бы пользователю знать, что тот метод может бросить файл, не найденный исключением.

Помнят, что это должно сообщить вызывающей стороне того, что ожидать, таким образом, они могут выбрать, как иметь дело с ним.

Indeed, as it has been already answered, the way to document the exceptions is using XML Comments.

In addition to the plugins, you can also use static analysis tools that can be integrated with TFS to be sure you have the exceptions documented.

In the links below you can see how to build a custom rule for StyleCop to validate the exceptions thrown by your methods are being documented.

http://www.josefcobonnin.com/post/2009/01/11/Xml-Documentation-Comments-Exceptions-I.aspx http://www.josefcobonnin.com/post/2009/01/15/Xml-Documentation-Comments-Exceptions-II.aspx

Regards.