使用 Desktop App Converter 封裝傳統型應用程式Package a desktop application using the Desktop App Converter

注意

Desktop App Converter 工具已被取代。The Desktop App Converter tool is deprecated. 建議您改用 MSIX 封裝工具We recommend that you use the MSIX Packaging Tool instead.

DAC 圖示

Desktop App Converter (DAC) 會建立適用於傳統型應用程式的套件,以便與最新的 Windows 功能整合,包括透過 Microsoft Store 散佈和提供服務。The Desktop App Converter (DAC) creates packages for desktop applications to integrate with the latest Windows features, including distribution and servicing via the Microsoft Store. 這包括 Win32 應用程式,以及您使用 .NET 4.6.1 建立的應用程式。This includes Win32 apps and apps that you've created by using .NET 4.6.1.

取得傳統型應用程式轉換器Get the Desktop App Converter

雖然此工具的名稱中出現 Converter (轉換器) 這個詞,但它並不會轉換您的應用程式。While the term "Converter" appears in the name of this tool, it doesn't actually convert your app. 您的應用程式不會改變。Your application remains unchanged. 不過,此工具會產生含有套件識別資料並可呼叫大範圍 WinRT API 的 Windows 應用程式套件。However, this tool generates a Windows app package with a package identity and the ability to call a vast range of WinRT APIs.

您可在開發電腦上使用 Add-AppxPackage PowerShell Cmdlet 安裝該套件。You can install that package by using the Add-AppxPackage PowerShell cmdlet on your development machine.

這個轉換器會在隔離的 Windows 環境中,使用全新基礎映像 (當作轉換器下載的一部分來提供) 來執行桌面安裝程式。The converter runs the desktop installer in an isolated Windows environment by using a clean base image provided as part of the converter download. 它會擷取桌面安裝程式所製作的任何登錄與檔案系統 I/O,並將它重新封裝為輸出的一部分。It captures any registry and file system I/O made by the desktop installer and packages it as part of the output.

重要

Windows 10 1607 版和更新版本支援 Desktop App Converter。Desktop App Converter is supported on Windows 10, version 1607, and later. Desktop App Converter 只能用於以 Visual Studio 中 Windows 10 年度更新版 (10.0;組建 14393) 或更新版本為目標的專案。It can only be used in projects that target Windows 10 Anniversary Update (10.0; Build 14393) or a later release in Visual Studio.

DAC 不只是為您產生套件The DAC does more than just generate a package for you

以下是一些它也能為您做到的事情。Here's a few extra things it can do for you.

Windows 10 Creators UpdateWindows 10 Creators Update

✔️自動註冊您的預覽處理常式、縮圖處理常式、屬性處理常式、防火牆規則、URL 旗標。Automatically register your preview handlers, thumbnail handlers, property handlers, firewall rules, URL flags.

✔️自動註冊檔案類型對應,讓使用者可以在檔案總管中使用 類型欄位群組檔案。Automatically register file type mappings that enable users to group files by using the Kind column in File Explorer.

✔️註冊您的公用 COM 伺服器。Register your public COM servers.

Windows 10 年度更新版或更新版本Windows 10 Anniversary Update or later

✔️自動簽署您的套件,讓您可以測試您的應用程式。Automatically sign your package so that you can test your app.

✔️根據您的已封裝應用程式和 Microsoft Store 需求來驗證您的應用程式。Validate your application against packaged app and Microsoft Store requirements.

若要尋找選項的完整清單,請參閱本文的參數一節。To find a complete list of options, see the Parameters section of this guide.

當您準備好要建立套件時,我們就可以開始了。If you're ready to create your package, let's start.

首先,準備您的應用程式First, prepare your application

開始為您的應用程式建立套件之前,請先檢閱本指南:準備封裝傳統型應用程式Review this guide before you begin creating a package for your application: Prepare to package a desktop application.

確定您的系統可以執行轉換器Make sure that your system can run the converter

請確定您的系統符合下列需求︰Make sure that your system meets the following requirements:

啟動 Desktop App ConverterStart the Desktop App Converter

  1. 下載並安裝 Desktop App ConverterDownload and install the Desktop App Converter.

  2. 以系統管理員身分執行 Desktop App Converter。Run the Desktop App Converter as an administrator.

    以系統管理員身分執行 DAC

    隨即顯示主控台視窗。A console window appears. 您將會使用該主控台視窗執行命令。You'll use that console window to run commands.

進行幾項設定 (僅限有安裝程式的應用程式)Set a few things up (apps with installers only)

