Add usage documentation for undocumented ARM operation templates#3961
Add usage documentation for undocumented ARM operation templates#3961
Conversation
Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>
| | Async TagsOnly PATCH | `update is ArmTagsPatchAsync<ResourceType>` | | ||
| | Sync Lifecycle PATCH | `update is ArmResourcePatchSync<ResourceType, ResourcePropertiesType>` | | ||
| | Async Lifecycle PATCH | `update is ArmResourcePatchAsync<ResourceType, ResourcePropertiesType>` | | ||
| | Sync Custom Properties PATCH | `update is ArmCustomPatchSync<ResourceType, Azure.ResourceManager.Foundations.ResourceUpdateModel<ResourceType, ResourcePropertiesType>>` | |
There was a problem hiding this comment.
@copilot the two ArmCustomPatch templates are the recommended templates for PATCH operations
There was a problem hiding this comment.
Reordered the table to list ArmCustomPatch* before the lifecycle templates and marked them as "(recommended)" in the operation description. Also updated the explanatory text below the table to lead with ArmCustomPatch* as the recommended choice. See 2dc82a2.
| | Sync Custom Properties PATCH | `update is ArmCustomPatchSync<ResourceType, Azure.ResourceManager.Foundations.ResourceUpdateModel<ResourceType, ResourcePropertiesType>>` | | ||
| | Async Custom Properties PATCH | `update is ArmCustomPatchAsync<ResourceType, Azure.ResourceManager.Foundations.ResourceUpdateModel<ResourceType, ResourcePropertiesType>>` | | ||
|
|
||
| The `ArmResourcePatch*` templates use the resource's Lifecycle.Update visibility to automatically |
There was a problem hiding this comment.
You should make it clear that the ArmResourcePatch templates are not recommended because the visibility analysis you mention is preformed only by the typespec-autorest emitter and so will not be replaicated in SDKs generated for the PATCH operation. Instead, spec authors should define a specific PATCH template and use the ArmCustomPatch* template
There was a problem hiding this comment.
Added a blockquote note explaining that ArmResourcePatch* templates are not recommended because the Lifecycle.Update visibility analysis is only performed by the typespec-autorest emitter and won't be replicated in SDKs. The note directs spec authors to define a specific PATCH model and use ArmCustomPatch* instead. See 2dc82a2.
| Parameters to the template are the ResourceType, the model for the operation Request body, and the | ||
| model for the operation Response body. | ||
|
|
||
| For long-running actions where the response is only available after polling the LRO (rather than |
There was a problem hiding this comment.
Remove any documentation about this template for now
There was a problem hiding this comment.
Removed the ActionAsync documentation. See 2dc82a2.
…inst ArmResourcePatch, remove ActionAsync docs Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>
Several operation templates in the
Azure.ResourceManagernamespace had no usage examples in the how-to documentation. This adds coverage for each inresource-operations.md.New sections
ArmResourceCheckExistence— HEAD operation for checking resource existence without fetching the bodyArmProviderActionSync/ArmProviderActionAsync— Provider-level actions with configurable scope (TenantActionScope,SubscriptionActionScope, etc.)Additions to existing sections
ArmResourcePatchSync/ArmResourcePatchAsync— Added as explicit "Lifecycle PATCH" table rows with a note that they are not recommended, since their Lifecycle.Update visibility analysis is only performed by the typespec-autorest emitter and will not be replicated in generated SDKsArmCustomPatchSync/ArmCustomPatchAsync— Marked as the recommended PATCH templates in the table and explanatory textArmResourceListAtScope— Added to the List Operations table for custom-scope listingNot documented (intentionally)
ArmResourceDeleteAsyncBase,ArmResourceActionAsyncBase— internal@devbase templatesArmResourceCreateOrUpdateSync,ArmResourceDeleteAsync,ArmResourceActionNoContentAsync— deprecatedActionAsync— omitted per reviewer guidance💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.