通过

从 HockeySDK 迁移到 App Center Xamarin SDK

  • 项目

重要

Visual Studio App Center 计划于 2025 年 3 月 31 日停用。 虽然可以继续使用 Visual Studio App Center，直到它完全停用，但你可以考虑迁移到几个建议的替代方法。

详细了解支持时间线和替代方案。

如果要更新应用程序以使用 App Center SDK 而不是 HockeySDK，请遵循此文档。

1. 更新库

将 HockeySDK.Xamarin NuGet 包替换为解决方案中所有项目中的 App Center 包。

Visual Studio for Mac

  • 打开 Visual Studio for Mac。
  • 单击“ 文件>打开 ”并选择解决方案。
  • 在解决方案导航器中，右键单击“ 包” 部分，然后选择 “添加 NuGet 包...”。
  • 删除 HockeySDK.Xamarin 包。
  • 搜索 “App Center”，然后选择“ App Center Analytics”、“ App Center 崩溃”和 “App Center 分发”。
  • 单击“ 添加包”。

适用于 Windows 的 Visual Studio

  • 打开 Visual Studio for Windows。
  • 单击“ 文件>打开 ”并选择解决方案。
  • 在解决方案导航器中，右键单击“ 引用 ”，然后选择“ 管理 NuGet 包”。
  • 删除 HockeySDK.Xamarin 包。
  • 搜索 App Center，并安装 Microsoft.AppCenter.Analytics、 Microsoft.AppCenter.Crashes 和 Microsoft.AppCenter.Distribut 包。

程序包管理器控制台

  • 在 Visual Studio 中打开控制台。 为此，请选择 “工具”>“NuGet 包管理器>包管理器控制台”。
  • 如果使用的是 Visual Studio for Mac，请确保已安装 NuGet 包管理扩展。 为此，请选择 “Visual Studio>扩展”，搜索 “NuGet” 并根据需要安装。
  • 在控制台中键入以下命令：
Uninstall-Package HockeySDK.Xamarin
Install-Package Microsoft.AppCenter.Analytics
Install-Package Microsoft.AppCenter.Crashes
Install-Package Microsoft.AppCenter.Distribute

App Center SDK 采用模块化方法设计 - 只能集成感兴趣的服务。 在本部分中，需要将每个 SDK 模块添加为单独的依赖项。 请参阅下表中的等效项：

HockeyApp 类 App Center 模块
MetricsManager Analytics
CrashManager Crashes
UpdateManager Distribute

2.更新 SDK 设置代码

2.1 转换应用程序标识符

App Center SDK 使用全局唯一标识符 (GUID) 格式的应用程序标识符。 App Center 可以使用 HockeyApp 应用 ID，但需要将其转换为不同的格式。 若要转换标识符，必须添加四个连字符才能获取 8-4-4-4-12 表示形式。

在 (HockeyApp) 之前： 00112233445566778899aabbccddeeff

(App Center) 后： 00112233-4455-6677-8899-aabbccddeeff

2.2 替换应用程序代码中的 SDK 初始化

  1. 删除旧的 HockeyApp 注册代码。

    • Xamarin.Android - 打开项目的 MainActivity.cs 并删除以下行：

      using HockeyApp.Android;

...

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

      在 Properties/AssemblyInfo.cs 中删除以下程序集级别属性：

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

    • Xamarin.iOS - 打开项目的 AppDelegate.cs 并删除以下行：

      using HockeyApp.iOS;

...

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

  2. 启动 App Center SDK

    • 本节后面提到的初始化代码需要在现有 using 语句下方添加以下行：
    using Microsoft.AppCenter;
