[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6BTCGD613BBYG8KS0N4N8PD":3,"skill-same:01M6BTCGD613BBYG8KS0N4N8PD":59},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":31,"linkOnly":32,"markdownContent":33,"markdownBody":34,"frontMatter":35,"refName":36,"commitSha":37,"skillDirectory":38,"forksCount":39,"repositoryHtmlUrl":40,"repositoryHomepageUrl":6,"ownerHtmlUrl":41,"ownerBlogUrl":42,"ownerDescription":43,"updatedAt":44,"install":45,"resources":58},"01M6BTCGD613BBYG8KS0N4N8PD","mitigate-breaking-changes",null,"Patterns and techniques for mitigating breaking changes in Azure management-plane SDKs. Covers SDK-side customizations (partial classes, CodeGenType, CodeGenSuppress) and TypeSpec decorator customizations (clientName, access, markAsPageable, alternateType, hierarchyBuilding).","Azure\u002Fazure-sdk-for-net","Azure","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6844498?v=4","01M6BT15ZBDTV4D9RM7HCC4D8A","Microsoft Azure","01M6BT163EEHB7Y52MKZJ322Q8",6073,"MIT","https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-net\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fmitigate-breaking-changes\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27,28,29,30],"mitigate breaking changes","changes","sdk","azure","typespec","access","management","patterns","plane","sdks","techniques","for","2026-11-10 10:12:30",false,"---\nname: mitigate-breaking-changes\ndescription: Patterns and techniques for mitigating breaking changes in Azure management-plane SDKs. Covers SDK-side customizations (partial classes, CodeGenType, CodeGenSuppress) and TypeSpec decorator customizations (clientName, access, markAsPageable, alternateType, hierarchyBuilding).\n---\n# Skill: mitigate-breaking-changes\n\nPatterns and techniques for mitigating breaking changes when regenerating Azure management-plane .NET SDKs. Use these to preserve backward compatibility in the generated SDK surface.\n\n## When Invoked\n\nTrigger phrases: \"mitigate breaking changes\", \"fix breaking change\", \"customization patterns\", \"how to keep backward compat\", \"CodeGenType\", \"CodeGenSuppress\", \"markAsPageable\", \"hierarchyBuilding\", \"base type change\".\n\n## Common breaking-change workflow\n\nWhen invoked from `azsdk-common-sdk-breaking-change`, use the\n[.NET pattern catalog](..\u002F..\u002F..\u002Fdoc\u002Fdev\u002FSDKBreakingChanges.md) and the original\n`azsdk_package_detect_breaking_change` result. Preserve the ApiCompat diagnostics,\nprevious signatures, additions, and `originBreaks`; a removal\u002Faddition pair is\nnot proof of a rename.\n\n- For a user-selected `mitigation: generator` change, verify the documented\n  preconditions and matching previous contract. Reuse the management generator's\n  existing conditional-header and model-factory compatibility overload support.\n  Regenerate; do not write a second synthesizer or patch generated files.\n- For `mitigation: client customization`, use `azsdk_customized_code_update`\n  with the user's selected change and permitted edit scope. `CustomCode` cannot\n  edit TypeSpec inputs or change the pinned spec commit; `SpecChangeRequired`\n  requires a spec-owner handoff, not an automatic retry with broader scope.\n- For `mitigation: manual`, missing evidence, or unsupported generator output,\n  explain the decision needed and stop automatic mitigation.\n\nThis skill's ARM patterns are management-specific. Do not apply resource\nhierarchy, ARM identifier, or conditional-header transformations to data-plane\nlibraries without separately verified support.\n\nAfter a change, regenerate and compile fresh artifacts as needed, rerun the\nstandalone detector, then run ordinary builds, analyzers, and tests separately.\nDo not treat a missing GA baseline, stale artifact, or detector failure as a\ncompatibility pass. Never add suppressions without explicit owner approval.\n\n## SDK-Side Customizations (in SDK repo)\n\nUse **Custom\u002F*.cs** or **Customization\u002F*.cs** partial classes (follow the package's existing structure) for .NET-side fixes.\n\n### Custom code file organization\nKeep custom code types split into separate files:\n- Put each custom type\u002Fpartial type in its own `.cs` file.\n- Name the file after the class it contains, for example `src\u002FCustom\u002FModels\u002FMyModel.cs` for `public partial class MyModel`.\n- Align the custom code folder structure with the generated code structure, such as using `Models\u002F` for model customizations and `Extensions\u002F` for extension customizations when those folders exist.\n- Do not group multiple compatibility types in a single broad file such as `Compatibility.cs`; split them so each file name aligns with the class name.\n\n### Partial class (add members, suppress generated members)\n```csharp\n\u002F\u002F src\u002FCustom\u002FModels\u002FMyModel.cs (or src\u002FCustomization\u002FModels\u002FMyModel.cs — follow the package's existing convention)\nnamespace Azure.ResourceManager.\u003CService>.Models\n{\n    public partial class MyModel\n    {\n        \u002F\u002F Add computed properties, rename via [CodeGenMember], etc.\n    }\n}\n```\n\n### `[CodeGenType]` — Override accessibility or rename a generated type\nWhen a generated type is `internal` and `@@access` in `client.tsp` doesn't work (common for nested\u002Fwrapper types), use `[CodeGenType]` in Custom code to make it public:\n\n```csharp\n\u002F\u002F src\u002FCustom\u002FModels\u002FMyPublicModel.cs\nusing Microsoft.TypeSpec.Generator.Customizations;\n\nnamespace Azure.ResourceManager.\u003CService>.Models\n{\n    [CodeGenType(\"OriginalTypeSpecModelName\")]\n    public partial class MyPublicModel\n    {\n    }\n}\n```\n\nThe `[CodeGenType(\"...\")]` attribute takes the **original TypeSpec model name** (not the C# renamed name). This links the Custom partial class to the generated internal type and overrides its accessibility to `public`.\n\n## TypeSpec Decorator Customizations (in spec repo)\n\nThese decorators are added to `client.tsp` in the spec repo.\n\n```typespec\n\u002F\u002F Rename parameter\n@@clientName(Operations.create::parameters.resource, \"content\");\n\n\u002F\u002F Rename path parameter\n@@Azure.ResourceManager.Legacy.renamePathParameter(Resources.list, \"fooName\", \"name\");\n\n\u002F\u002F Mark a non-pageable list operation as pageable (returns Pageable\u003CT> instead of Response\u003CListType>)\n\u002F\u002F Requires: using Azure.ClientGenerator.Core.Legacy;\n#suppress \"@azure-tools\u002Ftypespec-azure-core\u002Fno-legacy-usage\" \"migration\"\n@@markAsPageable(InterfaceName.operationName, \"csharp\");\n\n\u002F\u002F Suppress warning\n#suppress \"@azure-tools\u002Ftypespec-azure-core\u002Fno-legacy-usage\" \"migration\"\n```\n\n### When to use `@@markAsPageable`\nWhen the old SDK returned `Pageable\u003CT>` \u002F `AsyncPageable\u003CT>` for a list operation, but the TypeSpec spec defines the operation as non-pageable (returns a wrapper list type like `FooList`), use `@@markAsPageable` to make the generator produce pageable methods. This is **preferred over** writing custom `SinglePagePageable\u003CT>` wrapper code because:\n- It reduces custom code that must be maintained\n- The generated pageable implementation handles diagnostics, cancellation, and error handling correctly\n- It keeps the SDK surface consistent with other generated methods\n\n**Do NOT use `@@markAsPageable` if the operation is already marked with `@list`** — the `@list` decorator already makes the operation pageable, and adding `@@markAsPageable` will cause a compile error. Check the spec's operation definition before adding the decorator.\n\n**Requirements:**\n1. Add `using Azure.ClientGenerator.Core.Legacy;` to the `client.tsp` imports\n2. Add `#suppress \"@azure-tools\u002Ftypespec-azure-core\u002Fno-legacy-usage\" \"migration\"` before each `@@markAsPageable` call\n3. After adding the decorator, regenerate and remove any custom `[CodeGenSuppress]` + `SinglePagePageable` wrapper code\n\n### `@@alternateType` Decorator\nWhen the spec uses older common types that generate incorrect C# types (e.g., `string` instead of `ResourceIdentifier` for ID properties), use `@@alternateType`:\n```typespec\n@@alternateType(MyModel.resourceId, Azure.ResourceManager.CommonTypes.ArmResourceIdentifier, \"csharp\");\n```\n\n### `@@hierarchyBuilding` Decorator — Legacy base-type override\nDo **not** use `@@hierarchyBuilding` for C# base-model\u002Fbase-type compatibility. First verify resource-hierarchy parity, fix structural resource hierarchy issues in the TypeSpec resource shape, and use SDK-side custom code only for C# base-model\u002Fbase-type compatibility after the generated surface is stable.\n\n`@@hierarchyBuilding` is a legacy escape hatch. Use it only with explicit owner approval when no TypeSpec resource-shape fix or SDK-side customization is appropriate.\n\n**Syntax:**\n```typespec\n\u002F\u002F Requires: using Azure.ClientGenerator.Core.Legacy;\n#suppress \"@azure-tools\u002Ftypespec-azure-core\u002Fno-legacy-usage\" \"Change the base type back to \u003CTargetBase> for backward compatibility\"\n@@Azure.ClientGenerator.Core.Legacy.hierarchyBuilding(MyResource,\n  Azure.ResourceManager.Foundations.TrackedResource,\n  \"csharp\"\n);\n```\n\n**Common target base types:**\n- `Azure.ResourceManager.Foundations.TrackedResource` — generates `TrackedResourceData` (for resources with location and tags)\n- `Azure.ResourceManager.Foundations.ProxyResource` — generates `ResourceData` (for proxy\u002Fchild resources)\n- `Azure.ResourceManager.Foundations.Resource` — generates `ResourceData` (ARM resource base)\n\n**Legacy-only scenarios that require explicit approval:**\n- The old SDK had `MyData : ResourceData` or `MyData : TrackedResourceData`, the regenerated SDK produces `MyData : SomeOtherType` (e.g., a service-local `Resource` model), and the owner has explicitly rejected the normal resource-shape and SDK-customization fixes.\n- The `CannotRemoveBaseTypeOrInterface` API compatibility violation remains after verifying resource-hierarchy parity and attempting the normal SDK-side customization approach.\n\n**Requirements:**\n1. Add `using Azure.ClientGenerator.Core.Legacy;` to the `client.tsp` imports\n2. Add `#suppress \"@azure-tools\u002Ftypespec-azure-core\u002Fno-legacy-usage\" \"...\"` before each `@@hierarchyBuilding` call\n3. After adding the decorator, regenerate the SDK code\n\n**Legacy-approved example** (from Key Vault):\n```typespec\nimport \"@azure-tools\u002Ftypespec-client-generator-core\";\nusing Azure.ClientGenerator.Core.Legacy;\n\n\u002F\u002F Fix Vault resource to generate VaultData : TrackedResourceData\n#suppress \"@azure-tools\u002Ftypespec-azure-core\u002Fno-legacy-usage\" \"Change the base type back to TrackedResource for backward compatibility\"\n@@Azure.ClientGenerator.Core.Legacy.hierarchyBuilding(Vault,\n  Azure.ResourceManager.Foundations.TrackedResource,\n  \"csharp\"\n);\n```\n\n## WirePathAttribute Breaking Changes\n\nWhen the previous SDK version included `WirePathAttribute` on model properties (used by Azure.Provisioning libraries), regeneration may produce ApiCompat `CannotRemoveAttribute` errors for the missing attribute because the emitter defaults to **not** generating it.\n\n### How to detect\n\n- ApiCompat `CannotRemoveAttribute` errors referencing `WirePathAttribute` on model properties\n- These errors appear during `dotnet pack --no-restore` when the previous SDK release had `WirePathAttribute` on properties but the new generation does not\n\n### Fix\n\nAdd `enable-wire-path-attribute: true` to the **mgmt emitter options** in `tspconfig.yaml` (in the spec repo):\n\n```yaml\noptions:\n  \"@azure-typespec\u002Fhttp-client-csharp-mgmt\":\n    emitter-output-dir: \"{output-dir}\u002F{service-dir}\u002F{namespace}\"\n    namespace: \"Azure.ResourceManager.\u003CService>\"\n    enable-wire-path-attribute: true\n```\n\nThen regenerate the SDK.\n\nIf the remaining ApiCompat diff is only `WirePathAttribute` removal, it is acceptable to add targeted entries to the centralized baseline file under `eng\u002Fapicompatbaselines\u002F\u003CProject>.xml`. Do not add SDK custom code just to restore `WirePathAttribute`; the maintenance cost is not worth it for this compatibility diff.\n\nDo not create a local `ApiCompatBaseline.txt`, do not baseline unrelated ApiCompat errors, and do not disable ApiCompat.\n\n## Extension Resources\n\nExtension resources (deployed onto parent resources from different providers) require special handling.\n\n### Parameterized Scopes\nWhen the same resource type can be deployed onto multiple parent types (e.g., VM, HCRP, VMSS), use `OverrideResourceName` with parameterized scopes. Each scope generates a separate SDK resource type. The generator may produce duplicate `GetXxxResource()` methods in `MockableArmClient` when multiple entries exist for the same resource — this is a known generator bug requiring deduplication.\n\n### Sub-Resource Operations: Avoid `Read\u003C>` \u002F `Extension.Read\u003C>` for Non-Lifecycle Ops\nWhen a sub-resource operation (e.g., getting a report under an assignment) uses `Read\u003C>` or `Extension.Read\u003C>` templates, the ARM library treats it as a **lifecycle read** operation. This causes:\n- The resource's `resourceType` and `resourceIdPattern` to be set to the sub-resource path\n- Collections using the wrong REST client\n- Compile errors: CS1729 (wrong constructor), CS0029 (type mismatch), CS1503 (wrong argument)\n\n**Fix**: Change sub-resource Get operations from `Read\u003C>` to `ActionSync\u003C>` (or `Extension.ActionSync\u003C>` for extension resources) with a `@get` decorator:\n```typespec\n\u002F\u002F WRONG — ARM library treats this as lifecycle Read\nreportGet is Ops.Read\u003CResource, Response = ArmResponse\u003CReport>, ...>;\n\n\u002F\u002F CORRECT — ActionSync with @get avoids lifecycle misclassification\n@get reportGet is Ops.ActionSync\u003CResource, void, Response = ArmResponse\u003CReport>, ...>;\n```\n","# Skill: mitigate-breaking-changes\n\nPatterns and techniques for mitigating breaking changes when regenerating Azure management-plane .NET SDKs. Use these to preserve backward compatibility in the generated SDK surface.\n\n## When Invoked\n\nTrigger phrases: \"mitigate breaking changes\", \"fix breaking change\", \"customization patterns\", \"how to keep backward compat\", \"CodeGenType\", \"CodeGenSuppress\", \"markAsPageable\", \"hierarchyBuilding\", \"base type change\".\n\n## Common breaking-change workflow\n\nWhen invoked from `azsdk-common-sdk-breaking-change`, use the\n[.NET pattern catalog](..\u002F..\u002F..\u002Fdoc\u002Fdev\u002FSDKBreakingChanges.md) and the original\n`azsdk_package_detect_breaking_change` result. Preserve the ApiCompat diagnostics,\nprevious signatures, additions, and `originBreaks`; a removal\u002Faddition pair is\nnot proof of a rename.\n\n- For a user-selected `mitigation: generator` change, verify the documented\n  preconditions and matching previous contract. Reuse the management generator's\n  existing conditional-header and model-factory compatibility overload support.\n  Regenerate; do not write a second synthesizer or patch generated files.\n- For `mitigation: client customization`, use `azsdk_customized_code_update`\n  with the user's selected change and permitted edit scope. `CustomCode` cannot\n  edit TypeSpec inputs or change the pinned spec commit; `SpecChangeRequired`\n  requires a spec-owner handoff, not an automatic retry with broader scope.\n- For `mitigation: manual`, missing evidence, or unsupported generator output,\n  explain the decision needed and stop automatic mitigation.\n\nThis skill's ARM patterns are management-specific. Do not apply resource\nhierarchy, ARM identifier, or conditional-header transformations to data-plane\nlibraries without separately verified support.\n\nAfter a change, regenerate and compile fresh artifacts as needed, rerun the\nstandalone detector, then run ordinary builds, analyzers, and tests separately.\nDo not treat a missing GA baseline, stale artifact, or detector failure as a\ncompatibility pass. Never add suppressions without explicit owner approval.\n\n## SDK-Side Customizations (in SDK repo)\n\nUse **Custom\u002F*.cs** or **Customization\u002F*.cs** partial classes (follow the package's existing structure) for .NET-side fixes.\n\n### Custom code file organization\nKeep custom code types split into separate files:\n- Put each custom type\u002Fpartial type in its own `.cs` file.\n- Name the file after the class it contains, for example `src\u002FCustom\u002FModels\u002FMyModel.cs` for `public partial class MyModel`.\n- Align the custom code folder structure with the generated code structure, such as using `Models\u002F` for model customizations and `Extensions\u002F` for extension customizations when those folders exist.\n- Do not group multiple compatibility types in a single broad file such as `Compatibility.cs`; split them so each file name aligns with the class name.\n\n### Partial class (add members, suppress generated members)\n```csharp\n\u002F\u002F src\u002FCustom\u002FModels\u002FMyModel.cs (or src\u002FCustomization\u002FModels\u002FMyModel.cs — follow the package's existing convention)\nnamespace Azure.ResourceManager.\u003CService>.Models\n{\n    public partial class MyModel\n    {\n        \u002F\u002F Add computed properties, rename via [CodeGenMember], etc.\n    }\n}\n```\n\n### `[CodeGenType]` — Override accessibility or rename a generated type\nWhen a generated type is `internal` and `@@access` in `client.tsp` doesn't work (common for nested\u002Fwrapper types), use `[CodeGenType]` in Custom code to make it public:\n\n```csharp\n\u002F\u002F src\u002FCustom\u002FModels\u002FMyPublicModel.cs\nusing Microsoft.TypeSpec.Generator.Customizations;\n\nnamespace Azure.ResourceManager.\u003CService>.Models\n{\n    [CodeGenType(\"OriginalTypeSpecModelName\")]\n    public partial class MyPublicModel\n    {\n    }\n}\n```\n\nThe `[CodeGenType(\"...\")]` attribute takes the **original TypeSpec model name** (not the C# renamed name). This links the Custom partial class to the generated internal type and overrides its accessibility to `public`.\n\n## TypeSpec Decorator Customizations (in spec repo)\n\nThese decorators are added to `client.tsp` in the spec repo.\n\n```typespec\n\u002F\u002F Rename parameter\n@@clientName(Operations.create::parameters.resource, \"content\");\n\n\u002F\u002F Rename path parameter\n@@Azure.ResourceManager.Legacy.renamePathParameter(Resources.list, \"fooName\", \"name\");\n\n\u002F\u002F Mark a non-pageable list operation as pageable (returns Pageable\u003CT> instead of Response\u003CListType>)\n\u002F\u002F Requires: using Azure.ClientGenerator.Core.Legacy;\n#suppress \"@azure-tools\u002Ftypespec-azure-core\u002Fno-legacy-usage\" \"migration\"\n@@markAsPageable(InterfaceName.operationName, \"csharp\");\n\n\u002F\u002F Suppress warning\n#suppress \"@azure-tools\u002Ftypespec-azure-core\u002Fno-legacy-usage\" \"migration\"\n```\n\n### When to use `@@markAsPageable`\nWhen the old SDK returned `Pageable\u003CT>` \u002F `AsyncPageable\u003CT>` for a list operation, but the TypeSpec spec defines the operation as non-pageable (returns a wrapper list type like `FooList`), use `@@markAsPageable` to make the generator produce pageable methods. This is **preferred over** writing custom `SinglePagePageable\u003CT>` wrapper code because:\n- It reduces custom code that must be maintained\n- The generated pageable implementation handles diagnostics, cancellation, and error handling correctly\n- It keeps the SDK surface consistent with other generated methods\n\n**Do NOT use `@@markAsPageable` if the operation is already marked with `@list`** — the `@list` decorator already makes the operation pageable, and adding `@@markAsPageable` will cause a compile error. Check the spec's operation definition before adding the decorator.\n\n**Requirements:**\n1. Add `using Azure.ClientGenerator.Core.Legacy;` to the `client.tsp` imports\n2. Add `#suppress \"@azure-tools\u002Ftypespec-azure-core\u002Fno-legacy-usage\" \"migration\"` before each `@@markAsPageable` call\n3. After adding the decorator, regenerate and remove any custom `[CodeGenSuppress]` + `SinglePagePageable` wrapper code\n\n### `@@alternateType` Decorator\nWhen the spec uses older common types that generate incorrect C# types (e.g., `string` instead of `ResourceIdentifier` for ID properties), use `@@alternateType`:\n```typespec\n@@alternateType(MyModel.resourceId, Azure.ResourceManager.CommonTypes.ArmResourceIdentifier, \"csharp\");\n```\n\n### `@@hierarchyBuilding` Decorator — Legacy base-type override\nDo **not** use `@@hierarchyBuilding` for C# base-model\u002Fbase-type compatibility. First verify resource-hierarchy parity, fix structural resource hierarchy issues in the TypeSpec resource shape, and use SDK-side custom code only for C# base-model\u002Fbase-type compatibility after the generated surface is stable.\n\n`@@hierarchyBuilding` is a legacy escape hatch. Use it only with explicit owner approval when no TypeSpec resource-shape fix or SDK-side customization is appropriate.\n\n**Syntax:**\n```typespec\n\u002F\u002F Requires: using Azure.ClientGenerator.Core.Legacy;\n#suppress \"@azure-tools\u002Ftypespec-azure-core\u002Fno-legacy-usage\" \"Change the base type back to \u003CTargetBase> for backward compatibility\"\n@@Azure.ClientGenerator.Core.Legacy.hierarchyBuilding(MyResource,\n  Azure.ResourceManager.Foundations.TrackedResource,\n  \"csharp\"\n);\n```\n\n**Common target base types:**\n- `Azure.ResourceManager.Foundations.TrackedResource` — generates `TrackedResourceData` (for resources with location and tags)\n- `Azure.ResourceManager.Foundations.ProxyResource` — generates `ResourceData` (for proxy\u002Fchild resources)\n- `Azure.ResourceManager.Foundations.Resource` — generates `ResourceData` (ARM resource base)\n\n**Legacy-only scenarios that require explicit approval:**\n- The old SDK had `MyData : ResourceData` or `MyData : TrackedResourceData`, the regenerated SDK produces `MyData : SomeOtherType` (e.g., a service-local `Resource` model), and the owner has explicitly rejected the normal resource-shape and SDK-customization fixes.\n- The `CannotRemoveBaseTypeOrInterface` API compatibility violation remains after verifying resource-hierarchy parity and attempting the normal SDK-side customization approach.\n\n**Requirements:**\n1. Add `using Azure.ClientGenerator.Core.Legacy;` to the `client.tsp` imports\n2. Add `#suppress \"@azure-tools\u002Ftypespec-azure-core\u002Fno-legacy-usage\" \"...\"` before each `@@hierarchyBuilding` call\n3. After adding the decorator, regenerate the SDK code\n\n**Legacy-approved example** (from Key Vault):\n```typespec\nimport \"@azure-tools\u002Ftypespec-client-generator-core\";\nusing Azure.ClientGenerator.Core.Legacy;\n\n\u002F\u002F Fix Vault resource to generate VaultData : TrackedResourceData\n#suppress \"@azure-tools\u002Ftypespec-azure-core\u002Fno-legacy-usage\" \"Change the base type back to TrackedResource for backward compatibility\"\n@@Azure.ClientGenerator.Core.Legacy.hierarchyBuilding(Vault,\n  Azure.ResourceManager.Foundations.TrackedResource,\n  \"csharp\"\n);\n```\n\n## WirePathAttribute Breaking Changes\n\nWhen the previous SDK version included `WirePathAttribute` on model properties (used by Azure.Provisioning libraries), regeneration may produce ApiCompat `CannotRemoveAttribute` errors for the missing attribute because the emitter defaults to **not** generating it.\n\n### How to detect\n\n- ApiCompat `CannotRemoveAttribute` errors referencing `WirePathAttribute` on model properties\n- These errors appear during `dotnet pack --no-restore` when the previous SDK release had `WirePathAttribute` on properties but the new generation does not\n\n### Fix\n\nAdd `enable-wire-path-attribute: true` to the **mgmt emitter options** in `tspconfig.yaml` (in the spec repo):\n\n```yaml\noptions:\n  \"@azure-typespec\u002Fhttp-client-csharp-mgmt\":\n    emitter-output-dir: \"{output-dir}\u002F{service-dir}\u002F{namespace}\"\n    namespace: \"Azure.ResourceManager.\u003CService>\"\n    enable-wire-path-attribute: true\n```\n\nThen regenerate the SDK.\n\nIf the remaining ApiCompat diff is only `WirePathAttribute` removal, it is acceptable to add targeted entries to the centralized baseline file under `eng\u002Fapicompatbaselines\u002F\u003CProject>.xml`. Do not add SDK custom code just to restore `WirePathAttribute`; the maintenance cost is not worth it for this compatibility diff.\n\nDo not create a local `ApiCompatBaseline.txt`, do not baseline unrelated ApiCompat errors, and do not disable ApiCompat.\n\n## Extension Resources\n\nExtension resources (deployed onto parent resources from different providers) require special handling.\n\n### Parameterized Scopes\nWhen the same resource type can be deployed onto multiple parent types (e.g., VM, HCRP, VMSS), use `OverrideResourceName` with parameterized scopes. Each scope generates a separate SDK resource type. The generator may produce duplicate `GetXxxResource()` methods in `MockableArmClient` when multiple entries exist for the same resource — this is a known generator bug requiring deduplication.\n\n### Sub-Resource Operations: Avoid `Read\u003C>` \u002F `Extension.Read\u003C>` for Non-Lifecycle Ops\nWhen a sub-resource operation (e.g., getting a report under an assignment) uses `Read\u003C>` or `Extension.Read\u003C>` templates, the ARM library treats it as a **lifecycle read** operation. This causes:\n- The resource's `resourceType` and `resourceIdPattern` to be set to the sub-resource path\n- Collections using the wrong REST client\n- Compile errors: CS1729 (wrong constructor), CS0029 (type mismatch), CS1503 (wrong argument)\n\n**Fix**: Change sub-resource Get operations from `Read\u003C>` to `ActionSync\u003C>` (or `Extension.ActionSync\u003C>` for extension resources) with a `@get` decorator:\n```typespec\n\u002F\u002F WRONG — ARM library treats this as lifecycle Read\nreportGet is Ops.Read\u003CResource, Response = ArmResponse\u003CReport>, ...>;\n\n\u002F\u002F CORRECT — ActionSync with @get avoids lifecycle misclassification\n@get reportGet is Ops.ActionSync\u003CResource, void, Response = ArmResponse\u003CReport>, ...>;\n```\n",{"name":5,"description":7},"main","dbc5eb654c3492137a4fbeeb6776c804f0042063",".github\u002Fskills\u002Fmitigate-breaking-changes",5227,"https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-net","https:\u002F\u002Fgithub.com\u002FAzure","https:\u002F\u002Fdocs.microsoft.com\u002Fen-us\u002Fazure\u002F","APIs, SDKs and open source projects from Microsoft Azure","2026-11-14 03:04:16",{"source":8,"skillName":5,"commands":46,"prompt":56,"zipAvailable":57},[47,50,53],{"tool":48,"command":49},"npx","npx skills add Azure\u002Fazure-sdk-for-net --skill mitigate-breaking-changes",{"tool":51,"command":52},"bunx","bunx skills add Azure\u002Fazure-sdk-for-net --skill mitigate-breaking-changes",{"tool":54,"command":55},"pnpm","pnpm dlx skills add Azure\u002Fazure-sdk-for-net --skill mitigate-breaking-changes","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-net\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fmitigate-breaking-changes\u002FSKILL.md",true,[],[60,88,123,145,168,184],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":76,"publishedAt":31},"01M6BTE1QTJPYDAN115GS2EHDQ","update-chat-api","Use when: updating, exporting, refreshing, or validating the public API baseline for Azure.Messaging.WebPubSub.Chat after a public API change.","https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-net\u002Fblob\u002Fmain\u002Fsdk\u002Fwebpubsub\u002F.github\u002Fskills\u002Fupdate-chat-api\u002FSKILL.md",[66,71],{"categoryNo":67,"categoryName":68,"taxonomyType":69,"taxonomyTypeDesc":70},"01JBSEEDCAT000000000000010","后端与接口","SCENARIO","使用场景",{"categoryNo":72,"categoryName":73,"taxonomyType":74,"taxonomyTypeDesc":75},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[77,78,79,80,81,22,82,83,84,85,86,30,87],"update","api","update chat api","chat","change","messaging","baseline","public","use","public api","when",{"skillNo":89,"name":90,"nameZh":6,"description":91,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":92,"categories":93,"keywords":101,"publishedAt":31},"01M6BTDYJS2RSGZR2T2BTJJ6YC","search-documents","E2E workflow skill for Azure.Search.Documents SDK (TypeSpec + heavy customization). Handles full release cycles and partial updates: SHA update; code generation; build; customization fixes; ServiceVersion sync; testing; API export; changelog; version; samples; formatting; release metadata. WHEN: create new package version for Azure.Search.Documents; regenerate Azure.Search.Documents; fix Azure.Search.Documents bug; release Azure.Search.Documents; update Azure.Search.Documents spec. Do not use for Azure.ResourceManager.Search or Azure.Provisioning.Search.","https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-net\u002Fblob\u002Fmain\u002Fsdk\u002Fsearch\u002FAzure.Search.Documents\u002F.github\u002Fskills\u002Fsearch-documents\u002FSKILL.md",[94,97,100],{"categoryNo":95,"categoryName":96,"taxonomyType":69,"taxonomyTypeDesc":70},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":98,"categoryName":99,"taxonomyType":69,"taxonomyTypeDesc":70},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":72,"categoryName":73,"taxonomyType":74,"taxonomyTypeDesc":75},[102,103,104,105,106,21,107,108,22,23,109,77,110,111,112,113,114,115,116,78,117,118,119,120,121,87,122],"documents","search","search documents","testing","spec","workflow","sync","create","code","release","changelog","package","Code Generation","e2e","provisioning","fix","bug","workflow skill","updates","new package","new",{"skillNo":124,"name":125,"nameZh":6,"description":126,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":127,"categories":128,"keywords":129,"publishedAt":31},"01M6BTDVJGZ0N7F7DXR5Z7E0QH","search-documents-version-diff","Diff the current Azure.Search.Documents public API surface against a previous published version and detect preview-to-preview regressions where the SDK customization layer was not bubbled up after a TypeSpec change. Use whenever the user asks to compare Azure.Search.Documents betas, verify no Azure.Search.Documents preview features dropped, regression audit between Azure.Search.Documents versions, sanity-check a release branch for Azure.Search.Documents, or investigate a missing Azure.Search.Documents preview feature — even if they don't say the word \"diff\". Specifically catches dropped wrappers (QueryAnswer\u002FQueryCaption\u002FQueryRewrites style), lost SearchOptions aggregator redirectors, `@@access(\"internal\")` flips, deleted-instead-of-gated `#if AZURE_SEARCH_PREVIEW` blocks, dropped `ServiceVersion` enum values, and convenience-to-protocol downgrades.","https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-net\u002Fblob\u002Fmain\u002Fsdk\u002Fsearch\u002FAzure.Search.Documents\u002F.github\u002Fskills\u002Fsearch-documents-version-diff\u002FSKILL.md",[],[102,103,130,104,131,132,21,81,22,23,111,133,134,78,135,136,24,137,138,139,140,141,86,142,143,144],"search documents version diff","version","diff","protocol","audit","verify","investigate","regression","branch","up","preview","aggregator","sanity","layer","features",{"skillNo":146,"name":147,"nameZh":6,"description":148,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":149,"categories":150,"keywords":152,"publishedAt":31},"01M6BTDRCG0SXKPKCFWR75FY8T","search-documents-typespec-validation","TypeSpec validation skill for Azure.Search.Documents SDK. Performs a COMPLETE validation of ALL operations, ALL models, ALL enums, and ALL properties against the TypeSpec definition at any pinned commit. Works for any API version. Generates a full gap report: missing features, extra features, naming mismatches, and recommended fix location. WHEN: \"validate Azure.Search.Documents SDK against TypeSpec\", \"detect Azure.Search.Documents typespec feature gaps\", \"what is missing from the Azure.Search.Documents SDK\", \"compare Azure.Search.Documents SDK to spec\", \"full spec coverage audit for Azure.Search.Documents\". Do NOT use for version-to-version diff or regression detection — use search-documents-version-diff instead.","https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-net\u002Fblob\u002Fmain\u002Fsdk\u002Fsearch\u002FAzure.Search.Documents\u002F.github\u002Fskills\u002Fsearch-documents-typespec-validation\u002FSKILL.md",[151],{"categoryNo":98,"categoryName":99,"taxonomyType":69,"taxonomyTypeDesc":70},[102,23,153,103,154,104,106,21,155,156,157,158,22,159,134,160,78,137,161,162,117,163,164,165,144,166,167,87],"validation","search documents typespec validation","to spec","commit","validate","gap report","report","detection","extra","coverage","do","full","at","api version","definition",{"skillNo":169,"name":170,"nameZh":6,"description":171,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":172,"categories":173,"keywords":174,"publishedAt":31},"01M6BTDP9JS9KNT1H9ED8AGZF5","test-skill_file","Roll dice using a random number generator.","https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-net\u002Fblob\u002Fmain\u002Fsdk\u002Fai\u002FAzure.AI.Projects.Agents\u002Ftests\u002FTestData\u002Froll-dice\u002FSKILL.md",[],[175,176,177,178,179,180,181,182,183],"test","Test Skill","file","test skill file","roll dice","dice","random","generator","number",{"skillNo":185,"name":186,"nameZh":6,"description":187,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":188,"categories":189,"keywords":190,"publishedAt":31},"01M6BTDMF2VK2CM53SSHZNWX7T","roll-dice","Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.), roll dice, or generate a random dice roll.","https:\u002F\u002Fgithub.com\u002FAzure\u002Fazure-sdk-for-net\u002Fblob\u002Fmain\u002Fsdk\u002Fai\u002FAzure.AI.Projects.Agents\u002Ftests\u002FSamples\u002Froll-dice\u002FSKILL.md",[],[179,180,191,85,181,182,183,87],"generate"]