更新現有的 Xamarin.Forms 應用程式

發行項
03/05/2024

請遵循下列步驟來更新現有的 Xamarin.Forms 應用程式，以使用整合 API 並更新至 1.3.1 版

重要

由於 Xamarin.Forms 1.3.1 是第一個支援整合 API 的版本，因此應該更新整個解決方案以使用最新版本，同時將 iOS 應用程式移轉至 Unified。這表示，除了更新整合支援的 iOS 專案之外，您還需要在方案中的所有專案中編輯程式代碼。

更新會以兩個步驟執行：

使用 Visual Studio for Mac 在移轉工具中建置，將 iOS 應用程式移轉至整合 API。
- 使用移轉工具自動更新專案。
- 更新 iOS 原生 API，如更新 iOS 應用程式的指示中所述（特別是在自定義轉譯器或相依性服務程式代碼中）。
將整個解決方案更新為 Xamarin.Forms 1.3 版。
1. 安裝 Xamarin.Forms 1.3.1 NuGet 套件。
2. App更新共享程式代碼中的類別。
3. AppDelegate更新 iOS 專案中的。
4. MainActivity更新 Android 專案中的。
5. MainPage更新 Windows 電話專案中的。

1. iOS 應用程式（整合移轉）

移轉的一部分需要將 Xamarin.Forms 升級至支援整合 API 的 1.3 版。為了建立正確的元件參考，我們必須先更新 iOS 專案以使用整合 API。

移轉工具

按兩下 iOS 專案以選取它，然後選擇 [專案 > 遷移至 Xamarin.iOS 整合 API... ]，並同意出現的警告訊息。

Choose Project > Migrate to Xamarin.iOS Unified API... and agree to the warning message that appears

這會自動：

變更專案類型以支援 Unified 64 位 API。
將架構參考變更為 Xamarin.iOS （取代舊的 monotouch 參考）。
變更程式代碼中的命名空間參考，以移除前置 MonoTouch 詞。
更新 csproj 檔案，以針對整合 API 使用正確的組建目標。

清除並建置專案，以確保沒有其他錯誤可修正。不需要採取進一步的動作。統一 API 檔中會更詳細地說明這些步驟。

更新原生 iOS API（如有必要）

如果您已新增額外的 iOS 機器碼（例如自定義轉譯器或相依性服務），您可能需要執行額外的手動程式代碼修正。重新編譯您的應用程式，並參閱更新現有的 iOS 應用程式指示，以取得可能需要之變更的其他資訊。這些秘訣也有助於識別所需的變更。

2. Xamarin.Forms 1.3.1 更新

將iOS應用程式更新為整合 API 之後，解決方案的其餘部分必須更新為 Xamarin.Forms 1.3.1 版。這包括：

更新每個專案中的 Xamarin.Forms NuGet 套件。
將程式代碼變更為使用新的 Xamarin.Forms Application、 FormsApplicationDelegate （iOS）、 FormsApplicationActivity （Android）和 FormsApplicationPage （Windows 電話）類別。

下列步驟如下所述：

2.1 在所有專案中更新 NuGet

使用解決方案中所有專案的 NuGet 封裝管理員，將 Xamarin.Forms 更新為 1.3.1 發行前版本：PCL（如果有），iOS、Android 和 Windows 電話。建議您 刪除並重新新增 Xamarin.Forms NuGet 套件，以更新至 1.3 版。

注意

Xamarin.Forms 1.3.1 版目前處於 發行前版本。這表示您必須在 NuGet 中選取發行前選項（透過 Visual Studio for Mac 中的刻度方塊或 Visual Studio 中的下拉式清單），才能查看最新的發行前版本。

重要

如果您使用 Visual Studio，請確定已安裝最新版的 NuGet 封裝管理員。 Visual Studio 中的舊版 NuGet 不會正確安裝 Xamarin.Forms 1.3.1 的整合版本。移至 [工具>擴充功能和更新...]，然後按兩下 [已安裝] 列表，檢查Visual Studio的 NuGet 封裝管理員版本至少為2.8.5版。如果較舊，請按兩下 [更新] 清單以下載最新版本。

將 NuGet 套件更新為 Xamarin.Forms 1.3.1 之後，請在每個專案中進行下列變更，以升級至新的 Xamarin.Forms.Application 類別。

2.2 可攜式類別庫（或共享專案）

變更App.cs檔案，以便：

類別 App 現在繼承自 Application。
屬性 MainPage 會設定為您想要顯示的第一個內容頁面。

