SystemUpdateManager Klasse

Referenz

Definition

Namespace:: Windows.System.Update

Wichtig

Einige Informationen beziehen sich auf Vorabversionen, die vor dem Release ggf. grundlegend überarbeitet werden. Microsoft übernimmt hinsichtlich der hier bereitgestellten Informationen keine Gewährleistungen, seien sie ausdrücklich oder konkludent.

Bearbeiten

Der SystemUpdateManager ermöglicht die interaktive Steuerung von Systemupdates.

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

Vererbung: Object Platform::Object IInspectable SystemUpdateManager

Attribute: ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Windows-Anforderungen

Gerätefamilie	Windows 10, version 1809 (eingeführt in 10.0.17763.0)
API contract	Windows.System.SystemManagementContract (eingeführt in v6.0)

Beispiele

SystemUpdateManager-Beispielcode

Hinweise

Der Systemupdateprozess weist die folgenden Zustände auf:

Erkennen. Ermitteln Sie, ob Updatepakete verfügbar sind.
Herunterladen Laden Sie die Updatepakete vom Server herunter.
Stage Entpacken Sie die Updatepakete, und stellen Sie sie bereit, um später committet zu werden.
Warten Sie auf den Neustart des Updatebetriebssystems. Das Update-Betriebssystem zeigt Zahnräder auf Windows 10 IoT Core an, während die Betriebssystemänderungen committet werden.
Ein Commit Starten Sie das Updatebetriebssystem, in dem Zahnräder angezeigt werden, während Systemupdateänderungen committet werden.
Starten Sie das aktualisierte Hauptbetriebssystem neu. An diesem Punkt ist der Updatevorgang abgeschlossen.

Die Installation eines Updatepakets umfasst das Staging des Updatepakets, indem die Dateien und Einstellungen in einen Stagingbereich extrahiert und dann später die mehrstufigen Änderungen committen. Updatepakete können nicht für Windows 10 IoT Core zurückgesetzt werden, sobald die Commitphase beginnt. Nicht commitierte Updatepakete, die nur bereitgestellt wurden, können bei Bedarf verworfen werden, indem das Update abgebrochen wird. Nachdem der Commitvorgang gestartet wurde, kann er nicht mehr unterbrochen werden.

Der automatische Updateprozess wird durch eine Richtlinie gesteuert. Ein OEM kann die Richtlinie über einen Richtlinien-Manager wie MDM oder DUC (Device Update Center) steuern.

Interaktive Updateprozesssitzungen werden vom Gerätebenutzer gesteuert. Richtlinien, die den automatischen Updateprozess zurückstellen würden, können während einer interaktiven Updateprozesssitzung überschrieben werden. Beispielsweise kann der Benutzer nach Updatepaketen suchen und diese mit einer interaktiven Prozesssitzung herunterladen, wenn eine automatische Updateprozesssitzung durch die aktuellen Richtlinien daran gehindert wird, diese Aktionen auszuführen. Der interaktive Updateprozess kann auch die Updatepakete insZenieren. Stagingupdatepakete entpacken die Pakete und bereiten die Dateien und Einstellungen im Paket vor, die committet werden sollen.

Nachdem die Updatepakete heruntergeladen und bereitgestellt wurden, kann der interaktive Updateprozess vom Entwickler fortgesetzt werden, indem er in das Updatebetriebssystem neu startet und die Updatepakete committ. Das Update-Betriebssystem ist ein sehr kleines Betriebssystem, das den alleinigen Zweck hat, Updatepakete zu committen. Auf Windows 10 IoT Core zeigt das Update-Betriebssystem einen Bildschirm mit sich bewegenden Zahnrädern an. Der Neustart in das Updatebetriebssystem kann als Reaktion auf Benutzereingaben oder als Teil der Geschäftslogik eines einzelnen Geräts erfolgen. RebootToCompleteInstall muss aufgerufen werden, um mit dem Updatebetriebssystem fortzufahren. Das Einschalten und Deaktivieren des Geräts oder die Verwendung einer alternativen API zum Neustarten des Geräts hat keine Auswirkungen. Alternativ kann der Entwickler bis zum nächsten geplanten Neustart des automatischen Updateprozesses warten, wie durch die aktuellen Richtlinien konfiguriert (z. B. außerhalb der aktiven Zeiten).

