This tutorial teaches you how to write asynchronous code using futures and theasync andawait keywords. Using embedded DartPad editors, you can test your knowledge by running example code and completing exercises.

To get the most out of this tutorial, you should have the following:

• Knowledge ofbasic Dart syntax.
• Some experience writing asynchronous code in another language.
• Thediscarded_futures andunawaited_futures lints enabled.

This tutorial covers the following material:

• How and when to use theasync andawait keywords.
• How usingasync andawait affects execution order.
• How to handle errors from an asynchronous call usingtry-catch expressions inasync functions.

Estimated time to complete this tutorial: 40-60 minutes.

The exercises in this tutorial have partially completed code snippets. You can use DartPad to test your knowledge by completing the code and clicking theRun button.Don't edit the test code in themain function or below.

If you need help, expand theHint orSolution dropdown after each exercise.

Asynchronous operations let your program complete work while waiting for another operation to finish. Here are some common asynchronous operations:

• Fetching data over a network.
• Writing to a database.
• Reading data from a file.

Such asynchronous computations usually provide their result as aFuture or, if the result has multiple parts, as aStream. These computations introduce asynchrony into a program. To accommodate that initial asynchrony, other plain Dart functions also need to become asynchronous.

To interact with these asynchronous results, you can use theasync andawait keywords. Most asynchronous functions are just async Dart functions that depend, possibly deep down, on an inherently asynchronous computation.

The following example shows the wrong way to use an asynchronous function (fetchUserOrder()). Later you'll fix the example usingasync andawait. Before running this example, try to spot the issue -- what do you think the output will be?

// This example shows how *not* to write asynchronous Dart code.String createOrderMessage() {  var order = fetchUserOrder();  return 'Your order is: $order';}Future<String> fetchUserOrder() =>    // Imagine that this function is more complex and slow.    Future.delayed(const Duration(seconds: 2), () => 'Large Latte');void main() {  print(createOrderMessage());}

Here's why the example fails to print the value thatfetchUserOrder() eventually produces:

• fetchUserOrder() is an asynchronous function that, after a delay, provides a string that describes the user's order: a "Large Latte".
• To get the user's order,createOrderMessage() should callfetchUserOrder() and wait for it to finish. BecausecreateOrderMessage() doesnot wait forfetchUserOrder() to finish,createOrderMessage() fails to get the string value thatfetchUserOrder() eventually provides.
• Instead,createOrderMessage() gets a representation of pending work to be done: an uncompleted future. You'll learn more about futures in the next section.
• BecausecreateOrderMessage() fails to get the value describing the user's order, the example fails to print "Large Latte" to the console, and instead prints "Your order is: Instance of '_Future<String>'".

In the next sections you'll learn about futures and about working with futures (usingasync andawait) so that you'll be able to write the code necessary to makefetchUserOrder() print the desired value ("Large Latte") to the console.

A future (lower case "f") is an instance of theFuture (capitalized "F") class. A future represents the result of an asynchronous operation, and can have two states: uncompleted or completed.

When you call an asynchronous function, it returns an uncompleted future. That future is waiting for the function's asynchronous operation to finish or to throw an error.

If the asynchronous operation succeeds, the future completes with a value. Otherwise, it completes with an error.

A future of typeFuture<T> completes with a value of typeT. For example, a future with typeFuture<String> produces a string value. If a future doesn't produce a usable value, then the future's type isFuture<void>.

If the asynchronous operation performed by the function fails for any reason, the future completes with an error.

In the following example,fetchUserOrder() returns a future that completes after printing to the console. Because it doesn't return a usable value,fetchUserOrder() has the typeFuture<void>. Before you run the example, try to predict which will print first: "Large Latte" or "Fetching user order...".

