Rework Initialization #2227

bitsandfoxes · 2025-07-03T15:48:17Z

Fixes #2200
Required getsentry/sentry-dotnet#4322

Goal

As stated in the issue: The SDK needs to initializeable in two ways: self, and manual. Both these paths need to provide the same functionality.

Approach

Hide the .NET SDK static API by making it internal
Mirror the now hidden API into Sentry.Unity.SentrySdk - This way the Unity SDK can omit certain methods like the .NET SDKs Init
Hide the SentryInitialization.cs that is getting compiled with the game
Have all actual initialization - that includes platform specific configuration like scope sync - happen within the pre-compiled SDK.
The code that gets compiled with the game is strictly for setting up and calling Init. This allows users to call the same method.

Implementation Details

Hide the .NET SDK

This is done by conditionally making the .NET SDKs SentrySdks accessor internal getsentry/sentry-dotnet#4322
The .NET SDK now considers Unity as a platform and our very own .props allows us to conditionally set a constant.

Rename Rename `SentryUnity` to `SentrySdk`

Ideally, we'd only have one static API that allows for discoverability of what's available. This could either be SentrySdk or SentryUnity. I'm going with SentrySdk here as:

it's a smoother migration to fix usings. This change will require users to change them from using Sentry; to using Sentry.Unity. Which is still easier than having to go through every instance of calling into the SDK and change these from SentrySdk to SentryUnity.
it resides in the Sentry.Unity namespace and avoids conflicts. Attempting to access Sentry.SentrySdk.Capture will create an error Cannot access internal class 'SentrySdk' here.
- We're helping out here by adding a summary to the internal SentrySdk guiding users towards the right namespace

Make `Sentry.Unity.SentrySdk` a `partial` class

The Unity SDK version of SentrySdk is now split in two partial classes.

SentrySdk.cs is where the Unity SDK specific code resides and basically contains "overwritten" methods like Init, GetLastRunState.

SentrySdk.Dotnet.cs - TODO: This should be source generated and end up as SentrySdk.Dotnet.g.cs
The .NET SDK SentrySdk is now hidden and inaccessible. To give users access to the rest of the API we're putting all the rest of the static API in there hand have it forward the calls into the .NET SDK.

Hide the `.cs` scripts `SentryInitialization` and `SentryIntegrations`

Our package ships with io.sentry.asmdef which creates our own assembly for us within the game's project. This allows us to make these classes internal, but keep their name. They are now undiscoverable for users - and should have been so in the first place.

Changes to `SentryInitialization`

The SentryInitialization still receives the "first thing that happens when the game starts callback via the RuntimeLoad attribute. This allows us to set up the SDK all the way to be ready to be initialized. Instead of doing the actual initialization inside the script that gets compiled with the game, this now injects the platform specific configure calls into the SDK.

Add a static `SentryPlatformServices`

This is now the place that holds the injected platform specific configure callbacks and the IUnityInfo that we use to access version and platform specific code like IL2CPP runtime checks and backend calls for line number support.

We're setting these as the very first thing and can so guarantee that they are available, regardless whether the SDK auto-initializes or has the user call Init manually.

The PlatformServices stay on the options because

Ease of access
No global variable floating around somewhere that gets accessed from all kinds of places

Due to how things are getting initialized I had to add a SentryEditorPlatformSetUp that sets the UnityInfo by virtue of the InitializeOnLoadMethod attribute. This allows us to have access to this even during build time (no runtime initialization there) and we can keep requiring it on the SentryUnityOptions.

Move all initialization code into the SDK

Having the platform specific configure callbacks available via the SentryPlatformServices class allows us to call conditionally compiled code from within the pre-compiled SDK. All initialization paths funnel back together in that one Init call.

Migration Path

Unfortunately, this is a breaking change. As such, we need to provide a migration path. When updating the SDK users will face the following error on the console

Since we can modify the now internal SDK's <summary> we can already put some help there

IDEs like Rider will allow to automatically import the missing references

using Sentry;
using Sentry.Unity;

Things to follow up on

`using Sentry.Unity` vs. `using Sentry`

The entirety of the API is now discoverable within SentrySdk. but the namespace is split

Sentry - Contains the .NET SDK's types, i.e. SentryId
Sentry.Unity - Contains the static API

So users end up in situations where they need to always bring using Sentry.Unity and sometimes additionally need using Sentry. That was an issue before already, it's just something to be aware of.

Consider turning `IsEnabled` in the config window into `isSelfInitEnabled`

During build the SDK was opinionated regarding whether to bring a native SDK and tied setup and symbol upload to the isEnabled check. When we merged all option-configuration callbacks into one in #1888 the line already blurred.
And now, the SDK cannot reasonably be certain whether when it will be initialized at runtime. With this I think we have to consider

IsEnabled cannot be considered anymore
Is the symbol upload enabled -> upload symbols
Is the native support enabled -> add native SDK
On mobile: If IsEnabled and InitializationType.BuildTime -> setup native project

Source Generator for `Sentry.Dotnet`