Vor der Installation

Vor dem Versuch, die SystemUpdateManager-API zu verwenden, sollte die Anwendung überprüfen, ob SystemManagementContract 6.0 vorhanden ist.

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";
}

Als Nächstes sollte die Anwendung sicherstellen, dass SystemUpdateManager unter der aktuellen Version und Edition von Windows unterstützt wird.

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)";
}

Anzeigen des Systemupdatestatus

Wenn der Vertrag vorhanden ist und die API unterstützt wird, registrieren Sie sich für Statusänderungsbenachrichtigungen:

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

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

Initialisieren Sie die Benutzeroberfläche:

// 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();

Die Beispielcodefunktion UpdateVisualState führt folgende Aktionen aus:

Aktualisierungen das Statusfeld.
Aktualisierungen den Zeitpunkt der letzten Aktualisierungsprüfung.
Aktualisierungen den VisualStateManager-Zustand.
Aktualisierungen Statusanzeigen für Status mit Status.
Aktualisierungen den Status des Aktualisierungselements.

Der Code lautet wie folgt:

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;
    }
}

Installieren von Systemupdates

Wenn der Gerätebesitzer richtlinien für den automatischen Updateprozess konfiguriert hat, sodass er steuert, wann Downloads gestartet werden, oder wenn kunden den Updateprozess interaktiv starten können, sucht der Aufruf von SystemUpdateManager.StartInstall nach Updatepaketen und lädt die Updatepakete herunter, falls vorhanden. Dies ist eine Fire-and-Forget-Methode, die asynchron ausgeführt wird, aber sofort zurückgibt.

Der Status des Aktualisierungsprozesses kann über das StateChanged-Ereignis und die State-Eigenschaft nachverfolgt werden. Wenn bereits ein Download ausgeführt wird, wird der Aufruf sofort ohne Fehler zurückgegeben. Wenn die Aufmerksamkeit des Benutzers erforderlich ist, um fortzufahren, wird der Status auf AttentionRequired festgelegt, und der AttentionRequiredReason-Wert ist festgelegt. Wenn ein nicht behebbarer Fehler auftritt, wird der Status auf ExtendedError und die ExtendedError-Eigenschaft festgelegt.

Um ein Update zu starten, rufen Sie SystemUpdateManager.StartInstall auf. Wenn der Parameter SystemUpdateStartInstallAction.UpToReboot lautet, wird die Installation fortgesetzt, bis ein Neustart erforderlich ist. Wenn der Parameter SystemUpdateStartInstallAction.AllowReboot lautet, wird die Installation fortgesetzt und neu gestartet, sobald sie von der Richtlinie zugelassen wird.

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

Um eine Systemupdateinstallation zu committen, ist manchmal ein Neustart erforderlich. In diesem Fall entspricht SystemUpdateManager.StateSystemUpdateManagerState.RebootRequired. Beachten Sie, dass ein normaler Neustart nicht funktioniert, um die Änderungen in diesem Zustand abzuschließen. Sie müssen SystemUpdateManager.RebootToCompleteInstall aufrufen oder warten, bis der automatisch geplante Neustart während der Systemupdatefenster (außerhalb der aktiven Benutzerzeiten) erfolgt.

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

Benutzeraktivzeiten verwalten:

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;
    }
}

Fehler beim letzten Systemupdate abrufen

Wenn während der Installation eines Systemupdates ein Fehler auftritt, wird SystemUpdateManager.LastErrorInfo festgelegt. Hier sehen Sie ein Beispiel für die Anzeige der letzten Fehlerinformationen:

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");
}

