16

XML ドキュメントを使用したサンプル メソッド:

// summary and param tags are here when you're not looking.
/// <exception cref="ArgumentNullException>
///    <paramref name="text" /> is null.
/// </exception>
public void Write(string text)
{
    if (text == null)
        throw new ArgumentNullException("text", "Text must not be null.");

    // sync stuff...
}

Write(null)期待どおりに例外をスローします。以下は非同期メソッドです。

public async Task WriteAsync(string text)
{
    if (text == null)
        throw new ArgumentNullException("text", "Text must not be null.");

    // async stuff...
}

WriteAsync(null)、待機するまで例外をスローしません。とにかくタグで指定する必要がありますArgumentNullExceptionか？消費者は、呼び出しがスローされ、次のように記述される可能性がexceptionあると考えるようになると思います。WriteAsyncArgumentNullException

Task t;
try
{
    t = foo.WriteAsync(text);
}
catch (ArgumentNullException)
{
    // handling stuff.
}

非同期メソッドの例外を文書化するためのベスト プラクティスは何ですか?

4

3 に答える 3

10

直接的な答えではありませんが、個人的にはここで高速失敗に傾くことをお勧めします。これは、2 つのメソッドを記述することを意味する場合があります。

public Task WriteAsync(string text) // no "async"
{
    // validation
    if (text == null)
        throw new ArgumentNullException("text", "Text must not be null.");

    return WriteAsyncImpl(text);
}
private async Task WriteAsyncImpl(string text)
{
    // async stuff...
}

このパターンは、「高速パス」コードを追加する理想的な場所でもあります。次に例を示します。

public Task WriteAsync(string text) // no "async"
{
    // validation
    if (text == null)
        throw new ArgumentNullException("text", "Text must not be null.");

    if (some condition)
        return Task.FromResult(0); // or similar; also returning a pre-existing
                                   // Task instance can be useful

    return WriteAsyncImpl(text);
}
于 2013-04-09T13:07:23.233 に答える