Skip to content

Commit

Permalink
(SCHEMA) Update _exist guidance for delete
Browse files Browse the repository at this point in the history
This change updates guidance for resources that implement the `delete`
method to always define the `_exist` property in the JSON schema for
the resource's properties, now that DSC can automatically determine
whether to delete an instance as implemented in PowerShell#382.

This change updates both the source and composed schemas.
  • Loading branch information
michaeltlombardi committed Apr 18, 2024
1 parent 63d236a commit ad44d9c
Show file tree
Hide file tree
Showing 3 changed files with 10 additions and 2 deletions.
2 changes: 1 addition & 1 deletion schemas/2024/04/bundled/resource/manifest.vscode.json
Original file line number Diff line number Diff line change
Expand Up @@ -638,7 +638,7 @@
"$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.delete.json",
"title": "Delete method",
"description": "Defines how DSC must call the DSC Resource to delete an instance. Define this method for resources as an alternative to handling the `_exist` property in a `set` operation, which can lead to highly complex code. If the `set` operation for the resource is able to handle deleting an instance when `_exist` is `false`, set the `handlesExist` property of the set method definition to `true` instead.",
"markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to delete an instance. Define this method for\nresources as an alternative to handling the [`_exist`][02] property in a `set` operation, which\ncan lead to highly complex code. If the `set` method for the resource is able to handle deleting\nan instance when `_exist` is `false`, set the [`handlesExist`][03] property of the set method\ndefinition to `true` instead.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/delete?view=dsc-3.0&preserve-view=true\n[02]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/exist?view=dsc-3.0&preserve-view=true\n[03]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#handlesExist\n",
"markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to delete an instance. Define this method for\nresources as an alternative to handling the [`_exist`][02] property in a `set` operation, which\ncan lead to highly complex code. If the `set` method for the resource is able to handle deleting\nan instance when `_exist` is `false`, set the [`handlesExist`][03] property of the set method\ndefinition to `true` instead.\n\nIf you define the delete method in a resource manifest, ensure that you also define the\n[`_exist`][02] property in the [JSON schema for the resource's properties][04].\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/delete?view=dsc-3.0&preserve-view=true\n[02]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/exist?view=dsc-3.0&preserve-view=true\n[03]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#handlesExist\n[04]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserve-view=true\n",
"type": "object",
"required": [
"executable",
Expand Down
4 changes: 4 additions & 0 deletions schemas/src/resource/manifest.delete.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,13 @@ markdownDescription: | # VS Code only
an instance when `_exist` is `false`, set the [`handlesExist`][03] property of the set method
definition to `true` instead.
If you define the delete method in a resource manifest, ensure that you also define the
[`_exist`][02] property in the [JSON schema for the resource's properties][04].
[01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/delete?<DOCS_VERSION_PIN>
[02]: <DOCS_BASE_URL>/reference/schemas/resource/properties/exist?<DOCS_VERSION_PIN>
[03]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/set?<DOCS_VERSION_PIN>#handlesExist
[04]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/schema/property?<DOCS_VERSION_PIN>
type: object
required:
Expand Down
6 changes: 5 additions & 1 deletion schemas/src/resource/properties/exist.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,13 @@ markdownDescription: |
[_Online Documentation_][01]
***
Indicates whether the DSC Resource instance should exist.
Indicates whether the DSC Resource instance should exist. For DSC Resources that define the
[delete method in their manifest][02], DSC calls the `delete` method for the resource when an
instance defines `_exist` as `false` and the instance exists.
[01]: <DOCS_BASE_URL>/reference/schemas/resource/properties/exist?<DOCS_VERSION_PIN>
[02]: <DOCS?BASE_URL>/reference/schemas/resource/manifest/delete?<DOCS_VERSION_PIN>
markdownEnumDescriptions:
- | # false
_Instance shouldn't exist._
Expand Down

0 comments on commit ad44d9c

Please sign in to comment.