public class App : Application // superclass new in 1.3
{
    public App ()
    {
        // The root page of your application
        MainPage = new ContentPage {...}; // property new in 1.3
    }

我們已完全移除 GetMainPage 方法，而是在子類別上Application設定 MainPage屬性。

這個新的 Application 基類也支援 OnStart、 OnSleep和 OnResume 覆寫，以協助您管理應用程式的生命週期。

類別 App 接著會傳遞至每個應用程式專案中的新 LoadApplication 方法，如下所示：

2.3 iOS 應用程式

變更AppDelegate.cs檔案，以便：

類別繼承自 FormsApplicationDelegate （而不是 UIApplicationDelegate 先前）。
LoadApplication 會使用的新實體 App呼叫。

[Register ("AppDelegate")]
public partial class AppDelegate :
    global::Xamarin.Forms.Platform.iOS.FormsApplicationDelegate // superclass new in 1.3
{
    public override bool FinishedLaunching (UIApplication app, NSDictionary options)
    {
        global::Xamarin.Forms.Forms.Init ();

        LoadApplication (new App ());  // method is new in 1.3

        return base.FinishedLaunching (app, options);
    }
}

2.3 Android 應用程式

變更MainActivity.cs檔案，以便：

類別繼承自 FormsApplicationActivity （而不是 FormsActivity 先前）。
LoadApplication 使用的新實例呼叫 App

[Activity (Label = "YOURAPPNAM", Icon = "@drawable/icon", MainLauncher = true,
ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation)]
public class MainActivity :
    global::Xamarin.Forms.Platform.Android.FormsApplicationActivity // superclass new in 1.3
{
    protected override void OnCreate (Bundle bundle)
    {
        base.OnCreate (bundle);

        global::Xamarin.Forms.Forms.Init (this, bundle);

        LoadApplication (new App ()); // method is new in 1.3
    }
}

2.4 Windows 電話應用程式

我們需要更新 MainPage - XAML 和程式代碼後置。

變更 MainPage.xaml 檔案，以便：

根 XAML 元素應該是 winPhone:FormsApplicationPage。
屬性 xmlns:phone 應變更為 xmlns:winPhone="clr-namespace:Xamarin.Forms.Platform.WinPhone;assembly=Xamarin.Forms.Platform.WP8"

以下顯示更新的範例 - 您只需要編輯這些項目（其餘的屬性應該維持不變）：

<winPhone:FormsApplicationPage
   ...
   xmlns:winPhone="clr-namespace:Xamarin.Forms.Platform.WinPhone;assembly=Xamarin.Forms.Platform.WP8"
    ...>
</winPhone:FormsApplicationPage>

變更MainPage.xaml.cs檔案，以便：

類別繼承自 FormsApplicationPage （而不是 PhoneApplicationPage 先前）。
LoadApplication 會以 Xamarin.Forms App 類別的新實例呼叫。您可能需要完整限定此參考，因為 Windows 電話已定義自己的App類別。

public partial class MainPage : global::Xamarin.Forms.Platform.WinPhone.FormsApplicationPage // superclass new in 1.3
{
    public MainPage()
    {
        InitializeComponent();
        SupportedOrientations = SupportedPageOrientation.PortraitOrLandscape;

        global::Xamarin.Forms.Forms.Init();
        LoadApplication(new YOUR_APP_NAMESPACE.App()); // new in 1.3
    }
 }

疑難排解

更新 Xamarin.Forms NuGet 套件之後，您偶爾會看到類似此錯誤。當 NuGet 更新程式未從 csproj 檔案完全移除舊版的參考時，就會發生此情況。

YOUR_PROJECT.csproj：錯誤：此項目參考此計算機上遺漏的 NuGet 套件。啟用 NuGet 套件還原以下載它們。如需詳細資訊，請參閱https://go.microsoft.com/fwlink/?LinkID=322105。遺漏的檔案為 .。/../packages/Xamarin.Forms.1.2.3.6257/build/portable-win+net45+wp80+MonoAndroid10+MonoTouch10/Xamarin.Forms.targets。（YOUR_PROJECT）

若要修正這些錯誤，請在文本編輯器中開啟 csproj 檔案，並尋找 <Target 參考舊版 Xamarin.Forms 的專案，例如如下所示的元素。您應該從 csproj 檔案手動刪除此整個元素，並儲存變更。

