Многоэтапное упорядоченное выполнение

2021-11-12

Многошаговое упорядоченное выполнение позволяет выполнять задачи до и после установки при развертывании обновления по воздуху. Эта функция является частью схемы манифеста обновления версии Public Preview Refresh v4.

Ознакомьтесь с документацией по манифесту обновления перед просмотром следующих изменений в рамках общедоступного выпуска обновления предварительной версии.

При многошаговом упорядочении выполнения существует два типа шагов:

Встроенный шаг (по умолчанию)
Шаг ссылки

Пример манифеста обновления с одним встроенным шагом:

{
    "updateId": {...},
    "isDeployable": true,
    "compatibility": [
        {
            "deviceManufacturer": "du-device",
            "deviceModel": "e2e-test"
        }
    ],
    "instructions": {
        "steps": [
            {
                "description": "Example APT update that install libcurl4-doc on a host device.",
                "handler": "microsoft/apt:1",
                "files": [
                    "apt-manifest-1.0.json"
                ],
                "handlerProperties": {
                    "installedCriteria": "apt-update-test-1.0"
                }
            }
        ]
    },
    "manifestVersion": "4.0",
    "importedDateTime": "2021-11-16T14:54:55.8858676Z",
    "createdDateTime": "2021-11-16T14:50:47.3511877Z"
}

Пример манифеста обновления с двумя последовательными шагами:

{
    "updateId": {...},
    "isDeployable": true,
    "compatibility": [
        {
            "deviceManufacturer": "du-device",
            "deviceModel": "e2e-test"
        }
    ],
    "instructions": {
        "steps": [
            {
                "description": "Install libcurl4-doc on host device",
                "handler": "microsoft/apt:1",
                "files": [
                    "apt-manifest-1.0.json"
                ],
                "handlerProperties": {
                    "installedCriteria": "apt-update-test-2.2"
                }
            },
            {
                "description": "Install tree on host device",
                "handler": "microsoft/apt:1",
                "files": [
                    "apt-manifest-tree-1.0.json"
                ],
                "handlerProperties": {
                    "installedCriteria": "apt-update-test-tree-2.2"
                }
            }
        ]
    },
    "manifestVersion": "4.0",
    "importedDateTime": "2021-11-16T20:21:33.6514738Z",
    "createdDateTime": "2021-11-16T20:19:29.4019035Z"
}

Пример манифеста обновления с одним эталонным шагом:

Родительское обновление, ссылающееся на дочернее обновление

{
    "updateId": {...},
    "isDeployable": true,
    "compatibility": [
        {
            "deviceManufacturer": "du-device",
            "deviceModel": "e2e-test"
        }
    ],
    "instructions": {
        "steps": [
            {
                "type": "reference",
                "description": "Cameras Firmware Update",
                "updateId": {
                    "provider": "contoso",
                    "name": "virtual-camera",
                    "version": "1.2"
                }
            }
        ]
    },
    "manifestVersion": "4.0",
    "importedDateTime": "2021-11-17T07:26:14.7484389Z",
    "createdDateTime": "2021-11-17T07:22:10.6014567Z"
}

Дочернее обновление с помощью встроенных шагов

{
    "updateId": {
        "provider": "contoso",
        "name": "virtual-camera",
        "version": "1.2"
    },
    "isDeployable": false,
    "compatibility": [
        {
            "group": "cameras"
        }
    ],
    "instructions": {
        "steps": [
            {
                "description": "Cameras Update - pre-install step",
                "handler": "microsoft/script:1",
                "files": [
                    "contoso-camera-installscript.sh"
                ],
                "handlerProperties": {
                    "scriptFileName": "contoso-camera-installscript.sh",
                    "arguments": "--pre-install-sim-success --component-name --component-name-val --component-group --component-group-val --component-prop path --component-prop-val path",
                    "installedCriteria": "contoso-virtual-camera-1.2-step-0"
                }
            },
            {
                "description": "Cameras Update - firmware installation (failure - missing file)",
                "handler": "microsoft/script:1",
                "files": [
                    "contoso-camera-installscript.sh",
                    "camera-firmware-1.1.json"
                ],
                "handlerProperties": {
                    "scriptFileName": "missing-contoso-camera-installscript.sh",
                    "arguments": "--firmware-file camera-firmware-1.1.json --component-name --component-name-val --component-group --component-group-val --component-prop path --component-prop-val path",
                    "installedCriteria": "contoso-virtual-camera-1.2-step-1"
                }
            },
            {
                "description": "Cameras Update - post-install step",
                "handler": "microsoft/script:1",
                "files": [
                    "contoso-camera-installscript.sh"
                ],
                "handlerProperties": {
                    "scriptFileName": "contoso-camera-installscript.sh",
                    "arguments": "--post-install-sim-success --component-name --component-name-val --component-group --component-group-val --component-prop path --component-prop-val path",
                    "installedCriteria": "contoso-virtual-camera-1.2-stop-2"
                }
            }
        ]
    },
    "referencedBy": [
        {
            "provider": "DU-Client-Eng",
            "name": "MSOE-Update-Demo",
            "version": "3.1"
        }
    ],
    "manifestVersion": "4.0",
    "importedDateTime": "2021-11-17T07:26:14.7376536Z",
    "createdDateTime": "2021-11-17T07:22:09.2232968Z",
    "etag": "\"ad7a553d-24a8-492b-9885-9af424d44d58\""
}

