await 연산자(C# 참조)await operator (C# reference)

await 연산자는 피연산자가 나타내는 비동기 작업이 완료될 때까지 바깥쪽 비동기 메서드의 평가를 일시 중단합니다.The await operator suspends evaluation of the enclosing async method until the asynchronous operation represented by its operand completes. 비동기 작업이 완료되면 await 연산자는 작업 결과를 반환합니다(있는 경우).When the asynchronous operation completes, the await operator returns the result of the operation, if any. 이미 완료된 작업을 나타내는 피연산자에 await 연산자가 적용되면 바깥쪽 메서드를 일시 중단하지 않고 작업 결과를 즉시 반환합니다.When the await operator is applied to the operand that represents an already completed operation, it returns the result of the operation immediately without suspension of the enclosing method. await 연산자는 비동기 메서드를 평가하는 스레드를 차단하지 않습니다.The await operator doesn't block the thread that evaluates the async method. await 연산자가 바깥쪽 비동기 메서드를 일시 중단하면 제어가 메서드 호출자에게 반환됩니다.When the await operator suspends the enclosing async method, the control returns to the caller of the method.

다음 예제에서 HttpClient.GetByteArrayAsync 메서드는 완료 시 바이트 배열을 생성하는 비동기 작업을 나타내는 Task<byte[]> 인스턴스를 반환합니다.In the following example, the HttpClient.GetByteArrayAsync method returns the Task<byte[]> instance, which represents an asynchronous operation that produces a byte array when it completes. 작업이 완료될 때까지 await 연산자는 DownloadDocsMainPageAsync 메서드를 일시 중단합니다.Until the operation completes, the await operator suspends the DownloadDocsMainPageAsync method. DownloadDocsMainPageAsync가 일시 중단되면 제어는 DownloadDocsMainPageAsync의 호출자인 Main 메서드에 반환됩니다.When DownloadDocsMainPageAsync gets suspended, control is returned to the Main method, which is the caller of DownloadDocsMainPageAsync. Main 메서드는 DownloadDocsMainPageAsync 메서드가 수행한 비동기 작업의 결과가 필요할 때까지 실행됩니다.The Main method executes until it needs the result of the asynchronous operation performed by the DownloadDocsMainPageAsync method. GetByteArrayAsync가 모든 바이트를 가져오면 나머지 DownloadDocsMainPageAsync 메서드가 평가됩니다.When GetByteArrayAsync gets all the bytes, the rest of the DownloadDocsMainPageAsync method is evaluated. 그 후에는 나머지 Main 메서드가 평가됩니다.After that, the rest of the Main method is evaluated.

using System;
using System.Net.Http;
using System.Threading.Tasks;

public class AwaitOperator
{
    public static async Task Main()
    {
        Task<int> downloading = DownloadDocsMainPageAsync();
        Console.WriteLine($"{nameof(Main)}: Launched downloading.");

        int bytesLoaded = await downloading;
        Console.WriteLine($"{nameof(Main)}: Downloaded {bytesLoaded} bytes.");
    }

    private static async Task<int> DownloadDocsMainPageAsync()
    {
        Console.WriteLine($"{nameof(DownloadDocsMainPageAsync)}: About to start downloading.");

        var client = new HttpClient();
        byte[] content = await client.GetByteArrayAsync("https://docs.microsoft.com/en-us/");

        Console.WriteLine($"{nameof(DownloadDocsMainPageAsync)}: Finished downloading.");
        return content.Length;
    }
}
// Output similar to:
// DownloadDocsMainPageAsync: About to start downloading.
// Main: Launched downloading.
// DownloadDocsMainPageAsync: Finished downloading.
// Main: Downloaded 27700 bytes.

앞의 예제에서는 C# 7.1부터 가능한 비동기 Main 메서드를 사용합니다.The preceding example uses the async Main method, which is possible beginning with C# 7.1. 자세한 내용은 Main 메서드 섹션의 await 연산자를 참조하세요.For more information, see the await operator in the Main method section.

참고

비동기 프로그래밍에 대한 소개는 async 및 await를 사용한 비동기 프로그래밍을 참조하세요.For an introduction to asynchronous programming, see Asynchronous programming with async and await. asyncawait를 사용하는 비동기 프로그래밍은 작업 기반 비동기 패턴을 따릅니다.Asynchronous programming with async and await follows the task-based asynchronous pattern.

async 키워드로 수정된 메서드, 람다 식 또는 무명 메서드에는 await 연산자만 사용할 수 있습니다.You can use the await operator only in a method, lambda expression, or anonymous method that is modified by the async keyword. 비동기 메서드 내의 동기 함수 본문, lock 문 블록 및 unsafe 컨텍스트에서는 await 연산자를 사용할 수 없습니다.Within an async method, you can't use the await operator in the body of a synchronous function, inside the block of a lock statement, and in an unsafe context.

await 연산자의 피연산자는 일반적으로 .NET 형식인 Task, Task<TResult>, ValueTask 또는 ValueTask<TResult> 중 하나에 해당합니다.The operand of the await operator is usually of one of the following .NET types: Task, Task<TResult>, ValueTask, or ValueTask<TResult>. 그러나 대기 가능한 모든 식은 await 연산자의 피연산자일 수 있습니다.However, any awaitable expression can be the operand of the await operator. 자세한 내용은 C# 언어 사양대기 가능 식 섹션을 참조하세요.For more information, see the Awaitable expressions section of the C# language specification.

t 식의 형식이 Task<TResult> 또는 ValueTask<TResult>이면 await t 식의 형식은 TResult입니다.The type of expression await t is TResult if the type of expression t is Task<TResult> or ValueTask<TResult>. t 형식이 Task 또는 ValueTask이면 await t 형식은 void입니다.If the type of t is Task or ValueTask, the type of await t is void. 두 경우 모두 t가 예외를 throw하면 await t는 예외를 다시 throw합니다.In both cases, if t throws an exception, await t rethrows the exception. 예외 처리에 대한 자세한 내용은 try-catch 문 문서에서 비동기 메서드의 예외 섹션을 참조하세요.For more information about exception handling, see the Exceptions in async methods section of the try-catch statement article.

asyncawait 키워드는 C# 5 이상 버전에서 사용할 수 있습니다.The async and await keywords are available in C# 5 and later.

비동기 스트림 및 삭제 가능한 항목Asynchronous streams and disposables

C# 8.0부터 비동기 스트림 및 삭제 가능한 항목을 사용할 수 있습니다.Beginning with C# 8.0, you can work with asynchronous streams and disposables.

await foreach 문을 사용하여 비동기 데이터 스트림을 사용합니다.You use the await foreach statement to consume an asynchronous stream of data. 자세한 내용은 foreach 문서 및 C# 8.0의 새로운 기능 문서의 비동기 스트림 섹션을 참조하세요.For more information, see the foreach statement article and the Asynchronous streams section of the What's new in C# 8.0 article.

await using 문을 사용하여 삭제 가능한 개체, 즉 IAsyncDisposable 인터페이스를 구현하는 형식의 개체를 비동기적으로 사용합니다.You use the await using statement to work with an asynchronously disposable object, that is, an object of a type that implements an IAsyncDisposable interface. 자세한 내용은 DisposeAsync 메서드 구현 문서의 삭제 가능한 비동기 항목 사용 섹션을 참조하세요.For more information, see the Using async disposable section of the Implement a DisposeAsync method article.

Main 메서드의 await 연산자await operator in the Main method

C# 7.1부터 애플리케이션 진입점인 Main 메서드Task 또는 Task<int>를 반환하여 해당 본문에서 await 연산자를 사용할 수 있습니다.Beginning with C# 7.1, the Main method, which is the application entry point, can return Task or Task<int>, enabling it to be async so you can use the await operator in its body. 이전 C# 버전에서는 Main 메서드가 비동기 작업이 완료될 때까지 대기하는지 확인하기 위해 해당 비동기 메서드에서 반환되는 Task<TResult> 인스턴스의 Task<TResult>.Result 속성 값을 검색할 수 있습니다.In earlier C# versions, to ensure that the Main method waits for the completion of an asynchronous operation, you can retrieve the value of the Task<TResult>.Result property of the Task<TResult> instance that is returned by the corresponding async method. 값을 생성하지 않는 비동기 작업의 경우 Task.Wait 메서드를 호출할 수 있습니다.For asynchronous operations that don't produce a value, you can call the Task.Wait method. 언어 버전을 선택하는 방법에 대한 자세한 내용은 C# 언어 버전을 참조하세요.For information about how to select the language version, see C# language versioning.

C# 언어 사양C# language specification

자세한 내용은 C# 언어 사양Await 식 섹션을 참조하세요.For more information, see the Await expressions section of the C# language specification.

참조See also