Skip to content

docs(custom-handler): clarify IsInstalled call sites and authoring guidance (#750) - #896

Merged
Nox-MSFT merged 1 commit into
developfrom
user/nox-msft/issue-750-docs
Jun 23, 2026
Merged

docs(custom-handler): clarify IsInstalled call sites and authoring guidance (#750)#896
Nox-MSFT merged 1 commit into
developfrom
user/nox-msft/issue-750-docs

Conversation

@Nox-MSFT

Copy link
Copy Markdown
Contributor

Summary

Resolves #750. The IsInstalled row in docs/agent-reference/how-to-implement-custom-update-handler.md previously said only "In some situation, an Agent workflow can invoke 'IsInstalled'…" without explaining which situations, which is exactly what the issue reported.

Changes

docs/agent-reference/how-to-implement-custom-update-handler.md:

  1. Rewrote the IsInstalled table row to state the actual contract: it is a probe that may be called multiple times per deployment and must be cheap, side-effect-free, and idempotent; it compares the workflow's installedCriteria against handler-scoped state and must not consult system-wide state. Also fixed a malformed <br/ and clarified that a ResultCode of 0 is ADUC_Result_Failure (which the Steps Handler treats as NotInstalled).

  2. Added an "IsInstalled call sites and authoring guidance" section that:

    • enumerates the known call sites (agent core before a deployment and after a successful Apply; Steps Handler before each step's Download and before Install/Apply; and the aggregate call after the per-(component × step) loop);
    • lists authoring rules (be cheap / scoped / deterministic, use installedCriteria, don't return 0 to mean "installed", no reboots/restarts);
    • documents the conjunction semantics when used as a step in a multi-step manifest and cross-links steps-handler.md → IsInstalled.

Documentation-only change (+24 / −1); no code is affected.

Fixes #750

…idance (#750)

The how-to-implement-custom-update-handler.md table row for IsInstalled previously said 'In some situation' without listing them, leading to issue #750.

Rewrite the IsInstalled row to describe the contract (cheap, side-effect-free, idempotent; handler-scoped state; installedCriteria) and add an 'IsInstalled call sites and authoring guidance' section enumerating where the agent core and Steps Handler invoke it, the authoring rules, and the conjunction semantics for multi-step manifests.

Fixes #750
@Nox-MSFT
Nox-MSFT requested a review from chgennar June 23, 2026 21:39
@Nox-MSFT
Nox-MSFT merged commit a26f5a7 into develop Jun 23, 2026
12 checks passed
@Nox-MSFT
Nox-MSFT deleted the user/nox-msft/issue-750-docs branch June 23, 2026 23:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

IsInstalled not properly documented

2 participants