.NET Portability Analyzer

  • 發行項

注意

我們正在淘汰 API 埠，而偏好將二進位分析直接整合到 .NET 升級小幫手。 在近期幾個月內，我們將關閉 API 連接埠的後端服務，這會需要離線使用工具。 如需詳細資訊，請參閱 GitHub：.NET API 埠存放庫。*

要讓您的程式庫支援多平台？ 想要查看需要多少工作才能讓您的.NET Framework應用程式在 .NET Core 上執行？ .NET 可攜性分析器是一種工具，可分析元件，並提供 .NET API 的詳細報告，這些 API 遺漏了應用程式或程式庫才能在指定的目標 .NET 平臺上移植。 Portability Analyzer 會作為 Visual Studio 延伸模組提供，可分析每個專案的一個組件，並可作為 ApiPort 主控台應用程式，按指定的檔案或目錄去分析組件。

將專案轉換為以 .NET Core 之類的新平臺為目標之後，您可以使用 Roslyn 型 平臺相容性分析器 來識別擲回 PlatformNotSupportedException 例外狀況和其他相容性問題的 API。

常見目標

  • .NET Core：具有模組化設計、支援並存安裝，並以跨平臺案例為目標。 並存安裝可讓您採用新的 .NET Core 版本，而不會中斷其他應用程式。 如果您的目標是將應用程式移植到 .NET Core 並支援多個平臺，這是建議的目標。
  • .NET Standard：包含所有 .NET 實作上可用的 .NET Standard API。 如果您的目標是讓程式庫在所有 .NET 支援平臺上執行，建議使用這個目標。
  • ASP.NET Core：建置在 .NET Core 上的新式 Web 架構。 如果您的目標，是要將 Web 應用程式移植到 .NET Core 來支援多平台，這是建議的目標。
  • .NET Core +平臺延伸模組：除了 Windows 相容性套件之外，還包含 .NET Core API，可提供許多.NET Framework可用的技術。 如需將您的應用程式從 .NET Framework 移植到 Windows 上的 .NET Core，這是建議的目標。
  • .NET Standard + Platform Extensions：除了 Windows 相容性套件之外，還包含 .NET Standard API，可提供許多.NET Framework可用的技術。 如需將您的程式庫從 .NET Framework 移植到 Windows 上的 .NET Core，這是建議的目標。

如何使用 .NET 可攜性分析器

若要開始在 Visual Studio 中使用 .NET 可攜性分析器，您必須從 Visual Studio Marketplace 下載及安裝此延伸模組。 其適用於 Visual Studio 2017 和 Visual Studio 2019 版本。

重要

Visual Studio 2022 不支援 .NET 可攜性分析器。

透過[分析>可攜性分析器設定] 在 Visual Studio 中設定它，然後選取您的目標平臺，也就是您想要評估與目前元件所建置平臺/版本相較的 .NET 平臺/版本。

Portability Analyzer 的螢幕擷取畫面。

您也可以使用 ApiPort 主控台應用程式，可從 ApiPort 存放庫下載。 您可以使用 listTargets 命令選項來顯示可用的目標清單，然後指定 -t 或 --target 命令選項來挑選目標平台。

解決方案整體檢視

分析具有許多專案之解決方案的實用步驟，就是將相依性視覺化，以了解哪些組件子集相依於哪些項目。 一般建議是在從相依性圖表中的分葉節點開始，套用由下至上分析的結果。

若要擷取此項目，您可以執行下列命令：

ApiPort.exe analyze -r DGML -f [directory or file]

在 Visual Studio 中開啟時，此結果看起來如下：

DGML 分析的螢幕擷取畫面。

分析可攜性

若要在 Visual Studio 中分析整個專案，在 [方案總管] 中以滑鼠右鍵按一下您的專案，然後選取 [分析組件可攜性]。 否則，請移至 [分析] 功能表，然後選取 [Analyze Assembly Portability] (分析組件可攜性)。 從這裡選取專案的可執行檔或 DLL。

[方案總管] 中 Portability Analyzer 的螢幕擷取畫面。

您也可以使用 ApiPort 主控台應用程式。

輸入下列命令，以分析目前的目錄︰

ApiPort.exe analyze -f .

若要分析特定的 .dll 檔案清單，請輸入下列命令︰

ApiPort.exe analyze -f first.dll -f second.dll -f third.dll

若要以特定版本為目標，請使用 -t 參數：

ApiPort.exe analyze -t ".NET, Version=5.0" -f .

執行 ApiPort.exe -? 以取得詳細說明。

建議您納入所有您擁有並想要移植的相關 exe 與 dll 檔案，並排除應用程式所依賴，但您未擁有也無法移植的檔案。 這會提供您最相關的可攜性報告。

檢視並解譯可攜性結果

只有目標平台不支援的 API 會顯示在報表中。 在 Visual Studio 執行分析之後，您會看到 .NET 可攜性報表檔案連結。 如果您使用 ApiPort 主控台應用程式，您的 .NET 可攜性報表會儲存為您指定格式的檔案。 預設會在您目前的目錄中儲存為 Excel 檔案 (.xlsx)。

可攜性摘要

Portability 摘要的螢幕擷取畫面。

此報表顯示的可攜性摘要區段，會顯示該次執行中每個組件的可攜性百分比。 在上述範例中，71.24% 用於 svcutil 應用程式中的 .NET Framework API 可在 .NET Core + 平台延伸模組中取得。 如果您對多個組件執行 .NET 可攜性分析工具，每個組件都應該在可攜性摘要報告中具有一個資料列。

詳細資料

Portability 詳細資料的螢幕擷取畫面。

報告的 [詳細資料] 區段，其中會列出任何所選 [目標平台] 遺漏的 API。

  • 目標類型：類型缺少目標平台的 API
  • 目標成員：目標平台缺少方法
  • 組件名稱：缺少之 API 所在的 .NET Framework 組件。
  • 每個選取的目標平臺都是一個資料行，例如 「.NET Core」： 「Not supported」 值表示此目標平臺不支援 API。
  • 建議的變更：建議要變更的 API 或技術。 目前，許多 API 的此欄位為空白或過期。 因為 API 太多，導致我們難以使其保持最新狀態。 我們將尋找替代解決方案，來為客戶提供有用的資訊。

缺少的組件

遺漏組件的螢幕擷取畫面。

您可在報表中找到缺少的組件區段。 此區段包含的組件清單由已分析的組件所參考，但未進行分析。 如果是您自己擁有的組件，請將其納入 API 可攜性分析器中執行，以便您可為其取得 API 層級的詳細可攜性報告。 如果是協力廠商程式庫，請檢查是否有支援目標平台的較新版本，並考慮移至較新版本。 最後，這份清單應包含您應用程式所依賴的所有第三方組件，以及具有支援您目標平台的版本。

如需 .NET 可攜性分析器的詳細資訊，請流覽 GitHub 檔。