若您的應用程式沒有安裝程式,您可以跳到下一節。You can skip ahead to the next section if your application doesn't have an installer.

  1. 識別您的作業系統版本號碼。Identify the version number of your operating system.

    若要這樣做,請在 [執行] 對話方塊中輸入 winver,然後選取 [確定] 按鈕。To do that, type winver in the Run dialog box, and then choose the OK button.

    winver

    您可以在 [關於 Windows] 對話方塊中找到您的 Windows 組建版本。You'll find the version of your Windows build in the About Windows dialog box.

    Windows 10 版本

  2. 下載適合的 Desktop App Converter 基礎映像Download the appropriate Desktop app Converter base image.

    請確定出現在檔案名稱中的版本號碼符合您的 Windows 組建版本號碼。Make sure that the version number that appears in the name of the file matches the version number of your Windows build.

    重要

    如果您的組建編號是 15063,且該組建的次要版本等於或大於 .483 (例如:15063.540),請務必下載 BaseImage-15063-UPDATE.wim 檔案。If you're using build number 15063, and the minor version of that build is equal to or greater than .483 (For example: 15063.540), make sure to download the BaseImage-15063-UPDATE.wim file. 如果該組建的次要版本小於 .483,請下載 BaseImage-15063.wim 檔案。If the minor version of that build is less than .483, download the BaseImage-15063.wim file. 如果您已經安裝不相容的基礎檔案版本,可以進行修正。If you've already setup an incompatible version of this base file, you can fix it. 部落格文章說明如何執行。This blog post explains how to do that.

  3. 將下載的檔案放在您電腦上的任何一個位置,以便您稍後可以找到它。Place the downloaded file anywhere on your computer where you'll be able to find it later.

  4. 在啟動 Desktop App Converter 時出現的主控台視窗中執行此命令︰Set-ExecutionPolicy bypassIn the console window that appeared when you started the Desktop App Converter, run this command: Set-ExecutionPolicy bypass.

  5. 執行此命令以安裝轉換器︰DesktopAppConverter.exe -Setup -BaseImage .\BaseImage-1XXXX.wim -VerboseSet up the converter by running this command: DesktopAppConverter.exe -Setup -BaseImage .\BaseImage-1XXXX.wim -Verbose.

  6. 若系統提示您重新啟動您的電腦,請重新開機。Restart your computer if you're prompted to do so.

    轉換器展開基礎映像時於主控台視窗中出現的狀態訊息。Status messages appear in the console window as the converter expands the base image. 若您並未看到任何狀態訊息,請按任意鍵。If you don't see any status messages, press any key. 這可能會重新整理主控台視窗中的內容。This can cause the contents of the console window to refresh.

    主控台視窗中的狀態訊息

    當基礎映像完全展開後,請移至下一節。When the base image is fully expanded, move to the next section.

封裝應用程式Package an app

若要封裝您的應用程式,請在啟動 Desktop App Converter 時開啟的主控台視窗中執行 DesktopAppConverter.exe 命令。To Package your app, run the DesktopAppConverter.exe command in the console window that opened when you started the Desktop App Converter.

您將會使用參數來指定應用程式的套件名稱、發行者、版本號碼。You'll specify the package name, publisher and version number of the application by using parameters.

注意

如果您已在 Microsoft Store 中保留您的應用程式名稱,可以使用合作夥伴中心來取得套件和發行者名稱。If you've reserved your app name in the Microsoft Store, you can obtain the package and publisher names by using Partner Center. 若您想要在其他系統上側載您的應用程式,您可以為他們提供您自己的名稱,只要其發行者名稱與您選擇用來簽署您應用程式之憑證上的名稱相同即可。If you plan to sideload your app onto other systems, you can provide your own names for these as long as the publisher name that you choose matches the name on the certificate you use to sign your app.

快速查看命令參數A quick look at command parameters

以下是必要的參數。Here are the required parameters.

DesktopAppConverter.exe
-Installer <String>
-Destination <String>
-PackageName <String>
-Publisher <String>
-Version <Version>

您可以在這裡查看每一個參數的相關資訊。You can read about each one here.

範例Examples

以下是一些封裝應用程式的常見方式。Here's a few common ways to package your app.

封裝具有安裝程式 (.msi) 檔案的應用程式Package an application that has an installer (.msi) file

使用 Installer 參數指向安裝程式檔案。Point to the installer file by using the Installer parameter.

DesktopAppConverter.exe -Installer C:\Installer\MyAppSetup.msi -Destination C:\Output\MyApp -PackageName "MyApp" -Publisher "CN=MyPublisher" -Version 0.0.0.1

重要

以下是應該牢記的兩件重要的事。There are two important things to keep in mind here. 首先,確定您的安裝程式位於一個獨立的資料夾中,且相同的資料夾中只有其他與安裝程式相關的檔案。First, make sure that your installer is located in an independent folder and that only files related to that installer are in the same folder. 轉換器會將該資料夾中的所有內容複製到隔離 Windows 環境中。The converter copies all of the contents of that folder to the isolated Windows environment.
其次,如果合作夥伴中心為您的套件指定了以數字開頭的身分識別,請確定您也傳入 -AppId 參數,並只使用字串尾碼 (句點分隔符號之後) 為參數值。Secondly, if Partner Center assigns an identity to your package that begins with a number, make sure that you also pass in the -AppId parameter, and use only the string suffix (after the period separator) as the value of that parameter.

如果您的安裝程式包括相依媒體櫃或架構得安裝程式,您可能需要以不同方式組織項目。If your installer includes installers for dependent libraries or frameworks, you might have to organize things a bit a differently. 請參閱使用傳統型橋接器鏈結多個安裝程式See Chaining multiple installers with the Desktop Bridge.

封裝具有安裝程式執行檔的應用程式Package an application that has a setup executable file

使用 Installer 參數指向安裝程式執行檔。Point to the setup executable by using the Installer parameter.

DesktopAppConverter.exe -Installer C:\Installer\MyAppSetup.exe -InstallerArguments "/S" -Destination C:\Output\MyApp -PackageName "MyApp" -Publisher "CN=MyPublisher" -Version 0.0.0.1

重要

