# Migration Guide | Sentry for Dart

## [Migrating from `sentry` `8.x` to `sentry` `9.x`](https://docs.sentry.io/.md#migrating-from-sentry-8x-to-sentry-9x)

#### [Dart version](https://docs.sentry.io/.md#dart-version)

The required minimium Dart version is now `3.5.0`. This change allows us to use safer APIs and better support for features such as WASM compilation.

#### [API Removals and Renames](https://docs.sentry.io/.md#api-removals-and-renames)

* `LoadImagesListIntegration` has been renamed to `LoadNativeDebugImagesIntegration`.
* The `enableTracing` option has been removed. Use `options.traceSampleRate` or `options.tracesSampler` instead.
* `BeforeSendTransactionCallback` now has a `Hint` parameter.
* Usage of `dart:html` has been removed in favor of `package:web`. The SDK is now packaged with the `package:web` dependency for better interoperability with web APIs.
* The `segment` field from `SentryUser` has been removed.
* The old user feedback API has been removed and replaced by `Sentry.captureFeedback`.

#### [Logging](https://docs.sentry.io/.md#logging)

The default log level is now `warning` when `debug = true`. This can be adjusted by setting `options.diagnosticLevel = SentryLevel.info` in `Sentry.init`.

#### [SDK Data Classes](https://docs.sentry.io/.md#sdk-data-classes)

SDK data classes are now mutable which makes it easier to manipulate them. For backwards-compatibility, `copyWith` and `clone` can still be used but are officially deprecated.

```dart
// old
options.beforeSend = (event, hint) {
  event = event.copyWith(release: 'my-release')
  return event
}

// new
options.beforeSend = (event, hint) {
  event.release = 'my-release'
  return event
}
```

#### [Response Body Handling](https://docs.sentry.io/.md#response-body-handling)

Due to PII concerns, response bodies will no longer be added to Sentry events by the SDK automatically. Responses are now attached to the `Hint` object, which can be read in `beforeSend`/`beforeSendTransaction` callbacks via `hint.response` so you can manually attach the response to your event. Response bodies with a size greater than 0.15MB are not added to the hint object. Currently as of version `9.0.0`, only the `dio` integration is supported.

## [Migrating From `sentry` `6.18.x` to `sentry` `7.0.0`](https://docs.sentry.io/.md#migrating-from-sentry-618x-to-sentry-700)

API changes:

* Sentry's Dart SDK version 7.0.0 and above requires Dart `2.17.0`.

* Sentry's `sentry_file` package version 7.0.0 and above requires Dart `2.19.0`.

* Methods that used to take a `dynamic hint` optional parameter now take `Hint? hint` instead.

* The following deprecated fields have been removed from the `SentryDevice` class and replaced:

  * `screenResolution` replaced with `screenHeightPixels` and `screenWidthPixels`.
  * `timezone` replaced with `SentryCulture#timezone`.
  * `language` replaced with `SentryCulture#locale`.
  * `theme` replaced with `SentryOperatingSystem#theme`.

* The following deprecated field has been removed from the `Contexts#dart_context` databag and replaced:
  * `isolate` replaced with `SentryThread#name`.

* The following fields have been removed from the `Scope` class and replaced:

  * `user(SentryUser? user)` replaced with `setUser(SentryUser? user)`.
  * `attachements` replaced with `attachments`.

* Classes or methods that used to take the below optional parameters, have been moved to the `SentryOptions` class and replaced:

  * `captureFailedRequests` replaced with `SentryOptions#captureFailedRequests`.
  * `sendDefaultPii` replaced with `SentryOptions#sendDefaultPii`.
  * `maxRequestBodySize` replaced with `SentryOptions#maxRequestBodySize`.
  * `networkTracing` replaced with `SentryOptions#tracesSampleRate` or `SentryOptions#tracesSampler`.
  * `recordBreadcrumbs` replaced with `SentryOptions#recordHttpBreadcrumbs`.

* The following `SentryMeasurementUnits` are now strongly typed:

  * `DurationSentryMeasurementUnit`
  * `InformationSentryMeasurementUnit`
  * `FractionSentryMeasurementUnit`
  * `CustomSentryMeasurementUnit`
  * `NoneSentryMeasurementUnit`

Behavior changes:

