透過套件支援架構執行指令碼Run scripts with the Package Support Framework

腳本可讓 IT 專業人員在使用 MSIX 封裝之後,將應用程式動態地自訂到使用者的環境。Scripts enable IT Pros to customize an application dynamically to the user's environment after it is packaged using MSIX. 例如,您可以使用腳本來設定您的資料庫、設定 VPN、掛接共用磁片磁碟機,或動態執行授權檢查。For example, you can use scripts to configure your database, set up a VPN, mount a shared drive, or perform a license check dynamically. 腳本提供許多彈性。Scripts provide a lot of flexibility. 它們可能會變更登錄機碼,或根據電腦或伺服器設定來執行檔案修改。They may change registry keys or perform file modifications based on the machine or server configuration.

您可以使用封裝支援架構 (.PSF) 在封裝的應用程式可執行檔執行之前執行一個 PowerShell 腳本,並在應用程式可執行檔執行之後,執行一個 PowerShell 腳本以進行清除。You can use the Package Support Framework (PSF) to run one PowerShell script before a packaged application executable runs and one PowerShell script after the application executable runs to clean up. 應用程式資訊清單中定義的每個應用程式可執行檔都可以有自己的腳本。Each application executable defined in the application manifest can have its own scripts. 您可以將腳本設定為只在第一個應用程式啟動時執行一次,而不會顯示 PowerShell 視窗,讓使用者不會錯誤地結束腳本。You can configure the script to run once only on the first app launch and without showing the PowerShell window so users won't end the script prematurely by mistake. 還有其他選項可以設定腳本執行的方式,如下所示。There are other options to configure the way scripts can run, shown below.

必要條件Prerequisites

若要啟用腳本來執行,您必須將 PowerShell 執行原則設定為 RemoteSignedTo enable scripts to run, you need to set the PowerShell execution policy to RemoteSigned. 您可以執行此命令來執行此動作:You can do this by running this command:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

您必須針對64位 PowerShell 可執行檔和32位 PowerShell 可執行檔設定執行原則。The execution policy needs to be set for both the 64-bit PowerShell executable and the 32-bit PowerShell executable. 請務必開啟每個版本的 PowerShell,然後執行上面所示的其中一個命令。Make sure to open each version of PowerShell and run one of the commands shown above.

以下是每個可執行檔的位置。Here are the locations of each executable.

  • 64 位元電腦:64-bit computer:
    • 64位可執行檔:% SystemRoot% \system32\WindowsPowerShell\v1.0\powershell.exe64-bit executable: %SystemRoot%\system32\WindowsPowerShell\v1.0\powershell.exe
    • 32位可執行檔:% SystemRoot% \SysWOW64\WindowsPowerShell\v1.0\powershell.exe32-bit executable: %SystemRoot%\SysWOW64\WindowsPowerShell\v1.0\powershell.exe
  • 32 位元電腦:32-bit computer:
    • 32位可執行檔:% SystemRoot% \system32\WindowsPowerShell\v1.0\powershell.exe32-bit executable: %SystemRoot%\system32\WindowsPowerShell\v1.0\powershell.exe

如需 PowerShell 執行原則的詳細資訊,請參閱 這篇文章For more information about PowerShell execution policies, see this article.

請務必同時在套件中包含 StartingScriptWrapper.ps1 檔案,並將它放在與可執行檔相同的資料夾中。Make sure to also include the StartingScriptWrapper.ps1 file in your package and place it in the same folder as your executable. 您可以從 .Psf NuGet 套件複製這個檔案。You can copy this file from the PSF NuGet package.

啟用腳本Enable scripts

若要指定每個封裝的應用程式可執行檔將執行的腳本,您需要修改檔案 上的config.jsTo specify what scripts will run for each packaged application executable, you need to modify the config.json file. 若要告訴 .PSF 在執行封裝的應用程式之前執行腳本,請新增名為的設定專案 startScriptTo tell PSF to run a script before the execution of the packaged application, add a configuration item called startScript. 若要告訴 .PSF 在封裝的應用程式完成後執行腳本,請新增名為的設定專案 endScriptTo tell PSF to run a script after the packaged application finishes add a configuration item called endScript.

