Muokkaa

Jaa

Migrate from the HockeySDK to App Center Xamarin SDK

  • Artikkeli

Important

Visual Studio App Center is scheduled for retirement on March 31, 2025. While you can continue to use Visual Studio App Center until it is fully retired, there are several recommended alternatives that you may consider migrating to.

Learn more about support timelines and alternatives.

Follow this documentation if you're looking to update your application to use App Center SDK instead of HockeySDK.

1. Update the libraries

Replace HockeySDK.Xamarin NuGet package with App Center ones in all projects in your solution.

Visual Studio for Mac

  • Open Visual Studio for Mac.
  • Click File > Open and choose your solution.
  • In the solution navigator, right-click the Packages section, and choose Add NuGet packages....
  • Remove the HockeySDK.Xamarin package.
  • Search for App Center, and select App Center Analytics, App Center Crashes, and App Center Distribute.
  • Click Add Packages.

Visual Studio for Windows

  • Open Visual Studio for Windows.
  • Click File > Open and choose your solution.
  • In the solution navigator, right-click References and choose Manage NuGet Packages.
  • Remove the HockeySDK.Xamarin package.
  • Search for App Center, and install Microsoft.AppCenter.Analytics, Microsoft.AppCenter.Crashes, and Microsoft.AppCenter.Distribute packages.

Package Manager Console

  • Open the console in Visual Studio. To do this, choose Tools > NuGet Package Manager > Package Manager Console.
  • If you're working in Visual Studio for Mac, make sure you've installed NuGet Package Management Extensions. For this, choose Visual Studio > Extensions, search for NuGet and install, if necessary.
  • Type the following command in the console:
Uninstall-Package HockeySDK.Xamarin
Install-Package Microsoft.AppCenter.Analytics
Install-Package Microsoft.AppCenter.Crashes
Install-Package Microsoft.AppCenter.Distribute

The App Center SDK is designed with a modular approach – you can integrate only those services that you're interested in. Each SDK module needs to be added as a separate dependency in this section. See the equivalences in the next table:

HockeyApp class App Center module
MetricsManager Analytics
CrashManager Crashes
UpdateManager Distribute

2. Update the SDK setup code

2.1 Convert the application identifier

The App Center SDK uses application identifiers in the globally unique identifier (GUID) format. Your HockeyApp App ID can be used by App Center but you need to convert it to a different format. To convert the identifier you must add four hyphens to get 8-4-4-4-12 representation.

Before (HockeyApp): 00112233445566778899aabbccddeeff

After (App Center): 00112233-4455-6677-8899-aabbccddeeff

2.2 Replace SDK initialization in the application code

  1. Remove old HockeyApp registration code.

    • Xamarin.Android - Open the project's MainActivity.cs and remove the lines below:

      using HockeyApp.Android;

...

CrashManager.Register(this, "APP_IDENTIFIER");
MetricsManager.Register(Application, "APP_IDENTIFIER");
UpdateManager.Register(this, "APP_IDENTIFIER");

      Remove the following assembly level attribute in Properties/AssemblyInfo.cs:

      [assembly: MetaData ("net.hockeyapp.android.appIdentifier", Value="APP_IDENTIFIER")]

    • Xamarin.iOS - Open the project's AppDelegate.cs and remove the lines below:

      using HockeyApp.iOS;

...

var manager = BITHockeyManager.SharedHockeyManager;
manager.Configure("APP_IDENTIFIER");
manager.StartManager();
manager.Authenticator.AuthenticateInstallation();

  2. Start the App Center SDK

    • The initialization code mentioned later in this section requires adding the following lines below the existing using statements:
    using Microsoft.AppCenter;