* Sentry's Dart SDK version 7.0.0 and above supports Dart `3.0.0`.
* When an unhandled error happens and there's a running transaction, the transaction status will be set to `internal_error`.
* The `captureFailedRequests` feature is now enabled by default.
* The `enableStructuredDataTracing` feature is now enabled by default.
* The `enableUserInteractionTracing` feature is now enabled by default.

## [Migrating From `sentry` `6.5.x` to `sentry` `6.6.x`](https://docs.sentry.io/.md#migrating-from-sentry-65x-to-sentry-66x)

* `SentryOptions#sendClientReports` is now enabled by default. To disable it, use the code snippet below:

```dart
import 'package:sentry/sentry.dart';

Future<void> main() async {
  await Sentry.init((options) => options.sendClientReports = false;
}
```

* The `Scope.user` setter was deprecated in favor of `Scope.setUser`, and it will be removed in a future update.

* The `Scope.attachements` getter was deprecated in favor of `attachments`, and it will be removed in a future update.

* The following `Scope` methods now return `Future<void>` instead of `void`:

  * `setContexts`
  * `removeContexts`
  * `setUser`
  * `addBreadcrumb`
  * `clearBreadcrumbs`
  * `setExtra`
  * `removeExtra`
  * `setTag`
  * `removeTag`

### [Sentry Self-hosted Compatibility](https://docs.sentry.io/.md#sentry-self-hosted-compatibility)

* Starting with version `6.6.0` of `sentry`, [Sentry's version >= v21.9.0](https://github.com/getsentry/self-hosted/releases.md) is required or you have to manually disable sending client reports via the `sendClientReports` option. This only applies to self-hosted Sentry. If you are using [sentry.io](https://sentry.io/.md), no action is needed.

## [Migrating From `sentry` `5.1.x` to `sentry` `6.0.0`](https://docs.sentry.io/.md#migrating-from-sentry-51x-to-sentry-600)

* `Sentry.currentHub` was removed. Please use the static methods on `Sentry`

* `SentryOptions.cacheDirSize` was renamed to `SentryOptions.maxCacheItems`

* `EventProcessor` was changed from a callback to an interface

* The data type from the following options was changed from `int` to `Duration`. The old options are still present but deprecated and will be removed in a future version.

  * `SentryOptions.autoSessionTrackingIntervalMillis` to `SentryOptions.autoSessionTrackingInterval`
  * `SentryOptions.anrTimeoutIntervalMillis` to `SentryOptions.anrTimeoutInterval`

* The `beforeSend` callback now accepts async code. The method signature changed from `SentryEvent? Function(SentryEvent event, {dynamic hint});` to `FutureOr<SentryEvent?> Function(SentryEvent event, {dynamic hint});`. While this is technically a breaking change, your code probably is still valid.

* Sentry accepts multiple exceptions and multiple threads. If you haven't set exceptions, there's no need to do anything.

### [Sentry Self-hosted Compatibility](https://docs.sentry.io/.md#sentry-self-hosted-compatibility-1)

* Starting with version `6.0.0` of the `sentry`, [Sentry's version >= v20.6.0](https://github.com/getsentry/self-hosted/releases.md) is required. This only applies to self-hosted Sentry. If you are using [sentry.io](https://sentry.io/.md), no action is needed.

## [Migrating From `sentry` `4.0.x` to `sentry` `5.0.0`](https://docs.sentry.io/.md#migrating-from-sentry-40x-to-sentry-500)

* Sentry's Dart SDK version 5.0.0 and above requires Dart 1.12.0

* Fix: Prefix classes with Sentry

  * A couple of classes were often conflicting with user's code. As a result, this change renames the following classes:

    * `App` -> `SentryApp`
    * `Browser` -> `SentryBrowser`
    * `Device` -> `SentryDevice`
    * `Gpu` -> `SentryGpu`
    * `Integration` -> `SentryIntegration`
    * `Message` -> `SentryMessage`
    * `OperatingSystem` -> `SentryOperatingSystem`
    * `Orientation` -> `SentryOrientation`
    * `Request` -> `SentryRequest`
    * `User` -> `SentryUser`

* Return type of `Sentry.close()` changed from `void` to `Future<void>` and `Integration.close()` changed from `void` to `FutureOr<void>`