Future<void> fetchUserOrder() {  // Imagine that this function is fetching user info from another service or database.  return Future.delayed(const Duration(seconds: 2), () => print('Large Latte'));}void main() {  fetchUserOrder();  print('Fetching user order...');}

In the preceding example, even thoughfetchUserOrder() executes before theprint() call on line 8, the console shows the output from line 8("Fetching user order...") before the output fromfetchUserOrder() ("Large Latte"). This is becausefetchUserOrder() delays before it prints "Large Latte".

Run the following example to see how a future completes with an error. A bit later you'll learn how to handle the error.

Future<void> fetchUserOrder() {  // Imagine that this function is fetching user info but encounters a bug.  return Future.delayed(    const Duration(seconds: 2),    () => throw Exception('Logout failed: user ID is invalid'),  );}void main() {  fetchUserOrder();  print('Fetching user order...');}

In this example,fetchUserOrder() completes with an error indicating that the user ID is invalid.

You've learned about futures and how they complete, but how do you use the results of asynchronous functions? In the next section you'll learn how to get results with theasync andawait keywords.

Theasync andawait keywords provide a declarative way to define asynchronous functions and use their results. Remember these two basic guidelines when usingasync andawait:

• To define an async function, addasync before the function body:
• Theawait keyword works only inasync functions.

Here's an example that convertsmain() from a synchronous to asynchronous function.

First, add theasync keyword before the function body:

voidmain()async{···}

If the function has a declared return type, then update the type to beFuture<T>, whereT is the type of the value that the function returns. If the function doesn't explicitly return a value, then the return type isFuture<void>:

Future<void>main()async{···}

Now that you have anasync function, you can use theawait keyword to wait for a future to complete:

print(awaitcreateOrderMessage());

As the following two examples show, theasync andawait keywords result in asynchronous code that looks a lot like synchronous code. The only differences are highlighted in the asynchronous example, which—if your window is wide enough—is to the right of the synchronous example.

StringcreateOrderMessage(){varorder=fetchUserOrder();return'Your order is:$order';}​Future<String>fetchUserOrder()=>// Imagine that this function is// more complex and slow.Future.delayed(constDuration(seconds:2),()=>'Large Latte');​voidmain(){print('Fetching user order...');print(createOrderMessage());}

Fetching user order...Your order is: Instance of 'Future<String>'

As shown in following two examples, it operates like synchronous code.

Future<String>createOrderMessage()async{varorder=awaitfetchUserOrder();return'Your order is:$order';}​Future<String>fetchUserOrder()=>// Imagine that this function is// more complex and slow.Future.delayed(constDuration(seconds:2),()=>'Large Latte');​Future<void>main()async{print('Fetching user order...');print(awaitcreateOrderMessage());}

Fetching user order...Your order is: Large Latte

The asynchronous example is different in three ways:

• The return type forcreateOrderMessage() changes fromString toFuture<String>.
• Theasync keyword appears before the function bodies forcreateOrderMessage() andmain().
• Theawait keyword appears before calling the asynchronous functionsfetchUserOrder() andcreateOrderMessage().

Anasync function runs synchronously until the firstawait keyword. This means that within anasync function body, all synchronous code before the firstawait keyword executes immediately.

Run the following example to see how execution proceeds within anasync function body. What do you think the output will be?

Future<void> printOrderMessage() async {  print('Awaiting user order...');  var order = await fetchUserOrder();  print('Your order is: $order');}Future<String> fetchUserOrder() {  // Imagine that this function is more complex and slow.  return Future.delayed(const Duration(seconds: 4), () => 'Large Latte');}void main() async {  countSeconds(4);  await printOrderMessage();}// You can ignore this function - it's here to visualize delay time in this example.void countSeconds(int s) {  for (var i = 1; i <= s; i++) {    Future.delayed(Duration(seconds: i), () => print(i));  }}

After running the code in the preceding example, try reversing lines 2 and 3:

varorder=awaitfetchUserOrder();print('Awaiting user order...');

Notice that timing of the output shifts, now thatprint('Awaiting user order') appears after the firstawait keyword inprintOrderMessage().

The following exercise is a failing unit test that contains partially completed code snippets. Your task is to complete the exercise by writing code to make the tests pass. You don't need to implementmain().

To simulate asynchronous operations, call the following functions, which are provided for you:

Add code to thereportUserRole() function so that it does the following:

• Returns a future that completes with the following string:"User role: <user role>"
  • Note: You must use the actual value returned byfetchRole(); copying and pasting the example return value won't make the test pass.
  • Example return value:"User role: tester"
• Gets the user role by calling the provided functionfetchRole().

Implement anasync functionreportLogins() so that it does the following:

• Returns the string"Total number of logins: <# of logins>".
  • Note: You must use the actual value returned byfetchLoginAmount(); copying and pasting the example return value won't make the test pass.
  • Example return value fromreportLogins():"Total number of logins: 57"
• Gets the number of logins by calling the provided functionfetchLoginAmount().

// Part 1// Call the provided async function fetchRole()// to return the user role.Future<String> reportUserRole() async {  // TODO: Implement the reportUserRole function here.}// Part 2// TODO: Implement the reportLogins function here.// Call the provided async function fetchLoginAmount()// to return the number of times that the user has logged in.reportLogins() {}// The following functions those provided to you to simulate// asynchronous operations that could take a while.Future<String> fetchRole() => Future.delayed(_halfSecond, () => _role);Future<int> fetchLoginAmount() => Future.delayed(_halfSecond, () => _logins);// The following code is used to test and provide feedback on your solution.// There is no need to read or modify it.void main() async {  print('Testing...');  List<String> messages = [];  const passed = 'PASSED';  const testFailedMessage = 'Test failed for the function:';  const typoMessage = 'Test failed! Check for typos in your return value';  try {    messages      ..add(_makeReadable(          testLabel: 'Part 1',          testResult: await _asyncEquals(            expected: 'User role: administrator',            actual: await reportUserRole(),            typoKeyword: _role,          ),          readableErrors: {            typoMessage: typoMessage,            'null':                'Test failed! Did you forget to implement or return from reportUserRole?',            'User role: Instance of \'Future<String>\'':                '$testFailedMessage reportUserRole. Did you use the await keyword?',            'User role: Instance of \'_Future<String>\'':                '$testFailedMessage reportUserRole. Did you use the await keyword?',            'User role:':                '$testFailedMessage reportUserRole. Did you return a user role?',            'User role: ':                '$testFailedMessage reportUserRole. Did you return a user role?',            'User role: tester':                '$testFailedMessage reportUserRole. Did you invoke fetchRole to fetch the user\'s role?',          }))      ..add(_makeReadable(          testLabel: 'Part 2',          testResult: await _asyncEquals(            expected: 'Total number of logins: 42',            actual: await reportLogins(),            typoKeyword: _logins.toString(),          ),          readableErrors: {            typoMessage: typoMessage,            'null':                'Test failed! Did you forget to implement or return from reportLogins?',            'Total number of logins: Instance of \'Future<int>\'':                '$testFailedMessage reportLogins. Did you use the await keyword?',            'Total number of logins: Instance of \'_Future<int>\'':                '$testFailedMessage reportLogins. Did you use the await keyword?',            'Total number of logins: ':                '$testFailedMessage reportLogins. Did you return the number of logins?',            'Total number of logins:':                '$testFailedMessage reportLogins. Did you return the number of logins?',            'Total number of logins: 57':                '$testFailedMessage reportLogins. Did you invoke fetchLoginAmount to fetch the number of user logins?',          }))      ..removeWhere((m) => m.contains(passed))      ..toList();    if (messages.isEmpty) {      print('Success. All tests passed!');    } else {      messages.forEach(print);    }  } on UnimplementedError {    print(        'Test failed! Did you forget to implement or return from reportUserRole?');  } catch (e) {    print('Tried to run solution, but received an exception: $e');  }}const _role = 'administrator';const _logins = 42;const _halfSecond = Duration(milliseconds: 500);// Test helpers.String _makeReadable({  required String testResult,  required Map<String, String> readableErrors,  required String testLabel,}) {  if (readableErrors.containsKey(testResult)) {    var readable = readableErrors[testResult];    return '$testLabel $readable';  } else {    return '$testLabel $testResult';  }}// Assertions used in tests.Future<String> _asyncEquals({  required String expected,  required dynamic actual,  required String typoKeyword,}) async {  var strActual = actual is String ? actual : actual.toString();  try {    if (expected == actual) {      return 'PASSED';    } else if (strActual.contains(typoKeyword)) {      return 'Test failed! Check for typos in your return value';    } else {      return strActual;    }  } catch (e) {    return e.toString();  }}

Future<String>reportUserRole()async{finalusername=awaitfetchRole();return'User role:$username';}​Future<String>reportLogins()async{finallogins=awaitfetchLoginAmount();return'Total number of logins:$logins';}

To handle errors in anasync function, use try-catch:

try{print('Awaiting user order...');varorder=awaitfetchUserOrder();}catch(err){print('Caught error:$err');}

Within anasync function, you can writetry-catch clauses the same way you would in synchronous code.

Run the following example to see how to handle an error from an asynchronous function. What do you think the output will be?

Future<void> printOrderMessage() async {  try {    print('Awaiting user order...');    var order = await fetchUserOrder();    print(order);  } catch (err) {    print('Caught error: $err');  }}Future<String> fetchUserOrder() {  // Imagine that this function is more complex.  var str = Future.delayed(    const Duration(seconds: 4),    () => throw 'Cannot locate user order',  );  return str;}void main() async {  await printOrderMessage();}

The following exercise provides practice handling errors with asynchronous code, using the approach described in the previous section. To simulate asynchronous operations, your code will call the following function, which is provided for you:

Useasync andawait to implement an asynchronouschangeUsername() function that does the following:

• Calls the provided asynchronous functionfetchNewUsername() and returns its result.
  • Example return value fromchangeUsername():"jane_smith_92"
• Catches any error that occurs and returns the string value of the error.
  • You can use thetoString() method to stringify bothExceptions andErrors.

// TODO: Implement changeUsername here.changeUsername() {}// The following function is provided to you to simulate// an asynchronous operation that could take a while and// potentially throw an exception.Future<String> fetchNewUsername() =>    Future.delayed(const Duration(milliseconds: 500), () => throw UserError());class UserError implements Exception {  @override  String toString() => 'New username is invalid';}// The following code is used to test and provide feedback on your solution.// There is no need to read or modify it.void main() async {  final List<String> messages = [];  const typoMessage = 'Test failed! Check for typos in your return value';  print('Testing...');  try {    messages      ..add(_makeReadable(          testLabel: '',          testResult: await _asyncDidCatchException(changeUsername),          readableErrors: {            typoMessage: typoMessage,            _noCatch:                'Did you remember to call fetchNewUsername within a try/catch block?',          }))      ..add(_makeReadable(          testLabel: '',          testResult: await _asyncErrorEquals(changeUsername),          readableErrors: {            typoMessage: typoMessage,            _noCatch:                'Did you remember to call fetchNewUsername within a try/catch block?',          }))      ..removeWhere((m) => m.contains(_passed))      ..toList();    if (messages.isEmpty) {      print('Success. All tests passed!');    } else {      messages.forEach(print);    }  } catch (e) {    print('Tried to run solution, but received an exception: $e');  }}// Test helpers.String _makeReadable({  required String testResult,  required Map<String, String> readableErrors,  required String testLabel,}) {  if (readableErrors.containsKey(testResult)) {    final readable = readableErrors[testResult];    return '$testLabel $readable';  } else {    return '$testLabel $testResult';  }}Future<String> _asyncErrorEquals(Function fn) async {  final result = await fn();  if (result == UserError().toString()) {    return _passed;  } else {    return 'Test failed! Did you stringify and return the caught error?';  }}Future<String> _asyncDidCatchException(Function fn) async {  var caught = true;  try {    await fn();  } on UserError catch (_) {    caught = false;  }  if (caught == false) {    return _noCatch;  } else {    return _passed;  }}const _passed = 'PASSED';const _noCatch = 'NO_CATCH';

Future<String>changeUsername()async{try{returnawaitfetchNewUsername();}catch(err){returnerr.toString();}}

It's time to practice what you've learned in one final exercise. To simulate asynchronous operations, this exercise provides the asynchronous functionsfetchUsername() andlogoutUser():

Write the following:

• Write a functionaddHello() that takes a singleString argument.
• addHello() returns itsString argument preceded by'Hello '.
  Example:addHello('Jon') returns'Hello Jon'.

• Write a functiongreetUser() that takes no arguments.
• To get the username,greetUser() calls the provided asynchronous functionfetchUsername().
• greetUser() creates a greeting for the user by callingaddHello(), passing it the username, and returning the result.
  Example: IffetchUsername() returns'Jenny', thengreetUser() returns'Hello Jenny'.

• Write a functionsayGoodbye() that does the following:
  • Takes no arguments.
  • Catches any errors.
  • Calls the provided asynchronous functionlogoutUser().
• IflogoutUser() fails,sayGoodbye() returns any string you like.
• IflogoutUser() succeeds,sayGoodbye() returns the string'<result> Thanks, see you next time', where<result> is the string value returned by callinglogoutUser().

// Part 1addHello(String user) {}// Part 2// Call the provided async function fetchUsername()// to return the username.greetUser() {}// Part 3// Call the provided async function logoutUser()// to log out the user.sayGoodbye() {}// The following functions are provided to you to use in your solutions.Future<String> fetchUsername() => Future.delayed(_halfSecond, () => 'Jean');Future<String> logoutUser() => Future.delayed(_halfSecond, _failOnce);// The following code is used to test and provide feedback on your solution.// There is no need to read or modify it.void main() async {  const didNotImplement =      'Test failed! Did you forget to implement or return from';  final List<String> messages = [];  print('Testing...');  try {    messages      ..add(_makeReadable(          testLabel: 'Part 1',          testResult: await _asyncEquals(              expected: 'Hello Jerry',              actual: addHello('Jerry'),              typoKeyword: 'Jerry'),          readableErrors: {            _typoMessage: _typoMessage,            'null': '$didNotImplement addHello?',            'Hello Instance of \'Future<String>\'':                'Looks like you forgot to use the \'await\' keyword!',            'Hello Instance of \'_Future<String>\'':                'Looks like you forgot to use the \'await\' keyword!',          }))      ..add(_makeReadable(          testLabel: 'Part 2',          testResult: await _asyncEquals(              expected: 'Hello Jean',              actual: await greetUser(),              typoKeyword: 'Jean'),          readableErrors: {            _typoMessage: _typoMessage,            'null': '$didNotImplement greetUser?',            'HelloJean':                'Looks like you forgot the space between \'Hello\' and \'Jean\'',            'Hello Instance of \'Future<String>\'':                'Looks like you forgot to use the \'await\' keyword!',            'Hello Instance of \'_Future<String>\'':                'Looks like you forgot to use the \'await\' keyword!',            '{Closure: (String) => dynamic from Function \'addHello\': static.(await fetchUsername())}':                'Did you place the \'\$\' character correctly?',            '{Closure \'addHello\'(await fetchUsername())}':                'Did you place the \'\$\' character correctly?',          }))      ..add(_makeReadable(          testLabel: 'Part 3',          testResult: await _asyncDidCatchException(sayGoodbye),          readableErrors: {            _typoMessage:                '$_typoMessage. Did you add the text \'Thanks, see you next time\'?',            'null': '$didNotImplement sayGoodbye?',            _noCatch:                'Did you remember to call logoutUser within a try/catch block?',            'Instance of \'Future<String>\' Thanks, see you next time':                'Did you remember to use the \'await\' keyword in the sayGoodbye function?',            'Instance of \'_Future<String>\' Thanks, see you next time':                'Did you remember to use the \'await\' keyword in the sayGoodbye function?',          }))      ..add(_makeReadable(          testLabel: 'Part 3',          testResult: await _asyncEquals(              expected: 'Success! Thanks, see you next time',              actual: await sayGoodbye(),              typoKeyword: 'Success'),          readableErrors: {            _typoMessage:                '$_typoMessage. Did you add the text \'Thanks, see you next time\'?',            'null': '$didNotImplement sayGoodbye?',            _noCatch:                'Did you remember to call logoutUser within a try/catch block?',            'Instance of \'Future<String>\' Thanks, see you next time':                'Did you remember to use the \'await\' keyword in the sayGoodbye function?',            'Instance of \'_Future<String>\' Thanks, see you next time':                'Did you remember to use the \'await\' keyword in the sayGoodbye function?',            'Instance of \'_Exception\'':                'CAUGHT Did you remember to return a string?',          }))      ..removeWhere((m) => m.contains(_passed))      ..toList();    if (messages.isEmpty) {      print('Success. All tests passed!');    } else {      messages.forEach(print);    }  } catch (e) {    print('Tried to run solution, but received an exception: $e');  }}// Test helpers.String _makeReadable({  required String testResult,  required Map<String, String> readableErrors,  required String testLabel,}) {  String? readable;  if (readableErrors.containsKey(testResult)) {    readable = readableErrors[testResult];    return '$testLabel $readable';  } else if ((testResult != _passed) && (testResult.length < 18)) {    readable = _typoMessage;    return '$testLabel $readable';  } else {    return '$testLabel $testResult';  }}Future<String> _asyncEquals({  required String expected,  required dynamic actual,  required String typoKeyword,}) async {  final strActual = actual is String ? actual : actual.toString();  try {    if (expected == actual) {      return _passed;    } else if (strActual.contains(typoKeyword)) {      return _typoMessage;    } else {      return strActual;    }  } catch (e) {    return e.toString();  }}Future<String> _asyncDidCatchException(Function fn) async {  var caught = true;  try {    await fn();  } on Exception catch (_) {    caught = false;  }  if (caught == true) {    return _passed;  } else {    return _noCatch;  }}const _typoMessage = 'Test failed! Check for typos in your return value';const _passed = 'PASSED';const _noCatch = 'NO_CATCH';const _halfSecond = Duration(milliseconds: 500);String _failOnce() {  if (_logoutSucceeds) {    return 'Success!';  } else {    _logoutSucceeds = true;    throw Exception('Logout failed');  }}bool _logoutSucceeds = false;

StringaddHello(Stringuser)=>'Hello$user';​Future<String>greetUser()async{finalusername=awaitfetchUsername();returnaddHello(username);}​Future<String>sayGoodbye()async{try{finalresult=awaitlogoutUser();return'$result Thanks, see you next time';}catch(e){return'Failed to logout user:$e';}}

To catch common mistakes that arise while working with async and futures,enable the following lints:

• discarded_futures
• unawaited_futures

Congratulations, you've finished the tutorial! If you'd like to learn more, here are some suggestions for where to go next:

• Play withDartPad.
• Try anothertutorial.
• Learn more about futures and asynchronous code in Dart:
  • Streams tutorial: Learn how to work with a sequence of asynchronous events.
  • Concurrency in Dart: Understand and learn how to implement concurrency in Dart.
  • Asynchronous programming: Dive in to Dart's language and library support for asynchronous coding.
  • Dart videos from Google: Watch one or more of the videos about asynchronous coding.
• Get theDart SDK!