Execução ordenada em várias etapas
A execução ordenada em várias etapas oferece a capacidade de executar tarefas de pré-instalação e pós-instalação ao implantar uma atualização sem fio. Essa capacidade faz parte do esquema do Manifesto de Atualização da Versão Prévia Pública v4.
Veja a documentação Atualizar Manifesto antes de revisar as alterações a seguir como parte da versão de atualização da versão prévia pública.
Com a execução ordenada em várias etapas, há dois tipos de etapas:
- Etapa em linha (padrão)
- Etapa de referência
Exemplo de manifesto de atualização com uma etapa em linha:
{
"updateId": {...},
"isDeployable": true,
"compatibility": [
{
"manufacturer": "du-device",
"model": "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"
}
Um exemplo de manifesto de atualização com duas etapas em linha:
{
"updateId": {...},
"isDeployable": true,
"compatibility": [
{
"manufacturer": "du-device",
"model": "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"
}
Um exemplo de manifesto de atualização com uma etapa de referência:
A atualização pai que faz referência a uma atualização filho
{ "updateId": {...}, "isDeployable": true, "compatibility": [ { "manufacturer": "du-device", "model": "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" }A atualização filho com etapas em linha
{ "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\"" }
Observação
No manifesto de atualização, cada etapa deve ter uma cadeia de caracteres installedCriteria diferente, se essa cadeia de caracteres estiver sendo usada para determinar se a etapa deve ser executada ou não.
Atualizações pai e filho
Quando os manifestos de atualização fazem referência uns aos outros, o manifesto de nível superior é chamado de atualização pai e um manifesto especificado em uma etapa de referência é chamado de atualização filho.
Atualmente, uma atualização filho não pode conter etapas de referência. Essa restrição é validada no momento da importação e, se não for seguida, a importação falhará.
Etapas em linha em uma atualização pai
As etapas em linha especificadas em uma atualização pai são aplicadas ao dispositivo host. Aqui, o objeto ADUC_WorkflowData é informado a um manipulador de etapas (também conhecido como manipulador de conteúdo de atualização) e não conterá os dados Selected Components. O manipulador para esse tipo de etapa não deve ser um manipulador Component-Aware.
O manipulador de conteúdo de etapas aplica a lógica de validação IsInstalled a cada etapa. O manipulador de etapas do agente de Atualização de Dispositivo verifica se uma atualização específica já está instalada, verificando se IsInstalled() resultou em um código de resultado "900" que significa "verdadeiro". Se uma atualização já estiver instalada, para evitar a reinstalação de uma atualização que já esteja no dispositivo, o agente de atualização de dispositivo vai ignorar as etapas futuras porque a usaremos para determinar se deseja executar a etapa ou não.
Para relatar um resultado de atualização, o resultado de uma execução de manipulador de etapa deve ser gravado na estrutura ADUC_Result, em um arquivo de resultado desejado, conforme especificado na opção --result-file. Em seguida, com base nos resultados da execução, para o retorno de êxito 0, para quaisquer erros fatais retornar -1 ou 0xFF.
Para obter mais detalhes, confira os artigos Manipulador de conteúdo de etapas e Implementando um manipulador de conteúdo que reconhece componentes personalizado.
Etapas de referência em uma atualização pai
As etapas de referência especificadas em uma atualização pai são aplicadas a componentes ou conectadas ao dispositivo host. Uma etapa de referência é a que contém o identificador de atualização de outra atualização, chamada de atualização filho.
Ao processar uma etapa de referência, o manipulador de etapas baixará um arquivo de manifesto de atualização desanexado especificado nos dados da etapa de referência e validará a integridade do arquivo. Em seguida, o manipulador de etapas analisará o manifesto de atualização filho e criará um ADUC_Workflow (também conhecido como dados de fluxo de trabalho filho) combinando os dados das informações de manifesto de atualização filho e URLs de arquivo do manifesto de atualização pai. Esses dados de fluxo de trabalho filho também têm uma propriedade “nível” definida como “1”.
Observação
Atualmente, as atualizações filho não podem conter etapas de referência.
Manifestos de atualização desanexados
Para evitar a falha de implantação devido aos limites de tamanho de dados gêmeos do Hub IoT, qualquer manifesto de atualização grande será entregue na forma de um arquivo de dados JSON, também chamado manifesto de atualização desanexado.
Se uma atualização com conteúdo grande for importada na Atualização de Dispositivo para Hub IoT, o manifesto de atualização gerado conterá outro arquivo de conteúdo chamado Detached Update Manifest, que conterá os dados completos do Manifesto de Atualização.
A propriedade UpdateManifest no dispositivo ou módulo gêmeo conterá as informações de arquivo de manifesto de atualização desanexado.
Ao processar o evento alterado da propriedade PnP, o Agente de Atualização de Dispositivos baixará automaticamente o arquivo de manifesto de atualização desanexado e criará um objeto ADUC_WorkflowData, que conterá os dados completos do manifesto de atualização.