Esecuzione ordinata in più passaggi
L'esecuzione ordinata in più passaggi consente di eseguire attività di pre-installazione e post-installazione durante la distribuzione di un aggiornamento over-the-air. Questa funzionalità fa parte dello schema Manifesto aggiornamento anteprima pubblica v4.
Vedere la documentazione del manifesto di aggiornamento prima di esaminare le modifiche seguenti come parte della versione di aggiornamento dell'anteprima pubblica.
Con l'esecuzione ordinata in più passaggi sono disponibili due tipi di passaggi:
- Passaggio inline (impostazione predefinita)
- Passaggio di riferimento
Un manifesto di aggiornamento di esempio con un passaggio inline:
{
"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"
}
Manifesto di aggiornamento di esempio con due passaggi inline:
{
"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"
}
Manifesto di aggiornamento di esempio con un passaggio di riferimento:
Aggiornamento padre che fa riferimento a un aggiornamento figlio
{ "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" }Aggiornamento figlio con passaggi inline
{ "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\"" }
Nota
Nel manifesto dell'aggiornamento ogni passaggio deve avere una stringa installata diversaCriteria se tale stringa viene usata per determinare se il passaggio deve essere eseguito o meno.
Aggiornamenti padre e aggiornamenti figlio
Quando i manifesti di aggiornamento fanno riferimento tra loro, il manifesto di primo livello viene chiamato aggiornamento padre e un manifesto specificato in un passaggio di riferimento viene chiamato aggiornamento figlio.
Attualmente un aggiornamento figlio non può contenere passaggi di riferimento. Questa restrizione viene convalidata in fase di importazione e, se non seguita, l'importazione avrà esito negativo.
Passaggi inline in un aggiornamento padre
I passaggi inline specificati in un aggiornamento padre vengono applicati al dispositivo host. In questo caso l'oggetto ADUC_WorkflowData passato a un gestore di passaggi (noto anche come gestore del contenuto di aggiornamento) e non conterrà i Selected Components dati. Il gestore per questo tipo di passaggio non deve essere un Component-Aware gestore.
Il gestore contenuto dei passaggi applica la logica di convalida IsInstalled per ogni passaggio. Il gestore dei passaggi dell'agente di aggiornamento del dispositivo verifica se è già installato un particolare aggiornamento controllando se IsInstalled() ha generato un codice di risultato "900" che significa "true". Se un aggiornamento è già installato, per evitare di reinstallare un aggiornamento già presente nel dispositivo, l'agente DU ignora i passaggi futuri perché viene usato per determinare se eseguire il passaggio o meno.
Per segnalare un risultato dell'aggiornamento, il risultato di un'esecuzione del gestore dei passaggi deve essere scritto in ADUC_Result struct in un file di risultato desiderato come specificato nell'opzione --result-file. In base ai risultati dell'esecuzione, per esito positivo restituisce 0, per eventuali errori irreversibili restituisce -1 o 0xFF.
Per altre informazioni, vedere Passaggi del gestore del contenuto e Implementazione di un gestore di contenuto con riconoscimento dei componenti personalizzato.
Passaggi di riferimento in un aggiornamento padre
I passaggi di riferimento specificati in un aggiornamento padre vengono applicati ai componenti in o connessi al dispositivo host. Un passaggio di riferimento è un passaggio che contiene l'identificatore di aggiornamento di un altro aggiornamento, denominato aggiornamento figlio.
Quando si elabora un passaggio di riferimento, il gestore passaggi scarica un file manifesto di aggiornamento scollegato specificato nei dati del passaggio di riferimento, quindi convalida l'integrità del file. Successivamente, il gestore passaggi analizza il manifesto dell'aggiornamento figlio e crea un oggetto ADUC_Workflow (noto anche come dati del flusso di lavoro figlio) combinando i dati dal manifesto dell'aggiornamento figlio e dalle informazioni sugli URL di file dal manifesto dell'aggiornamento padre. Questi dati del flusso di lavoro figlio hanno anche una proprietà "level" impostata su '1'.
Nota
Attualmente gli aggiornamenti figlio non possono contenere passaggi di riferimento.
Manifesti di aggiornamento scollegati
Per evitare errori di distribuzione a causa di limiti di dimensioni dei dati gemelli hub IoT, qualsiasi manifesto di aggiornamento di grandi dimensioni verrà recapitato sotto forma di un file di dati JSON, denominato anche manifesto di aggiornamento scollegato.
Se un aggiornamento con contenuto di grandi dimensioni viene importato in Aggiornamento dispositivi per hub IoT, il manifesto dell'aggiornamento generato conterrà un altro file payload denominato Detached Update Manifest, che contiene i dati completi del manifesto di aggiornamento.
La UpdateManifest proprietà nel dispositivo o nel modulo gemello conterrà le informazioni sul file manifesto di aggiornamento scollegato.
Durante l'elaborazione dell'evento modificato della proprietà PnP, l'agente di aggiornamento del dispositivo scarica automaticamente il file manifesto di aggiornamento scollegato e crea un oggetto ADUC_WorkflowData contenente i dati del manifesto di aggiornamento completi.