Примечание.

В манифесте обновления каждый шаг должен иметь другую установленную строкуCriteria , если эта строка используется для определения того, следует ли выполнить шаг или нет.

Родительские и дочерние обновления

Когда манифесты обновления ссылаются друг на друга, манифест верхнего уровня называется родительским обновлением , а манифест, указанный на шаге ссылки, называется дочерним обновлением.

В настоящее время дочернее обновление не может содержать ссылочные шаги. Это ограничение проверяется во время импорта, и если импорт не выполнен, произойдет сбой.

Встроенные этапы в родительском обновлении

Встроенные шаги, указанные в родительском обновлении, применяются к хост-устройству. Здесь объект ADUC_WorkflowData передаётся обработчику шага (также известному как обработчик содержимого обновления) и не будет содержать данные Selected Components. Обработчик этого типа шага не должен быть обработчиком Component-Aware .

Обработчик содержимого шагов применяет логику проверки IsInstalled для каждого шага. Обработчик шага агента обновления устройств проверяет, установлено ли определенное обновление, проверяя, возвращает ли функция IsInstalled() код результата "900", что означает "true". Если обновление уже установлено, чтобы избежать переустановки обновления, которое уже находится на устройстве, агент DU пропустит дальнейшие шаги, так как мы используем его для определения того, следует ли выполнить шаг или нет.

Чтобы сообщить о результате обновления, результат выполнения обработчика шагов должен быть записан в структуру ADUC_Result в соответствующий файл результата, как указано в параметре --result-file. Затем, основанные на результатах выполнения, в случае успешного выполнения возвращается 0, а для любых фатальных ошибок возвращаются -1 или 0xFF.

Дополнительные сведения см. в разделе "Шаги обработчика содержимого" и "Реализация пользовательского обработчика содержимого с поддержкой компонентов".

Эталонные этапы в родительском обновлении

Этапы, указанные в родительском обновлении, применяются к компонентам, находящимся на хост-устройстве или подключенным к нему. Эталонный шаг — это шаг , содержащий идентификатор обновления другого обновления, который называется дочерним обновлением.

При обработке эталонного шага обработчик шагов скачивает отсоединяемый файл манифеста обновления, указанный в данных эталонного шага, а затем проверяет целостность файла. Затем обработчик шагов анализирует дочерний манифест обновления и создает объект ADUC_Workflow (также известный как дочерние данные рабочего процесса), объединив данные из дочернего манифеста обновления и URL-адреса файлов из родительского манифеста обновления. Эти дочерние данные рабочего процесса также имеют свойство level, которое имеет значение "1".

Примечание.

В настоящее время дочерние обновления не могут содержать ссылочные шаги.

Отдельные манифесты обновлений

Чтобы избежать сбоя развертывания из-за ограничений размера данных двойника Центра Интернета вещей, любой большой манифест обновления будет доставлен в виде файла данных JSON, который также называется отсоединяемым манифестом обновления.

Если обновление с большим содержимым импортируется в Центр обновления устройств для Интернета вещей, созданный манифест обновления будет содержать другой файл Detached Update Manifestполезных данных, который содержит полные данные манифеста обновления.

Свойство UpdateManifest в двойнике устройства или модуля будет содержать сведения о файле отсоединённого манифеста обновления.

При обработке события изменения свойства PnP агент обновления устройства автоматически скачивает отсоединяемый файл манифеста обновления и создает объект ADUC_WorkflowData, содержащий полные данные манифеста обновления.