開始使用MAUI和 Xamarin

發行項
03/15/2024

重要

Visual Studio App Center 已排定於 2025 年 3 月 31 日淘汰。雖然您可以繼續使用 Visual Studio App Center，直到它完全淘汰為止，但有數個建議您考慮移轉至的建議替代方案。

深入瞭解支持時程表和替代方案。

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

讓我們開始在應用程式中設定 App Center .NET SDK，以使用 App Center Analytics 和 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 Desktop 應用程式)

1.1 MAUI

注意

目前 App Center 入口網站上沒有 MAUI 平臺。請使用適用於 iOS 的 Xamarin 和 Android 和適用於 Windows 的 UWP 。

1.2 關於 Xamarin.Android

在 App Center 入口網站上建立應用程式，並搭配 Android 作為 OS 和 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 當機]。
按兩下 [新增套件]。

適用於 Windows 的 Visual Studio

開啟 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 套件。若要這樣做，您應該開啟每個子專案，並遵循適用於 Windows Visual Studio for Mac 或 Visual Studio 一節中所述的對應步驟。

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檔案， 並在建構函式 (或 Xamarin.Forms) 的方法中 OnStart() 新增下列這一行。

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檔案，並在方法內OnCreate()新增 Start() 呼叫

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

注意

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

4.2.3 Xamarin.iOS 和 Xamarin.Mac

注意

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

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

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

注意

如果使用當機，您必須在UI/主線程中呼叫這個方法，並避免在方法傳回之前 Start 啟動背景工作。原因是當機初始化時，從另一個線程攔截到任何 Null 參考例外狀況可能會觸發原生損毀並忽略 catch 子句。 AppCenter.Start方法傳回之後，可以放心地再次嘗試/攔截 Null 參考例外狀況。您可以在 Signals 和第三方損毀報告程式文章中深入瞭解此計時問題的原因。

警告

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

重要

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

注意

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

4.3 以您的應用程式秘密取代佔位元

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

使用者入門頁面包含上述程式代碼範例，其中含有您的應用程式密碼，您可以複製並貼上整個範例。

上述範例示範如何使用 Start() 方法，並同時包含App Center Analytics和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 Analytics 和 App Center 當機的檔，瞭解如何自定義和使用這兩項服務的更進階功能。

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

注意

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

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>