<Commands> 元素 (啟動載入器)

發行項
01/12/2024

Commands 元素會實作 InstallChecks 元素底下元素所描述的測試，並在測試失敗時，宣告 ClickOnce 啟動載入器應該安裝的套件。

語法

<Commands
    Reboot
>
    <Command
        PackageFile
        Arguments
        EstimatedInstallSeconds
        EstimatedDiskBytes
        EstimatedTempBytes
        Log
    >
        <InstallConditions>
            <BypassIf
                Property
                Compare
                Value
                Schedule
            />
            <FailIf
                Property
                Compare
                Value
                String
                Schedule
            />
        </InstallConditions>
        <ExitCodes>
            <ExitCode
                Value
                Result
                String
            />
        </ExitCodes>
    </Command>
</Commands>

元素和屬性

Commands 元素為必要項。元素具有下列屬性。

屬性	描述
`Reboot`	選擇性。判斷如果任何套件傳回重新啟動結束代碼，系統是否應該重新啟動。下列清單顯示有效的值： `Defer`. 重新啟動會延遲直到某些未來時間。 `Immediate`. 如果其中一個套件傳回重新啟動結束代碼，就會立即重新啟動。 `None`. 導致忽略任何重新啟動要求。預設值為 `Immediate`。

Command

Command 項目是 Commands 項目的子項目。 Commands 元素可以有一或多個 Command 元素。該項目具有下列屬性。

屬性	描述
`PackageFile`	必要。要安裝的套件名稱應該是 `InstallConditions` 傳回 false 所指定的一或多個條件。套件必須使用 `PackageFile` 元素，在相同的檔案中定義。
`Arguments`	選擇性。要傳入套件檔案的一組命令列引數。
`EstimatedInstallSeconds`	選擇性。安裝套件需耗費的預估時間 (以秒為單位)。這個值會決定啟動載入器向使用者顯示的進度列大小。預設值為 0，在此情況下不會指定任何時間估計值。
`EstimatedDiskBytes`	選擇性。套件在安裝完成之後佔用的預估磁碟空間量 (以位元組為單位)。此值用於啟動載入器向使用者顯示的硬碟空間需求中。預設值為 0，在此情況下啟動載入器不會顯示任何硬碟空間需求。
`EstimatedTempBytes`	選擇性。套件所需的預估暫存磁碟空間量 (以位元組為單位)。
`Log`	選擇性。套件產生的記錄檔路徑，相對於套件的根目錄。

InstallConditions

InstallConditions 元素是 Command 元素的子項目。每個 Command 元素最多可有一個 InstallConditions 元素。如果沒有 InstallConditions 元素存在，Condition 指定的套件一律會執行。

BypassIf

BypassIf 元素是 InstallConditions 元素的子系，並描述不應該執行命令的正面條件。每個 InstallConditions 元素可以有零個或多個 BypassIf 元素。

BypassIf 具有下列屬性。

屬性	描述
`Property`	必要。要測試的屬性名稱。屬性必須先由 `InstallChecks` 元素的子系定義。如需詳細資訊，請參閱 <InstallChecks> 元素。
`Compare`	必要。要執行的比較類型。下列清單顯示有效的值：
`Value`	必要。要與屬性比較的值。
`Schedule`	選擇性。定義何時應該評估此規則的 `Schedule` 標記名稱。

FailIf

FailIf 元素是 InstallConditions 元素的子系，並描述應該停止安裝的正面條件。每個 InstallConditions 元素可以有零個或多個 FailIf 元素。

FailIf 具有下列屬性。

屬性	描述
`Property`	必要。要測試的屬性名稱。屬性必須先由 `InstallChecks` 元素的子系定義。如需詳細資訊，請參閱 <InstallChecks> 元素。
`Compare`	必要。要執行的比較類型。下列清單顯示有效的值：
`Value`	必要。要與屬性比較的值。
`String`	選擇性。失敗時要向使用者顯示的文字。
`Schedule`	選擇性。定義何時應該評估此規則的 `Schedule` 標記名稱。

ExitCodes

ExitCodes 元素是 Command 元素的子項目。 ExitCodes 元素包含一或多個 ExitCode 元素，可決定安裝應該執行的動作，以回應套件的結束代碼。 Command 元素底下可以有一個選擇性 ExitCode 元素。 ExitCodes 沒有任何屬性。

ExitCode

ExitCode 元素是 ExitCodes 元素的子項目。 ExitCode 元素可決定安裝應該執行的動作，以回應套件的結束代碼。 ExitCode 不包含子項目，並具有下列屬性。

