Add extension class generation and categorization documentation

[Copilot]

Description

Created technical documentation explaining the ARM Management SDK extension class generation architecture and resource/operation categorization, covering the flow from TypeSpec definitions through to generated C# code.

Documentation Files

extension.md (743 lines)

• Two-layer extension pattern: public static extensions forward to mockable scope-based providers
• ExtensionProvider generates static facade, MockableResourceProvider implements logic per ARM scope
• GetCachedClient pattern ensures single provider instances per resource
• Component descriptions with GitHub repository links to generated examples in test project
• Six types of mockable providers: Comprehensive documentation of MockableArmClient, MockableTenantResource, MockableSubscriptionResource, MockableResourceGroupResource, and MockableManagementGroupResource with their scopes, generation conditions, and contents
• Detailed method placement rules: Precise rules for where methods are placed based on resource type (collections, singletons, non-resource methods, and resource-specific extension methods)
• Detailed list of forwarded methods: Factory methods, convenience Get methods, singleton factory methods, non-resource methods, and resource-specific extension methods
• TypeSpec to C# flow with ARM template patterns
• Code generation rules and examples
• Common patterns and best practices

categorization.md (340 lines)

• ResourceScope enum with 5 ARM hierarchy levels (Tenant, Subscription, ResourceGroup, ManagementGroup, Extension)
• Path-based scope determination and pattern analysis
• Resource vs non-resource method distinction
• Method categorization logic (MethodsInResource, MethodsInCollection, MethodsInExtension)
• Operation and method placement decision trees
• Categorization examples and troubleshooting

Examples

Includes real-world scenarios with TypeSpec → C# flow:

GetAllPrivateLinkResourcesAsync case study (as requested):

@armResourceOperations(PrivateLink)
interface PrivateLinks {
  @clientName("GetAllPrivateLinkResources")
  listByMongoCluster is ArmResourceListByParent<PrivateLink>;  // List only, no Get
}

Generates method in MockableAzureGeneratorMgmtTypeSpecTestsResourceGroupResource, but no PrivateLinkResource class due to missing Get operation.

Refinements Based on Feedback

• Removed verbose high-level flow diagram for cleaner architecture overview
• Replaced large inline code examples with GitHub repository URLs to generated files for better accessibility
• Separated categorization content into dedicated categorization.md file for better organization and focus
• Updated all file references to use GitHub repository URLs instead of relative paths
• Added comprehensive explanation of which methods are forwarded from mockable providers to extensions
• Removed frontmatter YAML title sections for cleaner GitHub markdown preview
• Added detailed documentation of all six mockable provider types with their inheritance, scope, and generation conditions
• Defined precise method placement rules for resource collections, singleton resources, non-resource methods, and resource-specific extension methods
• Streamlined ExtensionProvider responsibilities to focus on core technical functions
• Updated terminology for consistency: changed "Creates" to "Generates" throughout ExtensionProvider documentation

---

This checklist is used to make sure that common guidelines for a pull request are followed.

• Please add REST spec PR link to the SDK PR
• I have read the contribution guidelines.
• The pull request does not introduce breaking changes.

General Guidelines

• Title of the pull request is clear and informative.
• There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, see this page.

Testing Guidelines

• Pull request includes test coverage for the included changes.

SDK Generation Guidelines

• If an SDK is being regenerated based on a new swagger spec, a link to the pull request containing these swagger spec changes has been included above.
• The generate.cmd file for the SDK has been updated with the version of AutoRest, as well as the commitid of your swagger spec or link to the swagger spec, used to generate the code.
• The *.csproj and AssemblyInfo.cs files have been updated with the new version of the SDK.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Document for Extension class generation</issue_title>
<issue_description># Technical Documentation Request: ARM Management SDK Extension Class Generation

Objective

Write comprehensive technical documentation explaining how extension classes are generated in the Azure Management SDK code generator, covering the architecture from TypeSpec definitions through to generated C# code. The doc should be under https://github.com/Azure/azure-sdk-for-net/tree/main/eng/packages/http-client-csharp-mgmt/docs and name it extension.md.

Scope

Document the complete flow of extension method generation, including:

1. Architecture Overview

• The role of ExtensionProvider as the public facade generator
• How MockableResourceProvider classes implement the actual logic
• The relationship between extension methods and mockable providers
• The GetCachedClient pattern for provider instantiation

2. Resource Categorization

• How operations from TypeSpec are categorized by ResourceScope (ResourceGroup, Subscription, Tenant, ManagementGroup, Extension)
• The logic in ManagementOutputLibrary that categorizes operations
• Path pattern analysis that determines scope placement
• Distinction between resource methods vs non-resource methods

3. TypeSpec to C# Flow

• How TypeSpec ARM templates (ArmResourceListByParent<T>, ArmResourceRead<T>, etc.) generate operations
• The @armProviderSchema decorator and its role in defining resources
• How InputServiceMethod captures operation metadata including paths
• Path construction rules (scope prefix + provider namespace + resource type)

4. Code Generation Details

• When full ARM resource classes (Collection + Resource) are generated vs standalone methods
• Requirements for resource class generation (minimum: get operation for CRUD pattern)
• ProxyResource vs TrackedResource handling
• Non-resource method placement in mockable classes

5. Key Files & Classes

• ExtensionProvider.cs - Generates public static extension class
• MockableResourceProvider.cs - Generates scope-specific mockable providers
• ManagementOutputLibrary.cs - Orchestrates resource categorization
• ResourceScope.cs - Defines ARM hierarchy levels
• NonResourceMethod.cs - Represents non-resource operations
• ResourceMethod.cs - Represents resource-specific operations

Target Audience

SDK developers who need to understand or modify the code generation pipeline.

Deliverable Structure

Please organize the documentation with:

1. Introduction - High-level overview of the extension pattern
2. Architecture Diagram - Conceptual flow from TypeSpec → Generator → C# output
3. Component Details - Deep dive into each key class/file
4. Examples - Concrete examples showing:
   • TypeSpec definition → Generated extension method
   • Resource operation → Collection + Resource classes
   • Non-resource operation → Standalone method in mockable
5. Decision Tree - Flowchart showing how operations are categorized
6. Common Patterns - Best practices and common scenarios

Key Concepts to Cover

• Extension forwarding pattern: Static extension methods forward to cached mockable instances
• Scope-based organization: Operations grouped by ARM hierarchy level
• Resource vs non-resource: Different code generation paths based on operation kind
• CRUD requirements: What operations are needed to generate full resource classes
• Path analysis: How request paths determine scope and categorization

Example to Include

Use the GetAllPrivateLinkResourcesAsync method as a case study:

• TypeSpec: listByMongoCluster is ArmResourceListByParent<PrivateLink>
• Why it's in MockableAzureGeneratorMgmtTypeSpecTestsResourceGroupResource
• Why no PrivateLinkResource class is generated (missing CRUD operations)
• Path: /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/MgmtTypeSpec/privateLinkResources</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Document for Extension class generation #54667

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.