using Microsoft.AppCenter.Analytics;
using Microsoft.AppCenter.Crashes;
using Microsoft.AppCenter.Distribute;

    Xamarin.Android:

    Open the project's MainActivity.cs file and add the Start() call inside the OnCreate() method

    AppCenter.Start("{Your App Secret}", typeof(Analytics), typeof(Crashes), typeof(Distribute));

    Note

    If your application has background services or multiple entry points like a broadcast receiver, exported activities or content providers, it's recommended to start AppCenter in the Application.OnCreate callback instead.

    Xamarin.iOS:

    Open the project's AppDelegate.cs file and add the Start() call inside the FinishedLaunching() method

    AppCenter.Start("{Your App Secret}", typeof(Analytics), typeof(Crashes), typeof(Distribute));

    Note

    If using Crashes, you must call this method in the UI/main thread and avoid starting background tasks until the Start method returns. The reason is that any null reference exception caught from another thread while Crashes is initializing may trigger a native crash and ignore the catch clause. Once the AppCenter.Start method returns, it's safe to try/catch null reference exceptions again. You can read more about the cause of this timing issue in the Signals and third-party crash reporters article.

    Xamarin.Forms:

    To use a Xamarin.Forms application targeting iOS, Android and UWP platforms, you need to create three applications in the App Center portal - one for each platform. Creating three apps will give you three App secrets - one for each. Open the project's App.xaml.cs file (or your class that inherits from Xamarin.Forms.Application) in your shared or portable project and add the method below in the OnStart() method.

    AppCenter.Start("ios={Your App Secret};android={Your App Secret}", typeof(Analytics), typeof(Crashes), typeof(Distribute));

    Important

    The curly braces is just to document that you must replace that content with the actual app secrets, don't put curly braces in the Start call.

    Note

    In case you're using the HockeyApp SDK for Android, make sure to initialize the HockeyApp SDK AFTER the App Center SDK. For your iOS application, it isn't possible to have more than one active crash reporting SDK in your app. Disable the other SDKs' crash reporting functionality to make sure App Center can catch the crashes.

    Note

    The notes from both the previous sections about iOS and Android apply to Xamarin.Forms as well. If those remarks apply to your application, you might need to initialize AppCenter in different places per platform.

  3. [For distribute iOS only] Modify the project's Info.plist file

    • Add a new key for URL types or CFBundleURLTypes in your Info.plist file (in case Xcode displays your Info.plist as source code).
    • Change the key of the first child item to URL Schemes or CFBundleURLSchemes.
    • Enter appcenter-${Your App Secret} as the URL scheme and replace ${Your App Secret} with the App Secret of your app.

    For more information on this, refer to App Center Distribute documentation.

  4. Replace all HockeyApp API calls throughout the application. The detailed API mapping tables are given below.

3. Services and feature comparison

Core

Feature HockeyApp App Center
Adjust the log level SharedHockeyManager.LogLevel (iOS) or HockeyLog.LogLevel (Android) AppCenter.LogLevel
Identify installations iOS only AppCenter.GetInstallIdAsync
Identify users Crash only AppCenter.SetUserId

Analytics

Feature HockeyApp App Center
Automatically track sessions Yes, can be disabled only on Android Documentation (can't be disabled)
Custom events with properties HockeyApp.MetricsManager.TrackEvent Analytics.TrackEvent
Disable service at runtime MetricsManager.DisableUserMetrics (Android) or SharedHockeyManager.DisableMetricsManager (iOS) Analytics.SetEnabledAsync

Crashes

Feature HockeyApp App Center
Automatically send crashes Disabled by default Documentation (enabled by default)
Generate a test crash CrashManager.GenerateTestCrash (iOS Only) Crashes.GenerateTestCrash
Attach additional meta data Yes Documentation (can be attached from listener)
Customize user dialog Yes Documentation (not provided by default)
Get info about the sending status Android only Documentation
Info about a previous crash CrashManager.GetLastCrashDetails (Android) or CrashManager.LastSessionCrashDetails (iOS) Crashes.GetLastSessionCrashReportAsync
Disable service at runtime SharedHockeyManager.DisableCrashManager (iOS only) Crashes.SetEnabledAsync

Distribute

Note

Unlike in HockeyApp, App Center in-app updates feature only works with RELEASE builds (by default) that are distributed using the App Center Distribute service. If the app is using a private distribution group, once the app is installed and opened for the first time after the App Center Distribute SDK has been added, a browser will open to authenticate the user and enable in-app updates. This browser will also open if you set the private in-app update track at runtime. This is a ONE-TIME step that won't occur for subsequent releases of your app. Refer to the App Center Distribute Documentation for more details.

Feature HockeyApp App Center
Restricted in-app updates LoginManager.VerifyLogin (Android) or Authenticator.AuthenticateInstallation (iOS) Distribute.UpdateTrack
Disable service at runtime UpdateManager.Unregister (Android) or SharedHockeyManager.DisableUpdateManager (iOS) Distribute.SetEnabledAsync
Customize the update dialog Yes Distribute.ReleaseAvailable

Feedback Service

The feedback service won't be supported in App Center. See HockeyApp feedback.