Right now the Sentry.Dotnet.cs is created by hand. It forwards all calls to the now internal static API while omitting Init. This allows us to keep the Unity specific methods in the SentrySdk.cs file but it also requires us to manually update if and when the .NET SDK's public API changes.

Alternative (attempted) approaches

I gave extension members a try by bumping to C#14. But this cannot be consumed by the user's code.
Making only SentrySdk.Init methods internal. This somewhat works but gets us stuck in a place. We'd have the API split between SentryUnity.Init vs SentrySdk.Capture.
Going with SentryUnity as name for the type for the static API. But - and that's an assumption on my part - that would break the actual calls from SentrySdk.CaptureException() SentryUnity.CaptureException() instead of having the IDE fix the usings and be done with it.
Adding the Unity SDK init to the Sentry namespace. This did not work for conflicting reasons.

bitsandfoxes · 2025-07-07T14:40:12Z

package-dev/Runtime/SentryUserFeedback.cs

            {
                // Since there is no screenshot added we can capture the feedback right away
-                SentryUnity.CaptureFeedback(_description.text, _email.text, _name.text, addScreenshot: false);
+                SentrySdk.CaptureFeedback(_description.text, _email.text, _name.text, addScreenshot: false);


This is the desired effect. All things reside within SentrySdk.

bitsandfoxes · 2025-07-07T14:45:18Z

package-dev/Runtime/SentryInitialization.cs

 namespace Sentry.Unity
 {
-    public static class SentryInitialization
+    internal static class SentryInitialization


We can safely make this internal. The SDK ships with it's own .asmdef that allows us to hide internal types from the user.

bitsandfoxes · 2025-07-07T14:47:23Z

src/Sentry.Unity/NativeUtils/SentryPlatformServices.cs

@@ -0,0 +1,15 @@
+using System;
+
+namespace Sentry.Unity.NativeUtils;


Putting the services into a very distinctive namespace to "discourage" usage.

bitsandfoxes · 2025-07-07T14:48:05Z

src/Sentry.Unity/ScriptableSentryUnityOptions.cs

    /// Used for loading the SentryUnityOptions from the ScriptableSentryUnityOptions during runtime.
    /// </remarks>
-    public static SentryUnityOptions? LoadSentryUnityOptions(ISentryUnityInfo unityInfo)
+    public static SentryUnityOptions? LoadSentryUnityOptions()


We no longer need to provide the IUnityInfo since these are getting set up during startup as part of the new platform services that are statically available.

bitsandfoxes · 2025-07-07T14:48:56Z

src/Sentry.Unity/SentrySdk.Dotnet.cs

This should get source generated in a follow up PR.

That's a better approach than the test I recommended 👍

bitsandfoxes · 2025-07-07T14:50:29Z

src/Sentry.Unity/SentryUnitySdk.cs

        }

-        unitySdk._dotnetSdk = SentrySdk.Init(options);
+        unitySdk._dotnetSdk = Sentry.SentrySdk.Init(options);


A drawback is that we now need to fully qualify calls through the static API from within the Unity SDK. But our users won't have that problem.

bitsandfoxes · 2025-07-07T14:51:23Z

test/Sentry.Unity.Tests/ContextWriterTests.cs

        // act
        MainThreadData.SentrySystemInfo = sysInfo;
-        SentryUnity.Init(options);
+        SentrySdk.Init(options);


No more separation between SentryUnity and SentrySdk.

…try-unity into fix/initialization

bruno-garcia

Sorry I didn't notice this before but while in general I think this is a great approach, we now expect the static fields to be set before our public methods are called but we don't verify anywhere that's the case and we have a lot of null propagation patterns which hinder the ability to debug what was going on. In particular when customers change the init code, possibly bypassing our auto init/static property set in order to do things "by hand".

CHANGELOG.md

src/Sentry.Unity.Native/SentryNative.cs

src/Sentry.Unity.Native/SentryNativeBridge.cs

src/Sentry.Unity.iOS/SentryNativeCocoa.cs

bruno-garcia · 2025-07-10T19:27:22Z

src/Sentry.Unity/SentrySdk.Dotnet.cs

That's a better approach than the test I recommended 👍

Co-authored-by: Bruno Garcia <bruno@brunogarcia.com>

bruno-garcia

I have some QOL suggestions but in general lgtm!

src/Sentry.Unity/NativeUtils/SentryPlatformServices.cs

src/Sentry.Unity/SentryUnityOptions.cs

bruno-garcia · 2025-07-12T02:54:56Z

src/Sentry.Unity/SentryUnitySdk.cs

        if (options.NativeContextWriter is { } contextWriter)
        {
-            SentrySdk.ConfigureScope((scope) =>
+            Sentry.SentrySdk.CurrentHub.ConfigureScope((scope) =>


You can add to the top (or via csproj iirc): using Sntry = Sentry.SentrySdk and use only Sntry throughout the file/project

This will lead to ambiguous references for the namespace Sentry.Unity - between Sentry and SentrySdk.

Could Sntry, without e (as Bruno suggested) work though?

…try-unity into fix/initialization

initial working implementation

14427b6

bitsandfoxes changed the title ~~initial working implementation~~ Rework Initialization Jul 3, 2025

bitsandfoxes added 5 commits July 4, 2025 13:10

fixed using in smoketester

bb4dbc0

we actually need both. idk if that's great. doesn't look great

0f97f0b

bumped .NET to have the comment

a76e957

Updated CHANGELOG.md

e494279

bumped to cleaned up version of .NET

df211a3

bitsandfoxes mentioned this pull request Jul 7, 2025

ref: Support Unity as a platfom getsentry/sentry-dotnet#4322

Merged

bitsandfoxes added 2 commits July 7, 2025 16:31

added services logging to init

19c4e78

added summary to platformservices

00e788a

bitsandfoxes commented Jul 7, 2025

View reviewed changes

bitsandfoxes added 3 commits July 7, 2025 16:43

fixed namespaces

bfcd0f1

cleaned up bugfarmbuttons

4448334

namespace clean followup

232833c

bitsandfoxes commented Jul 7, 2025

View reviewed changes

bitsandfoxes added 8 commits July 7, 2025 17:08

fixed qualification

bcbb551

moved scenetracing integration into the SDK

deb6aa7

updated CI to 2020

a66a5a6

env bump

857e492

removed now redundant test

eefad70

bumped uniy-of-bugs to 2020

16c9fcf

updated the package

6542706

removed now redundant asmdef

b48e60d

bitsandfoxes mentioned this pull request Jul 8, 2025

Drop support for Unity 2019 #2231

Merged

Updated CHANGELOG.md

76e05b2

bitsandfoxes added 2 commits July 10, 2025 16:50

Merge branch 'chore/cleanup-init' into fix/initialization

99bbb4d

Merge branch 'fix/initialization' of https://github.com/getsentry/sen…

d67b2b9

…try-unity into fix/initialization

bitsandfoxes requested review from Flash0ver, bruno-garcia and vaind July 10, 2025 14:52

bruno-garcia reviewed Jul 10, 2025

View reviewed changes

Update CHANGELOG.md

ac366e7

Co-authored-by: Bruno Garcia <bruno@brunogarcia.com>

Base automatically changed from chore/cleanup-init to main July 11, 2025 12:46

bitsandfoxes and others added 3 commits July 11, 2025 14:51

merged main

76868b8

hold platformservices in options and handle tests

1f520ee

Format code

a47872d

bruno-garcia approved these changes Jul 12, 2025

View reviewed changes

bitsandfoxes and others added 14 commits July 14, 2025 11:53

reworked the platform services into the options and fixed the tests

e18de6e

Format code

d0711f6

provide test fallback for platform services

e55eae6

Merge branch 'fix/initialization' of https://github.com/getsentry/sen…

f3af761

…try-unity into fix/initialization

sadly, need an editor hook otherwise unhappy times ahead

cab093a

updated snapshot

5f4438d

testplatfromservices are needed

888b28e

editor stuff needs its own asmdef

4a94b1a

need the asmdef in the 'package' due to name

6c72a82

updated snapshot

a7ecd95

fix meta files

fb5ef3d

another round of fixing asmdefs

e15752f

added the dev.runtime.asmdef.meta because now it's getting referenced

febcf57

too eager with removing the check

c2b35be

bitsandfoxes merged commit 2b21990 into main Jul 15, 2025
140 of 141 checks passed

bitsandfoxes deleted the fix/initialization branch July 15, 2025 06:26

This was referenced Jul 21, 2025

MainThreadData.CollectData is getting called twice #2247

Closed

Logging is getting set up twice #2248

Closed

		@@ -0,0 +1,15 @@
		using System;

		namespace Sentry.Unity.NativeUtils;

Uh oh!

Rework Initialization #2227

Rework Initialization #2227

Uh oh!

Conversation

bitsandfoxes commented Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Goal

Approach

Implementation Details

Hide the .NET SDK

Rename Rename SentryUnity to SentrySdk

Make Sentry.Unity.SentrySdk a partial class

Hide the .cs scripts SentryInitialization and SentryIntegrations

Changes to SentryInitialization

Add a static SentryPlatformServices

Move all initialization code into the SDK

Migration Path

Things to follow up on

using Sentry.Unity vs. using Sentry

Consider turning IsEnabled in the config window into isSelfInitEnabled

Source Generator for Sentry.Dotnet

Alternative (attempted) approaches

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bitsandfoxes Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bruno-garcia left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bruno-garcia left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

bitsandfoxes commented Jul 3, 2025 •

edited

Loading

Rename Rename `SentryUnity` to `SentrySdk`

Make `Sentry.Unity.SentrySdk` a `partial` class

Hide the `.cs` scripts `SentryInitialization` and `SentryIntegrations`

Changes to `SentryInitialization`

Add a static `SentryPlatformServices`

`using Sentry.Unity` vs. `using Sentry`

Consider turning `IsEnabled` in the config window into `isSelfInitEnabled`

Source Generator for `Sentry.Dotnet`

bitsandfoxes Jul 7, 2025 •

edited

Loading