SystemUpdateManager 類別

參考

定義

命名空間:: Windows.System.Update

重要

部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

編輯

SystemUpdateManager允許系統更新的互動式控制。

public ref class SystemUpdateManager abstract sealed

/// [Windows.Foundation.Metadata.ContractVersion(Windows.System.SystemManagementContract, 393216)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class SystemUpdateManager final

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.System.SystemManagementContract), 393216)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public static class SystemUpdateManager

Public Class SystemUpdateManager

繼承: Object Platform::Object IInspectable SystemUpdateManager

屬性: ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Windows 需求

裝置系列	Windows 10, version 1809 (已於 10.0.17763.0 引進)
API contract	Windows.System.SystemManagementContract (已於 v6.0 引進)

範例

SystemUpdateManager 範例程式碼

備註

系統更新程式具有下列狀態：

偵測。判斷是否有任何可用的更新套件。
下載。從伺服器下載更新套件。
階段。解除封裝更新套件，並暫存這些套件以供稍後認可。
等候重新開機至更新作業系統。更新 OS 會在認可 OS 變更時顯示Windows 10 IoT 核心版齒輪。
認可。開機進入更新 OS，其中顯示系統更新變更認可時的齒輪。
重新開機至更新的主要 OS。此時，更新程式已完成。

安裝更新套件包括將檔案和設定解壓縮至預備區域，然後認可暫存變更，以暫存更新套件。一旦開始認可階段，就無法在Windows 10 IoT 核心版回復更新套件。取消更新，可以視需要捨棄僅暫存的未認可更新套件。一旦啟動認可程式，就無法中斷。

自動更新程式是由原則所控制。 OEM 可以透過 MDM 之類的原則管理員或 DUC (裝置更新中心) 來控制原則。

互動式更新程式會話是由裝置使用者所控制。在互動式更新程式會話期間，可能會覆寫延遲自動更新程式的原則。例如，使用者可以掃描更新套件，並在自動更新進程會話遭到封鎖而無法由目前原則執行這些動作時，使用互動式進程會話下載這些套件。互動式更新程式也可以暫存更新套件。預備更新套件會解壓縮套件，並準備要認可的套件中的檔案和設定。

下載並暫存更新套件之後，開發人員可能會重新開機至更新 OS 並認可更新套件，以繼續互動式更新程式。更新 OS 是一個非常小的 OS，其唯一用途是認可更新套件。在Windows 10 IoT 核心版更新作業系統會顯示具有移動齒輪的畫面。重新開機至更新 OS 可以回應使用者輸入，或作為單一用途裝置商務邏輯的一部分。必須呼叫 RebootToCompleteInstall 才能繼續更新作業系統。開啟和關閉電源，或使用替代 API 重新開機裝置不會有任何作用。或者，開發人員可以選擇等到目前原則所設定的下一個排程自動更新程式重新開機視窗 (使用時間以外，例如。)

安裝之前

嘗試使用 SystemUpdateManager API 之前，應用程式應該先確認 SystemManagementContract 6.0 存在。

if (!ApiInformation.IsApiContractPresent("Windows.System.SystemManagementContract", 6, 0))
{
    // SystemUpdateManager was first implemented in SystemManagementContract 6.0
    VisualStateManager.GoToState(this, "NotSupported", false);
    UpdateStateTextBlock.Text = "Windows.System.SystemManagementContract 6.0 not found";
}

接下來，應用程式應該確定目前版本和 Windows 版本支援 SystemUpdateManager 。

else if (!SystemUpdateManager.IsSupported())
{
    // The API must be supported by the current edition of Windows
    // This can also return false if the application doesn't have the systemManagement capability
    VisualStateManager.GoToState(this, "NotSupported", false);
    UpdateStateTextBlock.Text = "System Update not supported (or systemManagement capability missing)";
}

顯示系統更新狀態

如果合約存在且支援 API，請註冊狀態變更通知：

// Register for state change notifications
SystemUpdateManager.StateChanged += SystemUpdateManager_StateChanged;