如果合作夥伴中心為您的套件指定了以數字開頭的身分識別,請確定您也傳入 -AppId 參數,並只使用字串尾碼 (句點分隔符號之後) 為參數值。If Partner Center assigns an identity to your package that begins with a number, make sure that you also pass in the -AppId parameter, and use only the string suffix (after the period separator) as the value of that parameter.

InstallerArguments 是選用參數。The InstallerArguments parameter is an optional parameter. 然而,由於 Desktop App Converter 需要您的安裝程式才能在自動模式下執行,您可能需要使用這項參數,才能確保您的應用程式能使無訊息 (silent) 旗標正常運作。However, because the Desktop App Converter needs your installer to run in unattended mode, you might have to use it if your application needs silent flags to run silently. /S 旗標是一個相當常見的無訊息旗標,但您使用的旗幟可能會因您所使用的安裝技術而有所不同。The /S flag is a very common silent flag, but the flag that you use might be different depending on which installer technology you used to create the setup file.

封裝沒有安裝程式的應用程式Package an application that doesn't have an installer

在這個範例中,您可以使用 Installer 參數指向您應用程式的根資料夾。In this example, use the Installer parameter to point to the root folder of your application files.

使用 AppExecutable 參數,指向您的應用程式執行檔。Use the AppExecutable parameter to point to your apps executable file.

DesktopAppConverter.exe -Installer C:\Installer\MyApp\ -AppExecutable MyApp.exe -Destination C:\Output\MyApp -PackageName "MyApp" -Publisher "CN=MyPublisher" -Version 0.0.0.1

重要

如果合作夥伴中心為您的套件指定了以數字開頭的身分識別,請確定您也傳入 -AppId 參數,並只使用字串尾碼 (句點分隔符號之後) 為參數值。If Partner Center assigns an identity to your package that begins with a number, make sure that you also pass in the -AppId parameter, and use only the string suffix (after the period separator) as the value of that parameter.

封裝應用程式、簽署應用程式,並對套件執行驗證檢查Package an app, sign the app, and run validation checks on the package

這個範例與第一個範例相似,然而其不同點在它會告訴您如何簽署您的應用程式以供本機進行測試。並且驗證您的應用程式,確定其並未違反封裝的應用程式和 Microsoft Store 的需求。This example is similar to first one except it shows how you can sign your application for local testing, and then validate your application against packaged app and Microsoft Store requirements.

DesktopAppConverter.exe -Installer C:\Installer\MyAppSetup.exe -InstallerArguments "/S" -Destination C:\Output\MyApp -PackageName "MyApp" -Publisher "CN=MyPublisher" -Version 0.0.0.1 -MakeAppx -Sign -Verbose -Verify

重要

如果合作夥伴中心為您的套件指定了以數字開頭的身分識別,請確定您也傳入 -AppId 參數,並只使用字串尾碼 (句點分隔符號之後) 為參數值。If Partner Center assigns an identity to your package that begins with a number, make sure that you also pass in the -AppId parameter, and use only the string suffix (after the period separator) as the value of that parameter.

Sign 參數會產生一個憑證,然後以此憑證簽署您的應用程式。The Sign parameter generates a certificate and then signs your application with it. 若要執行您的應用程式,您必須先安裝該產生的憑證。To run your app, you'll have to install that generated certificate. 若要了解如何執行,請參閱本文中執行封裝的應用程式一節。To learn how, see the Run the packaged app section of this guide.

您可以使用 Verify 參數來驗證您的應用程式。You can validate you application by using the Verify parameter.

快速查看選用參數A quick look at optional parameters

SignVerify 參數為選用參數。The Sign and Verify parameters are optional. 此外還有許多選用參數。There are many more optional parameters. 以下是一些較常使用的選用參數。Here are some of the more commonly used optional parameters.

[-ExpandedBaseImage <String>]
[-AppExecutable <String>]
[-AppFileTypes <String>]
[-AppId <String>]
[-AppDisplayName <String>]
[-AppDescription <String>]
[-PackageDisplayName <String>]
[-PackagePublisherDisplayName <String>]
[-MakeAppx]
[-LogFile <String>]
[<CommonParameters>]

您可以在下一節了解它們的相關資訊。You can read about all of them in the next section.

參數參考資料Parameter Reference

以下是您執行 Desktop App Converter 時可以使用的參數完整清單 (依類別分類)。Here's the complete list of parameters (organized by category) that you can use when you run the Desktop App Converter.

您也可以透過在應用程式主控台視窗執行 Get-Help 命令來檢視整個清單。You can also view the entire list by running the Get-Help command in the app console window.