Flight Ring für Systemupdates

Der Flight-Ring kann leer, Canary, Selfhost oder benutzerdefiniert sein. Wenn der Wert leer ist, wird auf der Benutzeroberfläche "Keine" ausgewählt. Andernfalls, wenn es sich nicht um Canary oder Selfhost handelt, gehen Sie davon aus, dass der Ring benutzerdefinierter ist, und speichern Sie ihn in der Ui-Liste.

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);
        }
    }
}

Automatische Neustarts blockieren

Um dem Updatedienst mitzuteilen, dass die Systemupdates nicht zulässig sind, rufen Sie SystemUpdateManager.UnblockAutomaticRebootAsync(id) auf, wobei id eine eindeutige Zeichenfolge ist, die aus Zahlen, Buchstaben und Bindestrichen besteht. Wenn die kritische Codeausführung abgeschlossen ist, sollte der Code SystemUpdateManager.UnblockAutomaticRebootAsync für jede ID aufrufen, die an BlockAutomaticRebootAsync übergeben wurde.

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);
    }
}

Die Anwendung muss die Funktion systemManagement deklarieren. Wird nur auf Windows 10 IoT Core unterstützt.

Eigenschaften

AttentionRequiredReason	Grund, warum Die Aufmerksamkeit des Benutzers erforderlich ist.
DownloadProgress	Prozentsatz des Downloadfortschritts.
ExtendedError	Erweiterte Fehlerinformationen, falls verfügbar.
InstallProgress	Prozentsatz des Installationsfortschritts.
LastErrorInfo	Informationen zum letzten fehlgeschlagenen Systemupdate.
LastUpdateCheckTime	Zeitpunkt der letzten Überprüfung auf Updates.
LastUpdateInstallTime	Zeitpunkt der letzten Updateinstallation.
State	Der aktuelle Status von SystemUpdateManager.
UserActiveHoursEnd	Ruft den Endzeitwert der aktiven Stunden des Benutzers ab.
UserActiveHoursMax	Ruft das maximal zulässige Intervall zwischen UserActiveHoursStart und UserActiveHoursEnd in Stunden ab.
UserActiveHoursStart	Ruft den Startzeitwert der aktiven Stunden des Benutzers ab.

Methoden

BlockAutomaticRebootAsync(String)	Automatische Neustarts für Updates blockieren, bis UnblockAutomaticRebootAsync aufgerufen wird oder bis ein Neustart durch die Systemrichtlinie erzwungen wird.
GetAutomaticRebootBlockIds()	Ruft die IDs von Anforderungen für automatische Neustartblocks ab.
GetFlightRing()	Rufen Sie den Flight Ring ab.
GetUpdateItems()	Ruft eine Liste der ausstehenden Updateelemente ab.
IsSupported()	Gibt an, ob diese API auf diesem Gerät unterstützt wird.
RebootToCompleteInstall()	Startet das Gerät neu, um die Installation abzuschließen, wenn ein Neustart erforderlich ist.
SetFlightRing(String)	Legt den Flight-Ring fest.
StartCancelUpdates()	Beginnen Sie mit dem Abbrechen von Updates, wenn Updates ausgeführt werden.
StartInstall(SystemUpdateStartInstallAction)	Starten Sie die Erkennung, den Download und die Installation ausstehender Updates.
TrySetUserActiveHours(TimeSpan, TimeSpan)	Versuchen Sie, die benutzerdefinierten Aktiven Stunden festzulegen, in denen automatische Neustarts für Updates nicht zulässig sind.
UnblockAutomaticRebootAsync(String)	Heben Sie die Blockierung automatischer Updateneustarts auf, wenn sie blockiert werden.

Ereignisse

StateChanged

Benachrichtigungsereignis zur Änderung der Zustandseigenschaft.

Gilt für:

Freigeben über