private void SystemUpdateManager_StateChanged(object sender, object args)
{
    var action = _dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
        UpdateVisualState();
    });
}

初始化使用者介面：

// Display update information
UpdateStateTextBlock.Text = GetResourceString(SystemUpdateManager.State.ToString());
LastChecked.Text = SystemUpdateManager.LastUpdateCheckTime.ToString("G");
LastInstalled.Text = SystemUpdateManager.LastUpdateInstallTime.ToString("G");

// Attach ViewModel to ListView
UpdateItemsListView.ItemsSource = _items;

// Initialize the visual state
UpdateVisualState();
UpdateFlightRing();

BlockAutoReboot.IsOn = IsAutomaticRebootBlockOn();

UpdateVisualState範例程式碼函式會執行下列動作：

更新狀態欄位。
更新上次更新檢查時間。
更新 VisualStateManager 狀態。
更新進度狀態的進度列。
更新更新專案狀態。

此程式碼如下：

private void UpdateVisualState()
{
    // Update the state text
    UpdateStateTextBlock.Text = GetResourceString(SystemUpdateManager.State.ToString());

    // Update the last update check time
    LastChecked.Text = SystemUpdateManager.LastUpdateCheckTime.ToString("G");

    // Change the VisualStateManager state based on the current SystemUpdateManagerState
    var state = SystemUpdateManager.State;
    Debug.WriteLine($"State={state}");
    switch (state)
    {
        case SystemUpdateManagerState.Idle:
        case SystemUpdateManagerState.Detecting:
        case SystemUpdateManagerState.Downloading:
        case SystemUpdateManagerState.Installing:
        case SystemUpdateManagerState.RebootRequired:
            VisualStateManager.GoToState(this, SystemUpdateManager.State.ToString(), false);
            break;

        case SystemUpdateManagerState.AttentionRequired:
            AttentionRequiredTextBlock.Text = GetResourceString(SystemUpdateManager.AttentionRequiredReason.ToString());
            VisualStateManager.GoToState(this, "AttentionRequired", false);
            break;

        default:
            VisualStateManager.GoToState(this, "UnknownState", false);
            break;
    }

    // Update progress for states with progress
    switch (SystemUpdateManager.State)
    {
        case SystemUpdateManagerState.Downloading:
            Debug.WriteLine($"Downloading={SystemUpdateManager.DownloadProgress}");
            SessionDownloadProgressBar.Value = SystemUpdateManager.DownloadProgress;
            break;
        case SystemUpdateManagerState.Installing:
            Debug.WriteLine($"Installing={SystemUpdateManager.InstallProgress}");
            SessionDownloadProgressBar.Value = SystemUpdateManager.DownloadProgress;
            SessionInstallProgressBar.Value = SystemUpdateManager.InstallProgress;
            break;
    }

    // Update progress items
    switch (SystemUpdateManager.State)
    {
        case SystemUpdateManagerState.Downloading:
        case SystemUpdateManagerState.Installing:
            foreach (var updateItem in SystemUpdateManager.GetUpdateItems())
            {
                var viewModelItem = _items.Where(x => x.Id == updateItem.Id).FirstOrDefault();
                if (viewModelItem != null)
                {
                    viewModelItem.Update(updateItem);
                }
                else
                {
                    _items.Add(new UpdateItemViewModel(updateItem));
                }
            }
            break;
    }
}

安裝系統更新

如果裝置擁有者已設定自動更新程式原則，以便在下載啟動時控制，或選擇允許客戶以互動方式啟動更新程式，則呼叫 SystemUpdateManager.StartInstall 將會檢查更新套件，並在有更新套件時下載更新套件。這是以非同步方式執行但立即傳回的引發和忘記方法。

您可以透過 StateChanged 事件和 State 屬性來追蹤更新程式的進度。如果下載正在進行中，呼叫會立即傳回，而不會發生錯誤。如果需要使用者注意才能繼續，狀態會設定為 AttentionRequired ，而且已設定 AttentionRequiredReason 。如果發生無法復原的錯誤，狀態會設定為 ExtendedError，並設定 ExtendedError 屬性。