安裝參數Setup parameters
-Setup [<SwitchParameter>]-Setup [<SwitchParameter>] 必要Required 在安裝模式中執行 DesktopAppConverter。Runs DesktopAppConverter in setup mode. 安裝模式支援展開提供的基礎映像。Setup mode supports expanding a provided base image.
-BaseImage <String>-BaseImage <String> 必要Required 未展開之基礎映像的完整路徑。Full path to an unexpanded base image. 如果指定了 -Setup,則此為必要參數。This parameter is required if -Setup is specified.
-LogFile <String>-LogFile <String> 選用Optional 指定記錄檔。Specifies a log file. 如果省略,則會建立記錄檔暫時位置。If omitted, a log file temporary location will be created.
-NatSubnetPrefix <String>-NatSubnetPrefix <String> 選用Optional 可供 Nat 執行個體使用的首碼值。Prefix value to be used for the Nat instance. 通常,只有在您的主機電腦附加到與轉換器的 NetNat 相同的子網路範圍時,您才會想要變更此值。Typically, you would want to change this only if your host machine is attached to the same subnet range as the converter's NetNat. 您可以使用 Get-NetNat Cmdlet 來查詢目前的轉換器 NetNat 組態。You can query the current converter NetNat config by using the Get-NetNat cmdlet.
-NoRestart [<SwitchParameter>]-NoRestart [<SwitchParameter>] 必要Required 執行安裝時不顯示重新開機的提示 (需要重新開機才能啟用容器功能)。Don't prompt for reboot when running setup (reboot is required to enable the container feature).
轉換參數Conversion parameters
-AppInstallPath <String>-AppInstallPath <String> 選用Optional 您的應用程式在安裝之後,其已安裝檔案根資料夾的完整路徑 (例如 "C:\Program Files (x86)\MyApp")。The full path to your application's root folder for the installed files if it were installed (e.g., "C:\Program Files (x86)\MyApp").
-Destination <String>-Destination <String> 必要Required 適用於轉換器 appx 輸出的所需目的地,如果尚未存在,DesktopAppConverter可以建立此位置。The desired destination for the converter's appx output - DesktopAppConverter can create this location if it doesn't already exist.
-Installer <String>-Installer <String> 必要Required 應用程式的安裝程式路徑,必須能夠自動執行或以無訊息方式執行。The path to the installer for your application - must be able to run unattended/silently. 無安裝程式轉換,這是您應用程式檔案根目錄的路徑。No-installer conversion, this is the path to the root directory of your application files.
-InstallerArguments <String>-InstallerArguments <String> 選用Optional 以逗號分隔的引數清單或字串,可強制您的安裝程式自動執行或以無訊息方式執行。A comma-separated list or string of arguments to force your installer to run unattended/silently. 如果您的安裝程式是 msi,則此為選用參數。This parameter is optional if your installer is an msi. 若要取得安裝程式的記錄,請提供此處的安裝程式記錄引數,然後使用路徑 <log_folder>,此為轉換器會使用適當路徑來取代的語彙基元。To get a log from your installer, supply the logging argument for the installer here and use the path <log_folder>, which is a token that the converter replaces with the appropriate path.

注意:自動/無訊息旗標和記錄引數會隨著安裝程式技術而不同。NOTE: The unattended/silent flags and log arguments will vary between installer technologies.