屬性	描述
`Value`	必要。這個 `ExitCode` 元素套用的結束代碼值。
`Result`	必要。安裝應該如何回應此結束代碼。下列清單顯示有效的值： `Success`. 將套件標示為已成功安裝。 `SuccessReboot`. 將套件標示為已成功安裝，並指示系統重新啟動。 `Fail`. 將套件標示為失敗。 `FailReboot`. 將套件標示為失敗，並指示系統重新啟動。
`String`	選擇性。要向使用者顯示的值，以回應這個結束代碼。
`FormatMessageFromSystem`	選擇性。判斷是否要使用對應至結束代碼的系統提供錯誤訊息，或使用 `String` 中提供的值。有效值為 `true`，這表示使用系統提供的錯誤，以及 `false`，這表示使用 `String` 提供的字串。預設值為 `false`。如果此屬性是 `false`，但未設定 `String`，則會使用系統提供的錯誤。

範例

下列程式碼範例會定義安裝 .NET Framework 2.0 的命令。

<Commands Reboot="Immediate">
    <Command PackageFile="instmsia.exe"
             Arguments= ' /q /c:"msiinst /delayrebootq"'
             EstimatedInstallSeconds="20" >
        <InstallConditions>
           <BypassIf Property="VersionNT" Compare="ValueExists"/>
             BypassIf Property="VersionMsi" Compare="VersionGreaterThanOrEqualTo" Value="2.0"/>
        </InstallConditions>
        <ExitCodes>
            <ExitCode Value="0" Result="SuccessReboot"/>
            <ExitCode Value="1641" Result="SuccessReboot"/>
            <ExitCode Value="3010" Result="SuccessReboot"/>
            <DefaultExitCode Result="Fail" FormatMessageFromSystem="true" String="GeneralFailure" />
        </ExitCodes>
    </Command>
    <Command PackageFile="WindowsInstaller-KB884016-v2-x86.exe"
             Arguments= '/quiet /norestart'
             EstimatedInstallSeconds="20" >
      <InstallConditions>
          <BypassIf Property="Version9x" Compare="ValueExists"/>
          <BypassIf Property="VersionNT" Compare="VersionLessThan" Value="5.0.3"/>
          <BypassIf Property="VersionMsi" Compare="VersionGreaterThanOrEqualTo" Value="3.0"/>
          <FailIf Property="AdminUser" Compare="ValueEqualTo" Value="false" String="AdminRequired"/>
      </InstallConditions>
      <ExitCodes>
          <ExitCode Value="0" Result="Success"/>
          <ExitCode Value="1641" Result="SuccessReboot"/>
          <ExitCode Value="3010" Result="SuccessReboot"/>
          <DefaultExitCode Result="Fail" FormatMessageFromSystem="true" String="GeneralFailure" />
      </ExitCodes>
    </Command>
    <Command PackageFile="dotnetfx.exe"
         Arguments=' /q:a /c:"install /q /l"'
         EstimatedInstalledBytes="21000000"
         EstimatedInstallSeconds="300">

        <!-- These checks determine whether the package is to be installed -->
        <InstallConditions>
            <!-- Either of these properties indicates the .NET Framework is already installed -->
            <BypassIf Property="DotNetInstalled" Compare="ValueNotEqualTo" Value="0"/>

            <!-- Block install if user does not have adminpermissions -->
            <FailIf Property="AdminUser" Compare="ValueEqualTo" Value="false" String="AdminRequired"/>

            <!-- Block install on Windows 95 -->
            <FailIf Property="Version9X" Compare="VersionLessThan" Value="4.10" String="InvalidPlatformWin9x"/>

            <!-- Block install on Windows 8 or less -->
            <FailIf Property="VersionNT" Compare="VersionLessThan" Value="6.2" String="InvalidPlatformWinNT"/>

            <!-- Block install if Internet Explorer 5.01 or later is not present -->
            <FailIf Property="IEVersion" Compare="ValueNotExists" String="InvalidPlatformIE" />
            <FailIf Property="IEVersion" Compare="VersionLessThan" Value="5.01" String="InvalidPlatformIE" />

            <!-- Block install if the operating system does not support x86 -->
            <FailIf Property="ProcessorArchitecture" Compare="ValueNotEqualTo" Value="Intel" String="InvalidPlatformArchitecture" />
       </InstallConditions>

        <ExitCodes>
            <ExitCode Value="0" Result="Success"/>
            <ExitCode Value="3010" Result="SuccessReboot"/>
            <ExitCode Value="4097" Result="Fail" String="AdminRequired"/>
            <ExitCode Value="4098" Result="Fail" String="WindowsInstallerComponentFailure"/>
            <ExitCode Value="4099" Result="Fail" String="WindowsInstallerImproperInstall"/>
            <ExitCode Value="4101" Result="Fail" String="AnotherInstanceRunning"/>
            <ExitCode Value="4102" Result="Fail" String="OpenDatabaseFailure"/>
            <ExitCode Value="4113" Result="Fail" String="BetaNDPFailure"/>
            <DefaultExitCode Result="Fail" FormatMessageFromSystem="true" String="GeneralFailure" />
        </ExitCodes>

    </Command>
</Commands>

共用方式為