開始使用MAUI和 Xamarin

2025-05-05

這很重要

Visual Studio App Center 於 2025 年 3 月 31 日淘汰，但分析和診斷功能除外，這些功能將持續支援到 2026 年 6 月 30 日。瞭解更多資訊。

App Center SDK 使用模組化架構，因此您可以使用任何或所有服務。

讓我們開始在應用程式中設定 App Center .NET SDK，以使用 App Center 分析與 App Center 當機。若要將 App Center 分發新增至您的應用程式，請查看 App Center 分發的文件。

1.Prerequisites

開始之前，請確定您已符合下列必要條件：

您的專案是在Visual Studio或Visual Studio for Mac 中設定。
您是以執行 iOS 11.0 或更新版本或 Android 5.0（API 層級 21）或更新版本的裝置為目標。
您不會使用任何其他提供當機報告功能的 SDK。

支援的平臺：

MAUI iOS
MAUI Android
MAUI Windows
.NET 6.0 macOS
Xamarin.Android
Xamarin.iOS
Xamarin.Mac
Xamarin.Forms （iOS、macOS Android、UWP 和 Windows 桌面應用程式）

1.1 MAUI

備註

App Center 入口網站目前沒有 MAUI 平臺。請使用 Xamarin 來開發適用於 iOS 和 Android 的應用程式，並使用 UWP 來開發適用於 Windows 的應用程式。

1.2 關於 Xamarin.Android

在 App Center 入口網站上建立應用程式，並以 Android 作為作系統， 並以 Xamarin 作為平臺。

1.3 關於 Xamarin.iOS

在 App Center 入口網站上，使用 iOS 作為 OS 和 Xamarin 作為平臺來建立應用程式。

1.4 關於 Xamarin.Mac

在 App Center 入口網站上，使用 macOS 作為 OS 和 Xamarin 作為平臺來建立應用程式。

警告

已知問題可防止應用程式上傳至 App Store。遵循 github 上的進度。

1.5 關於 Xamarin.Forms （iOS、macOS、Android、UWP 和 Windows Desktop）

在 App Center 上建立 5 個應用程式 – 每個 OS 各一個。

您必須選取 Xamarin 作為 Android、iOS 和 macOS 應用程式的平臺（UWP 和桌面應用程式沒有 Xamarin 選項）。

針對 Windows 桌面 和 macOS 應用程式，您必須設定專案以與 Xamarin.Forms 平臺相容。

2.在 App Center 入口網站中建立您的應用程式，以取得應用程式秘密

如果您已在 App Center 入口網站中建立應用程式，您可以略過此步驟。

前往 appcenter.ms。
註冊或登入，並按入口網站右上角的藍色按鈕，顯示 [ 新增 ]，然後從下拉功能表中選取 [ 新增應用程式 ]。
輸入應用程式的名稱和選擇性描述。
根據您的項目選取適當的OS和平臺，如上所述。
按兩下右下角按鈕，顯示 [新增應用程式]。

建立應用程式之後，您可以在 App Center 入口網站的 [設定] 頁面上取得其應用程式秘密。在 [ 設定 ] 頁面右上角，按兩下 三個垂直點 ，然後選取 Copy app secret 以取得您的應用程式秘密。

3.將 App Center SDK 新增至您的解決方案

App Center SDK 可以使用 Visual Studio 或套件管理員控制台進行整合。

備註

App Center SDK 使用強名稱元件來與使用強名稱符號的應用程式相容。

Visual Studio for Mac

開啟 Visual Studio。
按兩下 [ 檔案>開啟 ]，然後選擇您的解決方案。
在方案導覽器中，以滑鼠右鍵按兩下 [ 套件 ] 區段，然後選擇 [ 新增 NuGet 套件...]。
搜尋 App Center，然後選取 [App Center 分析 ] 和 [App Center 當機]。
按兩下 [新增套件]。

Visual Studio for Windows

開啟 Visual Studio。
按兩下 [ 檔案>開啟 ]，然後選擇您的解決方案。
在方案導覽器中，以滑鼠右鍵按兩下 [ 參考 ]，然後選擇 [ 管理 NuGet 套件]。
搜尋 App Center，並安裝 Microsoft.AppCenter.Analytics 和 Microsoft.AppCenter.Crashes 套件。

套件管理員主控台