此參數的範例用法: -InstallerArguments "/silent /log <log_folder>\install.log"。另一個不會產生記錄檔的範例如下:-InstallerArguments "/quiet", "/norestart"。同樣地,如果您想要讓轉換器擷取記錄並將其放在最終的記錄資料夾中,就必須將任何記錄直接導向至權杖路徑 <log_folder>。An example usage for this parameter: -InstallerArguments "/silent /log <log_folder>\install.log" Another example that doesn't produce a log file may look like: -InstallerArguments "/quiet", "/norestart" Again, you must literally direct any logs to the token path <log_folder> if you want the converter to capture it and put it in the final log folder.
-InstallerValidExitCodes <Int32>-InstallerValidExitCodes <Int32> 選用Optional 以逗號分隔的結束代碼清單,表示您的安裝程式已成功執行 (例如︰0, 1234, 5678)。A comma-separated list of exit codes that indicate your installer ran successfully (for example: 0, 1234, 5678). 針對非 msi,這個值預設是 0,針對 msi 則為 0, 1641, 3010。By default this is 0 for non-msi, and 0, 1641, 3010 for msi.
-MakeAppx [<SwitchParameter>]-MakeAppx [<SwitchParameter>] 選用Optional 一個參數,如果顯示,即會通知這個指令碼呼叫輸出上的 MakeAppx。A switch that, when present, tells this script to call MakeAppx on the output.
-MakeMSIX [<SwitchParameter>]-MakeMSIX [<SwitchParameter>] 選用Optional 一種參數,當出現時,會告知此指令碼將輸出封裝為 MSIX 套件。A switch that, when present, tells this script to package the output as an MSIX Package.
套件識別資料參數Package identity parameters
-PackageName <String>-PackageName <String> 必要Required 您的通用 Windows 應用程式套件的名稱。The name of your Universal Windows App package. 如果合作夥伴中心為您的套件指定了以數字開頭的身分識別,請確定您也傳入 -AppId 參數,並只使用字串尾碼 (句點分隔符號之後) 為參數值。If Partner Center assigns an identity to your package that begins with a number, make sure that you also pass in the -AppId parameter, and use only the string suffix (after the period separator) as the value of that parameter.
-Publisher <String>-Publisher <String> 必要Required 通用 Windows 應用程式套件的發行者The publisher of your Universal Windows App package
-Version <Version>-Version <Version> 必要Required 通用 Windows 應用程式套件的版本號碼The version number for your Universal Windows App package
套件資訊清單參數Package manifest parameters
-AppExecutable <String>-AppExecutable <String> 選用Optional 應用程式主要可執行檔 (例如 "MyApp.exe") 的名稱。The name of your application's main executable (eg "MyApp.exe"). 此參數是無安裝程式轉換的必要參數。This parameter is required for a no-installer conversion.
-AppFileTypes <String>-AppFileTypes <String> 選用Optional 以逗號分隔的檔案類型清單,應用程式將會與其產生關聯。A comma-separated list of file types which the application will be associated with. 使用範例:-AppFileTypes "'.md', '.markdown'"。Example usage: -AppFileTypes "'.md', '.markdown'".
-AppId <String>-AppId <String> 選用Optional 在 Windows 應用程式套件資訊清單中指定要為應用程式識別碼所設定的值。Specifies a value to set Application Id to in the Windows app package manifest. 如果未指定,它將會設定為針對 /packagename 傳入的值。If it is not specified, it will be set to the value passed in for PackageName. 在很多情況下,使用 PackageName 即可。In many cases, using the PackageName is fine. 不過,如果合作夥伴中心為您的套件指定了以數字開頭的身分識別,請確定您也傳入 -AppId 參數,並只使用字串尾碼 (句點分隔符號之後) 為參數值。However, if Partner Center assigns an identity to your package that begins with a number, make sure that you also pass in the -AppId parameter, and use only the string suffix (after the period separator) as the value of that parameter.
-AppDisplayName <String>-AppDisplayName <String> 選用Optional 指定要在 Windows 應用程式套件資訊清單中設定應用程式顯示名稱的值。Specifies a value to set Application Display Name to in the Windows app package manifest. 如果未指定,它將會設定為針對 /packagename 傳入的值。If it is not specified, it will be set to the value passed in for PackageName.
-AppDescription <String>-AppDescription <String> 選用Optional 在 Windows 應用程式套件資訊清單中指定要為應用程式描述所設定的值。Specifies a value to set Application Description to in the Windows app package manifest. 如果未指定,它將會設定為針對 /packagename 傳入的值。If it is not specified, it will be set to the value passed in for PackageName.
-PackageDisplayName <String>-PackageDisplayName <String> 選用Optional 指定要在 Windows 應用程式套件資訊清單中設定套件顯示名稱的值。Specifies a value to set Package Display Name to in the Windows app package manifest. 如果未指定,它將會設定為針對 /packagename 傳入的值。If it is not specified, it will be set to the value passed in for PackageName.
-PackagePublisherDisplayName <String>-PackagePublisherDisplayName <String> 選用Optional 指定要在 Windows 應用程式套件資訊清單中設定套件發行者顯示名稱的值。Specifies a value to set Package Publisher Display Name to in the Windows app package manifest. 如果未指定,它將會設定為針對 Publisher 傳入的值。If it is not specified, it will be set to the value passed in for Publisher.
清理參數Cleanup parameters
-Cleanup [<Option>]-Cleanup [<Option>] 必要Required 執行 DesktopAppConverter 成品的清理。Runs cleanup for the DesktopAppConverter artifacts. Cleanup 模式有 3 個有效的選項。There are 3 valid options for the Cleanup mode.
-Cleanup All-Cleanup All 刪除所有展開的基本映像、移除任何暫存轉換器檔案、移除容器網路,並停用選用的 Windows 功能、容器。Deletes all expanded base images, removes any temporary converter files, removes the container network, and disables the optional Windows feature, Containers.
-Cleanup WorkDirectory-Cleanup WorkDirectory 必要Required 移除所有的暫存轉換器檔案。Removes all the temporary converter files.
-Cleanup ExpandedImage-Cleanup ExpandedImage 必要Required 刪除所有已展開且安裝在主機電腦上的基本映像。Deletes all the expanded base images installed on your host machine.
套件架構參數Package architecture parameters
-PackageArch <String>-PackageArch <String> 必要Required 產生具有指定架構的套件。Generates a package with the specified architecture. 有效的選項是 'x86' 或 'x64';例如,-PackageArch x86。Valid options are 'x86' or 'x64'; for example, -PackageArch x86. 此為選擇性參數。This parameter is optional. 如果沒有指定,傳統型應用程式轉換器將會嘗試自動偵測套件架構。If unspecified, the DesktopAppConverter will try to auto-detect package architecture. 如果自動偵測失敗,將預設為 x64 套件。If auto-detection fails, it will default to x64 package.
其他參數Miscellaneous parameters
-ExpandedBaseImage <String>-ExpandedBaseImage <String> 選用Optional 已經展開之基礎映像的完整路徑。Full path to an already expanded base image.
-LogFile <String>-LogFile <String> 選用Optional 指定記錄檔。Specifies a log file. 如果省略,則會建立記錄檔暫時位置。If omitted, a log file temporary location will be created.
-Sign [<SwitchParameter>]-Sign [<SwitchParameter>] 選用Optional 告訴此指令碼使用為測試用途產生的憑證簽署輸出的 Windows 應用程式套件。Tells this script to sign the output Windows app package by using a generated certificate for testing purposes. 這個參數應該出現在參數 -MakeAppx 旁邊。This switch should be present alongside the switch -MakeAppx.
<Common parameters><Common parameters> 必要Required 此 Cmdlet 支援一般參數:Verbose 、Debug 、ErrorAction 、ErrorVariable 、WarningAction 、WarningVariable 、OutBuffer 、PipelineVariable 、OutVariable 。This cmdlet supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable, WarningAction, WarningVariable, OutBuffer, PipelineVariable, and OutVariable. 如需詳細資訊,請參閱 about_CommonParametersFor more info, see about_CommonParameters.
-Verify [<SwitchParameter>]-Verify [<SwitchParameter>] 選用Optional 一個參數,如果存在,這個參數會指示 DAC 根據封裝的應用程式及 Microsoft Store 的需求來驗證應用程式套件。A switch that, when present, tells the DAC to validate the app package against packaged app and Microsoft Store requirements. 結果會是驗證報告「VerifyReport.xml」,這在瀏覽器中呈現最佳視覺效果。The result is a validation report "VerifyReport.xml", which is best visualized in a browser. 這個參數應該出現在參數 -MakeAppx 旁邊。This switch should be present alongside the switch -MakeAppx.
-PublishComRegistrations-PublishComRegistrations 選用Optional 掃描所有由您的安裝程式建立的公用 COM 註冊,並發行資訊清單中有效的項目。Scans all public COM registrations made by your installer and publishes the valid ones in your manifest. 只有當您想要讓其他應用程式使用這些註冊時,才使用此旗標。Use this flag only if you want to make these registrations available to other applications. 若只有您的應用程式才會使用到這些註冊,則您就不需要使用此旗標。You don't need to use this flag if these registrations will be used only by your application.