腳本設定專案Script configuration items

以下是可供腳本使用的設定專案。The following are the configuration items available for the scripts. 結束腳本會忽略 waitForScriptToFinish 和設定 stopOnScriptError 專案。The ending script ignores the waitForScriptToFinish and stopOnScriptError configuration items.

機碼名稱Key name 值類型Value type 必要?Required? 預設Default 描述Description
scriptPath 字串string Yes N/AN/A 腳本的路徑,包括名稱和副檔名。The path to the script including the name and extension. 如果有指定,路徑會相對於應用程式的工作目錄,否則會從封裝的根目錄開始。The path is relative to the application's working directory if specified, otherwise, it starts at the root directory of the package.
scriptArguments 字串string NoNo emptyempty 以空格分隔的引數清單。Space delimited argument list. PowerShell 腳本呼叫的格式是相同的。The format is the same for a PowerShell script call. 這個字串會附加至, scriptPath 以進行有效的 PowerShell.exe 呼叫。This string gets appended to scriptPath to make a valid PowerShell.exe call.
runInVirtualEnvironment booleanboolean No truetrue 指定腳本是否應在封裝應用程式執行所在的相同虛擬環境中執行。Specifies whether the script should run in the same virtual environment that the packaged application runs in.
runOnce booleanboolean No truetrue 指定腳本是否應針對每個使用者執行一次(每個版本)。Specifies whether the script should run once per user, per version.
showWindow booleanboolean No falsefalse 指定是否顯示 PowerShell 視窗。Specifies whether the PowerShell window is shown.
stopOnScriptError booleanboolean No falsefalse 指定啟動腳本失敗時是否要結束應用程式。Specifies whether to exit the application if the starting script fails.
waitForScriptToFinish booleanboolean No truetrue 指定封裝的應用程式是否應該等待啟動腳本完成,再開始進行。Specifies whether the packaged application should wait for the starting script to finish before starting.
timeout DWORDDWORD No INFINITEINFINITE 允許腳本執行的時間長度。How long the script will be allowed to execute. 經過一段時間後,腳本就會停止。When the time elapses, the script will be stopped.

注意

stopOnScriptError: true waitForScriptToFinish: false 不支援設定範例應用程式的和。Setting stopOnScriptError: true and waitForScriptToFinish: false for the sample application is not supported. 如果您同時設定這兩個設定專案,.PSF 會傳回錯誤 ERROR_BAD_CONFIGURATION。If you set both of these configuration items, PSF will return the error ERROR_BAD_CONFIGURATION.

範例組態Sample configuration

以下是使用兩個不同應用程式可執行檔的範例設定。Here is a sample configuration using two different application executables.

{
  "applications": [
    {
      "id": "Sample",
      "executable": "Sample.exe",
      "workingDirectory": "",
      "stopOnScriptError": false,
      "startScript":
      {
        "scriptPath": "RunMePlease.ps1",
        "scriptArguments": "\\\"First argument\\\" secondArgument",
        "runInVirtualEnvironment": true,
        "showWindow": true,
        "waitForScriptToFinish": false
      },
      "endScript":
      {
        "scriptPath": "RunMeAfter.ps1",
        "scriptArguments": "ThisIsMe.txt"
      }
    },
    {
      "id": "CPPSample",
      "executable": "CPPSample.exe",
      "workingDirectory": "",
      "startScript":
      {
        "scriptPath": "CPPStart.ps1",
        "scriptArguments": "ThisIsMe.txt",
        "runInVirtualEnvironment": true
      },
      "endScript":
      {
        "scriptPath": "CPPEnd.ps1",
        "scriptArguments": "ThisIsMe.txt",
        "runOnce": false
      }
    }
  ],
  "processes": [
    ...(taken out for brevity)
  ]
}