在 Visual Studio 中開啟控制台。若要這樣做，請選擇 [工具>][NuGet 套件管理員>套件管理員控制台]。
如果您在 Visual Studio for Mac 中工作，請確定您已安裝 NuGet 套件管理延伸模組。為此，請選擇 Visual Studio>延伸模組，視需要搜尋 NuGet 並安裝。
在控制台中輸入下列命令：

Install-Package Microsoft.AppCenter.Analytics
Install-Package Microsoft.AppCenter.Crashes

既然您已在應用程式中整合 SDK，現在可以啟動 SDK 並使用 App Center 服務。

備註

如果您在可攜式專案中使用App Center SDK（例如 Xamarin.Forms），則必須在每個項目中安裝套件：可攜式、Android 和iOS 套件。若要這樣做，您應該開啟每個子專案，並遵循 Visual Studio for Mac 或 Visual Studio for Windows 小節中所述的對應步驟。

4.啟動 SDK

若要使用 App Center，您必須選擇您想使用的模組。根據預設，不會啟動任何模組，而且您必須在啟動 SDK 時明確呼叫每個模組。

4.1 新增 using 語句

在下列檔案中新增適當的命名空間：

MAUI 和 Xamarin.Forms - App.xaml.cs
Xamarin.iOS 和 Xamarin.Mac - AppDelegate.cs
Xamarin.Android - MainActivity.cs

using Microsoft.AppCenter;
using Microsoft.AppCenter.Analytics;
using Microsoft.AppCenter.Crashes;

4.2 新增 `Start()` 方法

4.2.1 MAUI 和 Xamarin.Forms

您必須在 App Center 入口網站上為每個平臺建立不同的應用程式。針對每個應用程式，您將有不同的應用程式秘密。開啟專案的 App.xaml.cs 檔案，並在建構函式中新增下列這一行（或在 OnStart() Xamarin.Forms 的方法中）。

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

如果您需要個別啟動 App Center 服務，您應該：

使用應用程式密碼來設定或啟動它。
如果可以多次呼叫程式代碼，請檢查是否已設定App Center。
在沒有應用程式秘密的情況下啟動必要的服務。

AppCenter.Configure("ios={Your App Secret};macos={Your App Secret};android={Your App Secret};uwp={Your App Secret};windowsdesktop={Your App Secret}");
if (AppCenter.Configured)
{
    AppCenter.Start(typeof(Analytics));
    AppCenter.Start(typeof(Crashes));
}

4.2.2 Xamarin.Android

備註

如果您使用適用於 Android 的 HockeyApp SDK，請務必在 App Center SDK 之後初始化 HockeyApp SDK。

開啟專案的MainActivity.cs檔案，並在方法內Start()新增OnCreate()呼叫

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

備註

如果您的應用程式具有背景服務或多個進入點，例如廣播接收者、匯出的活動或內容提供者，建議您改為在AppCenter回呼中啟動Application.OnCreate。

4.2.3 Xamarin.iOS 和 Xamarin.Mac

備註

您無法在應用程式中有多個正在運作的崩潰報告 SDK。停用其他 SDK 損毀報告功能，以確保 App Center 可以攔截損毀。

開啟項目的AppDelegate.cs檔案，並在Start()方法內新增FinishedLaunching()呼叫

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

備註

如果使用崩潰功能，您必須在使用者介面/主執行緒中呼叫此方法，並避免在方法傳回 Start 之前啟動背景工作。原因是在崩潰正在初始化時，由另一個執行緒捕捉到的任何 Null 參考異常，都可能會觸發原生崩潰並忽略 catch 子句。 AppCenter.Start方法傳回之後，可以安全地再次嘗試/攔截 Null 參照異常。您可以在 Signals 和第三方當機記者文章中深入瞭解此計時問題的原因。

警告

不建議在原始碼中內嵌您的應用程式秘密。

這很重要

大括弧會顯示放置實際應用程式密碼的位置，請勿在 Start 的呼叫中放置大括弧。

備註

針對 iOS 應用程式，您無法在應用程式中同時有多個正在運行的當機報告 SDK。停用其他 SDK 損毀報告功能，以確保 App Center 可以攔截損毀。

4.3 將佔位符取代為您的應用程式密鑰

請務必將 {Your App Secret} 替換為應用程式中的實際值。您可以在 App Center 入口網站的 [ 使用者入門 ] 頁面或 [ 設定 ] 頁面上找到應用程式密碼。

[用戶入門] 頁面包含上述程式碼範例，其中包含您的應用程式秘密，您可以複製並貼上整個範例。