請參閱本文以確定您的 COM 註冊在您封裝應用程式之後,其行為會跟預期中的一樣。Review this article to make sure that your COM registrations behave as you expect after you package your app.

執行已封裝的應用程式Run the packaged app

有兩種方式可執行您的應用程式。There's two ways to run your app.

一個是開啟 PowerShell 命令提示字元,並輸入此命令︰Add-AppxPackage –Register AppxManifest.xmlOne way is to open a PowerShell command prompt, and then type this command: Add-AppxPackage –Register AppxManifest.xml. 這可能是執行您的應用程式最簡單的方式,因為應用程式不需要先經過簽署。It's probably the easiest way to run your application because you don't have to sign it.

另一個則是使用一個憑證簽署您的應用程式。Another way is to sign your application with a certificate. 若您使用了 sign 參數,Desktop App Converter 會為您產生一個憑證,並以該憑證簽署您的應用程式。If you use the sign parameter, the Desktop App Converter will generate one for you, and then sign your application with it. 該憑證的檔名為 auto-generated.cer,您可以在已封裝應用程式的根資料夾中找到該檔案。That file is named auto-generated.cer, and you can find it in the root folder of your packaged app.

請依照下列步驟來安裝產生的認證,然後再執行您的應用程式。Follow these steps to install the generated certificate, and then run your app.

  1. 按兩下 auto-generated.cer 以安裝憑證。Double-click the auto-generated.cer file to install the certificate.

    產生的憑證檔案

    注意

    如果系統提示您輸入密碼,請使用預設密碼「123456」。If you're prompted for a password, use the default password "123456".

  2. 在 [憑證] 對話方塊中,選擇 [安裝憑證] 按鈕。In the Certificate dialog box, choose the Install Certificate button.

  3. 在 [憑證匯入精靈] 中,將憑證安裝到本機電腦,並將憑證放入 [受信任的人] 憑證存放區。In the Certificate Import Wizard, install the certificate onto the Local Machine, and place the certificate into the Trusted People certificate store.

    受信任的人存放區

  4. 在您的已封裝應用程式的根資料夾中,按兩下 Windows 應用程式套件檔案。In root folder of your packaged app, double click the Windows app package file.

    Windows 應用程式套件檔案

  5. 選擇 [安裝] 按鈕以安裝應用程式。Install the app, by choosing the Install button.

    安裝按鈕

修改已封裝的應用程式Modify the packaged app

您可能會想要變更您的已封裝應用程式,處理 BUG、增加視覺資產,或是透過現代化的體驗 (例如動態磚) 來美化您的應用程式。You'll likely make changes to your packaged application to address bugs, add visual assets, or enhance your application with modern experiences such as live tiles.

在您完成變更之後,不需要再執行一次轉換器。After you make your changes, you don't need to run the converter again. 在大部分情況下,您可以使用 MakeAppx 工具和 DAC 為您應用程式產生的 appxmanifest.xml 檔案,重新封裝您的應用程式。In most cases, you can just repackage your application by using the MakeAppx tool and the appxmanifest.xml file the DAC generates for your app. 請參閱產生 Windows 應用程式套件See Generate a Windows app package.

注意

若您變更了您應用程式建立的登錄設定,就必須再執行一次 Desktop App Converter 以揀選那些變更。If you make changes to registry settings that your installer makes, you will have to run the Desktop App Converter again to pick up those changes.

下列兩節描述了幾個您可能會考慮套用至您已封裝應用程式的選用修正內容。The following two sections describe a couple of optional fix-ups to the packaged application that you might consider.

刪除不需要的檔案和登錄機碼Delete unnecessary files and registry keys

Desktop App Converter 採用極為保守的方式來篩選出容器中的檔案和系統雜訊。The desktop App Converter takes a very conservative approach to filtering out files and system noise in the container.

若您需要的話,您可以檢視 VFS 資料夾,並刪除您的安裝程式不需要的任何檔案。If you want, you can review the VFS folder and delete any files that your installer doesn't need. 您也可以檢閱 Reg.dat 內容,並刪除應用程式未安裝/不需要的任何機碼。You can also review the contents of Reg.dat and delete any keys that are not installed/needed by the app.

修正損毀的 PE 標頭Fix corrupted PE headers

在轉換過程中,DesktopAppConverter 會自動執行 PEHeaderCertFixTool,以修正任何損毀的 PE 標頭。During the conversion process, the DesktopAppConverter automatically runs the PEHeaderCertFixTool to fixup any corrupted PE headers. 不過,您也可以在 UWP Windows 應用程式套件、鬆散檔案或特定的二進位檔上執行 PEHeaderCertFixTool。However, you can also run the PEHeaderCertFixTool on a UWP Windows app package, loose files, or a specific binary. 以下是範例。Here's an example.

