Migration Guide topic

Migration Guide

This document gathered all breaking changes and migrations requirement between versions.

Breaking versions

5.0.0

Summary

  • get and getUri in Dio has different signature.
  • DefaultHttpClientAdapter is now named IOHttpClientAdapter, and the platform independent adapter can be initiated by HttpClientAdapter() which is a factory method.
  • Adapters that extends HttpClientAdapter must now implements instead of extends.
  • DioError has separate constructors and all fields are annotated as final.
  • DioErrorType has different values.
  • Imports are split into new libraries:
    • dio/io.dart is for natives specific classes;
    • dio/browser.dart is for web specific classes.
  • connectTimeout, sendTimeout, and receiveTimeout are now Duration instead of int.

Details

get and getUri

 Future<Response<T>> get<T>(
   String path, {
+  Object? data,
   Map<String, dynamic>? queryParameters,
   Options? options,
   CancelToken? cancelToken,
   ProgressCallback? onReceiveProgress,
 });

 Future<Response<T>> getUri<T>(
   Uri uri, {
+  Object? data,
   Map<String, dynamic>? queryParameters,
   Options? options,
   CancelToken? cancelToken,
   ProgressCallback? onReceiveProgress,
 });

HttpClientAdapter

Before:

void initAdapter() {
  final dio = Dio();
  // For natives.
  dio.httpClientAdapter = DefaultHttpClientAdapter();
  // For web.
  dio.httpClientAdapter = BrowserHttpClientAdapter();
}

After:

void initAdapter() {
  final dio = Dio();
  // Universal adapter that create the adapter for the corresponding platform.
  dio.httpClientAdapter = HttpClientAdapter();
  // For natives.
  dio.httpClientAdapter = IOHttpClientAdapter();
  // For web.
  dio.httpClientAdapter = BrowserHttpClientAdapter();
}

Implementing HttpClientAdapter

Before:

class ExampleAdapter extends HttpClientAdapter { /* ... */ }

After:

class ExampleAdapter implements HttpClientAdapter { /* ... */ }

Const DioError

Before:

Never throwDioError() {
  final error = DioError(request: requestOptions, error: e);
  error.message = 'Custom message.';
  error.stackTrace = StackTrace.current;
  throw error;
}

After:

Never throwDioError() {
  DioError error = DioError(
    request: requestOptions,
    error: e,
    stackTrace: StackTrace.current
  );
  error = error.copyWith(message: 'Custom message.');
  throw error;
}

DioErrorType values update

Before After
N/A badCertificate
response badResponse
connectTimeout connectionTimeout
other unknown

Duration instead of int for timeouts

Before:

void request() {
  final dio = Dio(
    BaseOptions(
      connectTimeout: 5000,
      sendTimeout: 5000,
      receiveTimeout: 10000,
    ),
  );
}

After:

void request() {
  final dio = Dio(
    BaseOptions(
      connectTimeout: const Duration(seconds: 5),
      sendTimeout: const Duration(seconds: 5),
      receiveTimeout: const Duration(seconds: 10),
    ),
  );
}

4.0.0

Details

  1. Null safety support (Dart >= 2.12).
  2. The Interceptor APIs signature has changed.
  3. Rename options.merge to options.copyWith.
  4. Rename DioErrorType enums from uppercase to camel style.
  5. Delete dio.resolve and dio.reject APIs (use handler instead in interceptors).
  6. Class BaseOptions no longer inherits from Options class.
  7. Change requestStream type of HttpClientAdapter.fetch from Stream<List<int>> to Stream<Uint8List>.
  8. Download API: Add real uri and redirect information to headers.

Libraries

dio Migration Guide Plugins
A powerful HTTP client for Dart and Flutter, which supports global settings, Interceptors, FormData, aborting and canceling a request, files uploading and downloading, requests timeout, custom adapters, etc.