using Microsoft.AppCenter.Analytics;
using Microsoft.AppCenter.Crashes;
using Microsoft.AppCenter.Distribute;

    Xamarin.Android：

    打开项目的 MainActivity.cs 文件，并在 Start() 方法内 OnCreate() 添加调用

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

    注意

    如果应用程序具有后台服务或多个入口点（如广播接收器、导出的活动或内容提供程序），建议改为在回调中Application.OnCreate启动AppCenter。

    Xamarin.iOS：

    打开项目的 AppDelegate.cs 文件并在 方法内FinishedLaunching()添加Start()调用

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

    注意

    如果使用崩溃，则必须在 UI/main线程中调用此方法，并避免在方法返回之前Start启动后台任务。 原因是初始化崩溃时从另一个线程捕获的任何 null 引用异常都可能会触发本机崩溃并忽略 catch 子句。 AppCenter.Start方法返回后，可以安全地再次尝试/捕获 null 引用异常。 有关此计时问题的原因的详细信息，请参阅 信号和第三方崩溃报告者 一文。

    Xamarin.Forms：

    若要使用面向 iOS、Android 和 UWP 平台的 Xamarin.Forms 应用程序，需要在 App Center 门户中创建三个应用程序 - 每个平台一个应用程序。 创建三个应用将为你提供三个应用机密-每个机密一个。 (或从Xamarin.Forms.Application共享或可移植项目中的) 继承的类打开项目的App.xaml.cs文件，并在 方法中添加OnStart()以下方法。

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

    重要

    大括号只是为了记录你必须将该内容替换为实际应用机密，不要在调用中 Start 放置大括号。

    注意

    如果使用适用于 Android 的 HockeyApp SDK，请确保在 App Center SDK 之后 初始化 HockeyApp SDK。 对于 iOS 应用程序，应用中不能有多个活动故障报告 SDK。 禁用其他 SDK 的崩溃报告功能，以确保 App Center 可以捕获崩溃。

    注意

    前面两部分中有关 iOS 和 Android 的说明也适用于 Xamarin.Forms。 如果这些注释适用于应用程序，则可能需要在每个平台的不同位置初始化 AppCenter。

  3. [仅适用于分发 iOS]修改项目的 Info.plist 文件

    • 为 URL typesCFBundleURLTypesInfo.plist 文件添加新密钥， (以防 Xcode 将 Info.plist 显示为源代码) 。
    • 将第一个子项的键更改为 URL Schemes 或 CFBundleURLSchemes。
    • 输入 appcenter-${Your App Secret} 作为 URL 方案，并将 替换为 ${Your App Secret} 应用的“应用机密”。

    有关此内容的详细信息，请参阅 App Center 分发文档。

  4. 替换整个应用程序中的所有 HockeyApp API 调用。 下面提供了详细的 API 映射表。

3. 服务和功能比较

核心

功能 HockeyApp 应用中心
调整日志级别 SharedHockeyManager.LogLevel (iOS) 或 HockeyLog.LogLevel (Android) AppCenter.LogLevel
标识安装 仅限 iOS AppCenter.GetInstallIdAsync
标识用户 仅崩溃 AppCenter.SetUserId

分析

功能 HockeyApp 应用中心
自动跟踪会话 是，只能在 Android 上禁用 无法禁用文档 ()
具有属性的自定义事件 HockeyApp.MetricsManager.TrackEvent Analytics.TrackEvent
在运行时禁用服务 MetricsManager.DisableUserMetrics (Android) 或 SharedHockeyManager.DisableMetricsManager (iOS) Analytics.SetEnabledAsync

崩溃

功能 HockeyApp 应用中心
自动发送崩溃 默认情况下禁用 默认启用文档 ()
生成测试崩溃 CrashManager.GenerateTestCrash 仅 (iOS) Crashes.GenerateTestCrash
附加其他元数据 是 可以从侦听器) 附加文档 (
“自定义用户”对话框 是 默认情况下未提供文档 ()
获取有关发送状态的信息 仅限 Android 文档
有关上一次崩溃的信息 CrashManager.GetLastCrashDetails (Android) 或 CrashManager.LastSessionCrashDetails (iOS) Crashes.GetLastSessionCrashReportAsync
在运行时禁用服务 SharedHockeyManager.DisableCrashManager 仅) (iOS Crashes.SetEnabledAsync

分发

注意

与 HockeyApp 不同，App Center 应用内更新功能仅适用于 默认情况下 使用 App Center 分发 服务分发 () 版本。 如果应用使用的是专用通讯组，在添加 App Center 分发 SDK 后首次安装并打开应用后，浏览器将打开以对用户进行身份验证并启用应用内更新。 如果在运行时设置专用应用内更新跟踪，此浏览器也会打开。 这是一次性步骤，不会在应用的后续版本中发生。 有关更多详细信息，请参阅 App Center 分发文档 。

功能 HockeyApp 应用中心
受限的应用内更新 LoginManager.VerifyLogin (Android) 或 Authenticator.AuthenticateInstallation (iOS) Distribut.UpdateTrack
在运行时禁用服务 UpdateManager.Unregister (Android) 或 SharedHockeyManager.DisableUpdateManager (iOS) Distribut.SetEnabledAsync
自定义更新对话框 是 Distribut.ReleaseAvailable

反馈服务

App Center 不支持反馈服务。 请参阅 HockeyApp 反馈。