PEHeaderCertFixTool.exe <binary file>|<.appx package>|<folder> [/c] [/v]
 /c   -- check for corrupted certificate but do not fix (optional)
 /v   -- verbose (optional)
example1: PEHeaderCertFixTool app.exe
example2: PEHeaderCertFixTool c:\package.appx /c
example3: PEHeaderCertFixTool c:\myapp /c /v

從傳統型應用程式轉換器進行遙測Telemetry from Desktop App Converter

傳統型應用程式轉換器可能會收集您及您軟體使用方式的相關資訊,並將這項資訊傳送給 Microsoft。Desktop App Converter may collect information about you and your use of the software and send this info to Microsoft. 您可以在產品文件和 Microsoft 隱私權聲明中深入了解 Microsoft 的資料收集及使用方式。You can learn more about Microsoft's data collection and use in the product documentation and in the Microsoft Privacy Statement. 貴用戶玆同意遵守 Microsoft 隱私權聲明之所有適用條款。You agree to comply with all applicable provisions of the Microsoft Privacy Statement.

預設會針對傳統型應用程式轉換器啟用遙測。By default, telemetry will be enabled for the Desktop App Converter. 新增下列登錄機碼來設定所需設定的遙測︰Add the following registry key to configure telemetry to a desired setting:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\DesktopAppConverter
  • 使用設為 1 的 DWORD 來新增或編輯 DisableTelemetry 值。Add or edit the DisableTelemetry value by using a DWORD set to 1.
  • 若要啟用遙測,請移除此機碼或將值設為 0。To enable telemetry, remove the key or set the value to 0.

語言支援Language support

Desktop App Converter 不支援 Unicode;因此,無法在工具上使用中文字元或非 ASCII 字元。The Desktop App Converter does not support Unicode; thus, no Chinese characters or non-ASCII characters can be used with the tool.

Desktop App Converter 的已知問題Known issues with the Desktop App Converter

E_CREATING_ISOLATED_ENV_FAILED 和 E_STARTING_ISOLATED_ENV_FAILED 錯誤E_CREATING_ISOLATED_ENV_FAILED and E_STARTING_ISOLATED_ENV_FAILED errors

若您接收到其中一個錯誤,請確定您是使用來自下載中心的有效基礎映像。If you receive either of these errors, make sure that you're using a valid base image from the download center. 如果您使用的是正確的基礎映像,請嘗試在您的命令中使用 -Cleanup AllIf you’re using a valid base image, try using -Cleanup All in your command. 若此方法仍然無法解決您的問題,請將您的記錄檔傳送至 converter@microsoft.com,以幫助我們調查。If that does not work, please send us your logs at converter@microsoft.com to help us investigate.

New-ContainerNetwork:物件已存在錯誤New-ContainerNetwork: The object already exists error

當您設定一個新的基礎映像時,可能會收到這個錯誤。You might receive this error when you setup a new base image. 若在先前已安裝 Desktop App Converter 的程式開發人員電腦上有 Windows 測試人員正式發行前小眾測試版,則可能會發生此問題。This can happen if you have a Windows Insider flight on a developer machine that previously had the Desktop App Converter installed.

若要修正此問題,請嘗試在提升權限的命令提示字元中執行命令 Netsh int ipv4 reset,並重新啟動您的電腦。To resolve this issue, try running the command Netsh int ipv4 reset from an elevated command prompt, and then reboot your machine.

您的 .NET 應用程式使用「AnyCPU」組建選項進行編譯,但安裝仍然失敗Your .NET application is compiled with the "AnyCPU" build option and fails to install

若主要執行檔或任何相依性檔案是存放於 Program FilesWindows\System32 資料夾階層底下,就有可能會發生此問題。This can happen if the main executable or any of the dependencies were placed anywhere in the Program Files or Windows\System32 folder hierarchy.

若要修正此問題,請嘗試使用特定架構的桌面安裝程式 (32 位元或 64 位元) 產生 Windows 應用程式套件。To resolve this issue, try using your architecture-specific desktop installer (32 bit or 64 bit) to generate a Windows app package.

無法發行公用的並列 Fusion 組件Publishing public side-by-side Fusion assemblies won't work

在安裝期間,應用程式可以發行公用的並列 Fusion 組件,可存取任何其他處理序。During install, an application can publish public side-by-side Fusion assemblies, accessible to any other process. 在處理序啟用內容建立期間,這些組件是透過名為 CSRSS.exe 的系統處理序來擷取。During process activation context creation, these assemblies are retrieved by a system process named CSRSS.exe. 針對已轉換的處理序完成此動作之後,這些組件的啟用內容建立和模組載入將會失敗。When this is done for a converted process, activation context creation and module loading of these assemblies will fail. 並列 Fusion 組件會登錄於下列位置︰The side-by-side Fusion assemblies are registered in the following locations:

  • 登錄:HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\SideBySide\WinnersRegistry: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\SideBySide\Winners
  • 檔案系統︰%windir%\SideBySideFile System: %windir%\SideBySide