若要開始更新，請呼叫 SystemUpdateManager.StartInstall。如果參數是 SystemUpdateStartInstallAction.UpToReboot ，則安裝會繼續進行，直到需要重新開機為止。如果參數為 SystemUpdateStartInstallAction.AllowReboot ，則安裝會在原則允許時立即繼續並重新啟動。

private void CheckForUpdates_Click(object sender, RoutedEventArgs e)
{
    if (SystemUpdateManager.State == SystemUpdateManagerState.Idle)
    {
        SystemUpdateManager.StartInstall(SystemUpdateStartInstallAction.UpToReboot);
    }
}

若要認可系統更新安裝，有時需要重新開機。在此情況下 ，SystemUpdateManager.State 會等於 SystemUpdateManagerState.RebootRequired。請注意，正常重新開機無法完成此狀態的變更。您必須呼叫 SystemUpdateManager.RebootToCompleteInstall ，或等候在系統更新期間自動排程重新開機，) 使用者作用時間以外 (發生。

private void RebootNow_Click(object sender, RoutedEventArgs e)
{
    if (SystemUpdateManager.State == SystemUpdateManagerState.RebootRequired)
    {
        SystemUpdateManager.RebootToCompleteInstall();
    }
}

管理使用者使用時間：

private void ChangeActiveHours_Click(object sender, RoutedEventArgs e)
{
    StartTime.Time = SystemUpdateManager.UserActiveHoursStart;
    EndTime.Time = SystemUpdateManager.UserActiveHoursEnd;
    ActiveHoursErrorText.Visibility = Visibility.Collapsed;
    ActiveHoursPopup.IsOpen = true;
}

private void SaveActiveHours_Click(object sender, RoutedEventArgs e)
{
    bool succeeded = SystemUpdateManager.TrySetUserActiveHours(StartTime.Time, EndTime.Time);
    if (succeeded)
    {
        ActiveHoursPopup.IsOpen = false;
    }
    else
    {
        // Active hours not set display error message
        string format = GetResourceString("ActiveHoursErrorFormat");
        ActiveHoursErrorText.Text = String.Format(format, SystemUpdateManager.UserActiveHoursMax);
        ActiveHoursErrorText.Visibility = Visibility.Visible;
    }
}

取得上次系統更新錯誤

如果在安裝系統更新期間發生錯誤，則會設定 SystemUpdateManager.LastErrorInfo 。以下是顯示最後一個錯誤資訊的範例：

var info = SystemUpdateManager.LastErrorInfo;
if (SystemUpdateManager.LastErrorInfo.ExtendedError == null)
{
    NoErrorText.Visibility = Visibility.Visible;
    LastErrorInfoPanel.Visibility = Visibility.Collapsed;
}
else
{
    NoErrorText.Visibility = Visibility.Collapsed;
    LastErrorInfoPanel.Visibility = Visibility.Visible;
    ErrorStateTextBlock.Text = GetResourceString(info.State.ToString());
    HResultTextBlock.Text = (info.ExtendedError == null) ? "No Error Data" : info.ExtendedError.Message;
    IsInteractiveTextBlock.Text = GetResourceString(info.IsInteractive ? "Yes" : "No");
}

系統更新正式發行前小眾測試版通道

正式發行前小眾測試版通道可以是空白、Canary、Selfhost 或使用者定義。如果值是空的，則會在 UI 中選取 [無]。否則，如果它不是 Canary 或 Selfhost，則假設通道是使用者定義的，並將它儲存至 UI 清單。

private void UpdateFlightRing()
{
    var ring = Windows.System.Update.SystemUpdateManager.GetFlightRing();
    for (int i = 0; i < FlightRingCombo.Items.Count(); i++)
    {
        if (ring == FlightRingCombo.Items[i] as string)
        {
            FlightRingCombo.SelectedIndex = i;
            return;
        }
    }

    // if the current ring is non-empty and is not in the list save it to the list
    if (!String.IsNullOrEmpty(ring))
    {
        int index = FlightRingCombo.Items.Count;
        FlightRingCombo.Items.Insert(index, ring);
        FlightRingCombo.SelectedIndex = index;
        return;
    }

    FlightRingCombo.SelectedIndex = 0;
}

private void FlightRingCombo_SelectionChanged(object sender, SelectionChangedEventArgs e)
{
    var oldRing = SystemUpdateManager.GetFlightRing();
    var newRing = e.AddedItems[0].ToString();
    Debug.WriteLine($"newRing={newRing} oldRing={oldRing}");

    if (oldRing != newRing)
    {
        if (newRing == "None")
        {
            // only set if previous ring was not null or empty
            if (!String.IsNullOrEmpty(oldRing))
            {
                Windows.System.Update.SystemUpdateManager.SetFlightRing(String.Empty);
            }
        }
        else
        {
            Windows.System.Update.SystemUpdateManager.SetFlightRing(newRing);
        }
    }
}

封鎖自動重新開機

若要告知更新服務不允許系統更新，請呼叫 SystemUpdateManager.UnblockAutomaticRebootAsync (id) ，其中 id 是由數位、字母和破折號組成的唯一字串。完成關鍵程式碼執行時，程式碼應該針對傳入BlockAutomaticRebootAsync的每個識別碼呼叫SystemUpdateManager.UnblockAutomaticRebootAsync

if (BlockAutoReboot.IsOn)
{
    await SystemUpdateManager.BlockAutomaticRebootAsync(Guid.NewGuid().ToString());
}
else
{
    var ids = SystemUpdateManager.GetAutomaticRebootBlockIds();
    foreach(var id in ids)
    {
        bool unblocked = await SystemUpdateManager.UnblockAutomaticRebootAsync(id);
    }
}

應用程式必須宣告 systemManagement 功能。僅支援Windows 10 IoT 核心版。

屬性

AttentionRequiredReason	需要使用者注意的原因。
DownloadProgress	下載進度百分比。
ExtendedError	如果有的話，擴充錯誤資訊。
InstallProgress	安裝進度百分比。
LastErrorInfo	上次失敗系統更新的相關資訊。
LastUpdateCheckTime	上次檢查更新的時間。
LastUpdateInstallTime	上次安裝更新的時間。
State	SystemUpdateManager的目前狀態。
UserActiveHoursEnd	取得使用者使用時間結束時間值。
UserActiveHoursMax	取得 UserActiveHoursStart 與 UserActiveHoursEnd 之間允許的最大間隔，以小時為單位。
UserActiveHoursStart	取得使用者使用時間開始時間值。

方法

BlockAutomaticRebootAsync(String)	封鎖自動重新開機以進行更新，直到呼叫 UnblockAutomaticRebootAsync，或直到系統原則強制執行重新開機為止。
GetAutomaticRebootBlockIds()	取得自動重新開機封鎖要求的識別碼。
GetFlightRing()	取得正式發行前小眾測試版通道。
GetUpdateItems()	取得擱置的更新專案清單。
IsSupported()	指出此裝置是否支援此 API。
RebootToCompleteInstall()	如果需要重新開機，請將裝置重新開機以完成安裝。
SetFlightRing(String)	設定正式發行前小眾測試版通道。
StartCancelUpdates()	如果有任何更新正在進行中，請開始取消更新。
StartInstall(SystemUpdateStartInstallAction)	啟動擱置更新的偵測、下載和安裝。
TrySetUserActiveHours(TimeSpan, TimeSpan)	嘗試設定使用者定義的使用時間，在此期間，不允許自動重新開機更新。
UnblockAutomaticRebootAsync(String)	如果封鎖，解除封鎖自動更新重新開機。

事件

StateChanged

狀態屬性變更通知事件。

適用於

共用方式為