上述範例示範如何使用 Start() 方法，並同時包含 App Center 分析與 App Center 崩潰。

如果您不想使用這兩個服務之一，請從上述方法呼叫中移除對應的參數。

除非您明確將每個模組指定為 start 方法中的參數，否則您無法使用該 App Center 服務。此外， Start() API 只能在應用程式的生命週期中使用一次– 所有其他呼叫都會將警告記錄至主控台，而且只會使用第一次呼叫中包含的模組。

例如 - 如果您想要上線至 App Center Analytics，您應該修改 Start() 呼叫，如下所示：

4.3.1 MAUI 和 Xamarin.Forms

AppCenter.Start("ios={Your App Secret};macos={Your App Secret};android={Your App Secret};uwp={Your App Secret};windowsdesktop={Your App Secret}", typeof(Analytics));

4.3.2 Xamarin Native

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

太好了，您已準備好在 SDK 自動收集的門戶網站上視覺化分析數據和崩潰數據。

查看 App Center 分析與 App Center 當機的檔，瞭解如何自定義和使用這兩個服務更進階的功能。

若要了解如何開始使用應用程式內更新，請閱讀 App Center 發布的檔案。

備註

使用來自 Xamarin Forms 的可攜式 API，您會看到來自所有模組的 API，不過 UWP 和 Windows 桌面 平臺上不支援所有這些 API，而且 在 UWP 和 Windows Desktop 應用程式上執行時不會執行任何動作。特別是UWP和 Windows Desktop 不支援下列模組：發佈。任何具有傳回型別的方法，在 UWP 和 Windows 傳統型應用程式上會傳回 null （物件）、0 （數字）或false （布林值）。

5. 備份規則（僅限 Android）

備註

以 Android 6.0 （API 層級 23）或更新版本為目標的應用程式會自動啟用自動備份。

備註

如果您已經有具有備份規則的自定義檔案，請切換至第三個步驟。

如果您使用自動備份來避免取得裝置的不正確資訊，請遵循後續步驟：

5.1. 針對 Android 11（API 層級 30）或更低版本。

在 Resources/xml 資料夾中建立 appcenter_backup_rule.xml 檔案。

開啟專案的 AndroidManifest.xml 檔案。將 android:fullBackupContent 屬性新增至 <application> 專案。它應該指向 appcenter_backup_rule.xml 資源檔。

android:fullBackupContent="@xml/appcenter_backup_rule"

將下列備份規則新增至 appcenter_backup_rule.xml 檔案：

<full-backup-content xmlns:tools="http://schemas.android.com/tools">
      <exclude domain="sharedpref" path="AppCenter.xml"/>
      <exclude domain="database" path="com.microsoft.appcenter.persistence"/>
      <exclude domain="database" path="com.microsoft.appcenter.persistence-journal"/>
      <exclude domain="file" path="error" tools:ignore="FullBackupContent"/>
      <exclude domain="file" path="appcenter" tools:ignore="FullBackupContent"/>
  </full-backup-content>

5.2. 針對 Android 12 （API 層級 31）或更高版本。

在 Resources/xml 資料夾中建立 appcenter_backup_rule.xml 檔案。

開啟專案的 AndroidManifest.xml 檔案。將 android:dataExtractionRules 屬性新增至 <application> 專案。它應該指向 appcenter_backup_rule.xml 資源檔。

android:dataExtractionRules="@xml/appcenter_backup_rule"

將下列備份規則新增至 appcenter_backup_rule.xml 檔案：

<data-extraction-rules xmlns:tools="http://schemas.android.com/tools">
    <cloud-backup>
        <exclude domain="sharedpref" path="AppCenter.xml"/>
        <exclude domain="database" path="com.microsoft.appcenter.persistence"/>
        <exclude domain="database" path="com.microsoft.appcenter.persistence-journal"/>
        <exclude domain="file" path="error" tools:ignore="FullBackupContent"/>
        <exclude domain="file" path="appcenter" tools:ignore="FullBackupContent"/>
    </cloud-backup>
    <device-transfer>
        <exclude domain="sharedpref" path="AppCenter.xml"/>
        <exclude domain="database" path="com.microsoft.appcenter.persistence"/>
        <exclude domain="database" path="com.microsoft.appcenter.persistence-journal"/>
        <exclude domain="file" path="error" tools:ignore="FullBackupContent"/>
        <exclude domain="file" path="appcenter" tools:ignore="FullBackupContent"/>
    </device-transfer>
</data-extraction-rules>

共用方式為