這是已知的限制,且目前沒有任何因應措施。This is a known limitation and no workaround currently exists. 但是,由於收件匣組件 (例如 ComCtl) 均隨附於作業系統,因此和它們相依是安全的。That said, Inbox assemblies, like ComCtl, are shipped with the OS, so taking a dependency on them is safe.

在 XML 中找到錯誤。Error found in XML. 'Executable' 屬性無效:根據其資料類型,數值 'MyApp.EXE' 無效The 'Executable' attribute is invalid - The value 'MyApp.EXE' is invalid according to its datatype

若您的應用程式中有副檔名為大寫 .EXE 的執行檔,就有可能發生這個錯誤。This can happen if the executables in your application have a capitalized .EXE extension. 雖然副檔名的大小寫並不會影響您應用程式的執行,但這仍有可能會使 DAC 產生這個錯誤。Although, the casing of this extension shouldn't affect whether your application runs, this can cause the DAC to generate this error.

若要修正此問題,請嘗試在封裝時指定 -AppExecutable 旗標,並使用小寫的「.exe」作為您主要可執行檔的副檔名 (例如:MYAPP.exe)。To resolve this issue, try specifying the -AppExecutable flag when you package, and use the lower case ".exe" as the extension of your main executable (For example: MYAPP.exe). 或者,您也可以將您應用程式當中所有執行檔的副檔名,從大寫變更為小寫 (例如:從 .EXE 改為 .exe)。Alternately you can change the casing for all executables in your application from uppercase to lowercase (For example: from .EXE to .exe).

毀損或格式錯誤的 Authenticode 簽章Corrupted or malformed Authenticode signatures

本節中的詳細資訊包括如何識別 Windows 應用程式套件中可攜式執行檔 (PE) 的問題,且套件中可能包含損毀或格式錯誤的 Authenticode 簽章。This section contains details on how to identify issues with Portable Executable (PE) files in your Windows app package that may contain corrupted or malformed Authenticode signatures. PE 檔 (.exe、.dll、.chm 等任何二進位檔案格式) 上無效的 Authenticode 簽章,會導致無法正確簽署您的套件,進而造成無法從 Windows 應用程式套件部署它。Invalid Authenticode signatures on your PE files, which may be in any binary format (e.g. .exe, .dll, .chm, etc.), will prevent your package from being signed properly, and thus prevent it from being deployable from an Windows app package.

PE 檔的 Authenticode 簽章的位置是由「選用標頭資料目錄」中的「憑證表格」及相關的「屬性憑證表格」來指定。The location of the Authenticode signature of a PE file is specified by the Certificate Table entry in the Optional Header Data Directories and the associated Attribute Certificate Table. 驗證簽章的期間,會使用這些結構中的資訊來找出 PE 檔上的簽章。During signature verification, the information specified in these structures is used to locate the signature on a PE file. 如果這些值已損毀,就可能使檔案的簽署看似無效。If these values get corrupted then it is possible for a file to appear to be invalidly signed.

為了使 Authenticode 簽章正確無誤,Authenticode 簽章必須符合下列條件:For the Authenticode signature to be correct, the following must be true of the Authenticode signature:

  • PE 檔中 WIN_CERTIFICATE 項目的開頭不可延伸超過可執行檔的結尾The start of the WIN_CERTIFICATE entry in the PE file cannot extend past the end of the executable
  • WIN_CERTIFCATE 項目應位在映像的結尾The WIN_CERTIFCATE entry should be located at the end of the image
  • WIN_CERTIFICATE 項目的大小必須是正值The size of the WIN_CERTIFICATE entry must be positive
  • 32 位元可執行檔的 WIN_CERTIFICATE 項目必須在 IMAGE_NT_HEADERS32 結構之後開始,64 位元可執行檔則是在 IMAGE_NT_HEADERS64 結構之後開始The WIN_CERTIFICATEentry must start after the IMAGE_NT_HEADERS32 structure for 32-bit executables and IMAGE_NT_HEADERS64 structure for 64-bit executables

如需詳細資訊,請參閱 Authenticode 可攜式可執行檔規格PE 檔格式規格For more details, please refer to the Authenticode Portal Executable specification and the PE file format specification.

請注意,嘗試簽署 Windows 應用程式套件時,SignTool.exe 可以輸出損毀或格式錯誤之二進位檔案的清單。Note that SignTool.exe can output a list of the corrupted or malformed binaries when attempting to sign an Windows app package. 若要這樣做,請將環境變數 APPXSIP_LOG 設定為 1 (如 set APPXSIP_LOG=1) 以啟用詳細資訊記錄,然後重新執行 SignTool.exe。To do this, enable verbose logging by setting the environment variable APPXSIP_LOG to 1 (e.g., set APPXSIP_LOG=1 ) and re-run SignTool.exe.

若要修正這些格式錯誤的二進位檔,請確定它們符合上述需求。To fix these malformed binaries, ensure they conform to the requirements above.

接下來的步驟Next steps

尋找您的問題解答Find answers to your questions

有任何問題嗎?Have questions? 請在 Stack Overflow 上發問。Ask us on Stack Overflow. 我們的團隊會監視這些標籤Our team monitors these tags. 您也可以在這裡發問。You can also ask us here.

執行您的應用程式/尋找並修正問題Run your application / find and fix issues

請參閱執行、偵錯及測試已封裝的桌面應用程式See Run, debug, and test a packaged desktop application

散發您的應用程式Distribute your app

請參閱散發封裝的傳統型應用程式See Distribute a packaged desktop application