  <Target Name="EnsureNuGetPackageBuildImports" BeforeTargets="PrepareForBuild">
    <PropertyGroup>
      <ErrorText>This project references NuGet package(s) that are missing on this computer. Enable NuGet Package Restore to download them.  For more information, see https://go.microsoft.com/fwlink/?LinkID=322105. The missing file is {0}.</ErrorText>
    </PropertyGroup>
    <Error Condition="!Exists('..\..\packages\Xamarin.Forms.1.2.3.6257\build\portable-win+net45+wp80+MonoAndroid10+MonoTouch10\Xamarin.Forms.targets')" Text="$([System.String]::Format('$(ErrorText)', '..\..\packages\Xamarin.Forms.1.2.3.6257\build\portable-win+net45+wp80+MonoAndroid10+MonoTouch10\Xamarin.Forms.targets'))" />
  </Target>

拿掉這些舊參考之後，項目應該會成功建置。

考量

將現有的 Xamarin.Forms 專案從傳統 API 轉換成新的整合 API 時，如果該應用程式依賴一或多個元件或 NuGet 套件，則應考慮下列考慮。

元件

您包含在應用程式中的任何元件也必須更新為整合 API，否則當您嘗試編譯時，就會發生衝突。對於任何包含的元件，請將目前的版本取代為支援整合 API 的 Xamarin 元件存放區中的新版本，並執行全新組建。作者尚未轉換的任何元件，都會在元件存放區中顯示僅限 32 位的警告。

NuGet 支援

雖然我們貢獻了 NuGet 的變更來與整合 API 支援搭配運作，但 NuGet 沒有新版本，因此我們正在評估如何讓 NuGet 辨識新的 API。

在那段時間之前，就像元件一樣，您必須將專案中包含的任何 NuGet 套件切換為支援整合 API 的版本，並在之後執行全新組建。

重要

如果您在相同的 Xamarin.iOS 專案中出現錯誤「錯誤 3 無法同時包含『monotouch.dll』和 'Xamarin.iOS.dll' - 明確參考 'Xamarin.iOS.dll'，雖然 'monotouch.dll' 是由 'xxx， Version=0.0.000， Culture=neutral， PublicKeyToken=null'' 在將您的應用程式轉換成 Unified API 之後參考，但通常是因為專案中有一個元件或 NuGet 套件尚未更新為 Unified API。您必須移除現有的元件/NuGet、更新為支援整合 API 的版本，並執行全新組建。

啟用 Xamarin.iOS 應用程式的 64 位組建

對於已轉換成 Unified API 的 Xamarin.iOS 行動應用程式，開發人員仍然需要從應用程式的 [選項] 中為 64 位機器啟用應用程式建置。如需啟用64位組建的詳細指示，請參閱32/64位平臺考慮檔的 Xamarin.iOS 應用程式的啟用64位組建。

摘要

Xamarin.Forms 應用程式現在應該更新為 1.3.1 版，而 iOS 應用程式已移轉至整合 API（支援 iOS 平臺上的 64 位架構）。

如上所述，如果您的 Xamarin.Forms 應用程式包含原生程式代碼，例如自定義轉譯器或相依性服務，則這些程式碼可能需要更新以使用整合 API 中引進的新類型。

共用方式為

更新現有的 Xamarin.Forms 應用程式

1. iOS 應用程式（整合移轉）

移轉工具

更新原生 iOS API（如有必要）

2. Xamarin.Forms 1.3.1 更新

2.1 在所有專案中更新 NuGet

2.2 可攜式類別庫（或共享專案）

2.3 iOS 應用程式

2.3 Android 應用程式

2.4 Windows 電話應用程式

疑難排解

考量

元件

NuGet 支援

啟用 Xamarin.iOS 應用程式的 64 位組建

摘要

其他資源

共用方式為

更新現有的 Xamarin.Forms 應用程式

1. iOS 應用程式 （整合移轉）

移轉工具

更新原生 iOS API（如有必要）

2. Xamarin.Forms 1.3.1 更新

2.1 在所有專案中更新 NuGet

2.2 可攜式類別庫 （或共享專案）

2.3 iOS 應用程式

2.3 Android 應用程式

2.4 Windows 電話 應用程式

疑難排解

考量

元件

NuGet 支援

啟用 Xamarin.iOS 應用程式的 64 位組建

摘要

相關連結

其他資源

1. iOS 應用程式（整合移轉）

2.2 可攜式類別庫（或共享專案）

2.4 Windows 電話應用程式