Default autorest --csharp generator change

---

:warning: We have updated the default generator used by autorest --csharp to the new version V3, which uses @autorest/csharp package and it will have few side effects:

• It will generate code based on the .NET SDK guidelines, which will be totally different than the code generated by V2 version.
• The dotnet 8.0 or above is required.
• If you still want to generate code based on V2 version, you can add --legacy flag to the command line to get the previous behavior.

---

C# code generator for AutoRest V3

• C# code generator for AutoRest V3
  • Prerequisites
  • Build
  • Test
    • Testing Details
  • PR Merge Process
    • Preview changes in azure-sdk-for-net
    • Make sure changes in azure-sdk-for-net is expected before merging your autorest.csharp PR
    • Merge azure-sdk-for-net PR
  • Use in azure-sdk-for-net repo
    • PR Integration with Azure SDK Repository
  • Use outside of the azure-sdk-for-net repo
  • Debugging
  • Debugging transforms
  • Customizing the generated code
    • Make a model internal
    • Rename a model class
    • Change a model or client namespace
    • Make model property internal
    • Rename a model property
    • Change a model property type
    • Preserve raw Json value of a property
    • Changing member doc comment
    • Customize serialization/deserialization methods
      • Change the serialized name of a property
      • Change the hierarchy of a property in the serialized JSON
      • Change the implementation of serialization/deserialization method of one particular property
      • Add a new property to the model with serialization/deserialization
      • Replace the entire serialization/deserialization method
    • Renaming an enum
    • Renaming an enum member
    • Changing an enum to an extensible enum
    • Make a client internal
    • Rename a client
    • Replace any generated member
    • Remove any generated member
    • Change model namespace or accessibility in bulk
    • Change operation accessibility in bulk
    • Exclude models from namespace
    • Extending a model with additional constructors
    • Change the file license header
  • Management plane concepts and configurations

<!-- /TOC -->

Prerequisites

• NodeJS (18.x.x)
• .NET Core SDK (8.0.303 or above)
• PowerShell Core 7
• npm install (at root)

Build

• dotnet build (at root)

Test

./eng/Generate.ps1 (at root in PowerShell Core)

This command tests your change across many swagger definitions and samples.

These arguments change the behavior:

• -fast option skips Swagger -> YAML IL step. Much faster when only making codegen changes
• -fast SWAGGER_NAME (where SWAGGER_NAME is replaced with the name of the swagger) to run only one case

You could run this command on local dev machine or ask github workflow run it against your branch. The steps to run workflow is:

1. Go to github actions from your fork repo.
2. Click workflow "Regenerate all code".
3. Choose the branch you are working on, and click "Run workflow".
4. After the workflow success, there will be a new commit to your branch

dotnet test (at root)

Testing Details

autorest.testserver

autorest.testserver provides a platform for automated testing of the code generators.

It packages a bunch of test swagger files, along with a “mock” nodejs server.

The swagger files are compiled, and then run, which pings the mock server (to verify behavior). This tests both the Modeler 4 and language specific codegen.

This document contains some additional technical details.

cadl-ranch

cadl-ranch is similar to autorest.testserver, which provides a platform for automated testing too. The difference is the testing target of cadl-ranch is typespec generated SDK.

Sometimes when we are adding new tests in cadl-ranch, we might want to make sure the tests and corresponding mock APIs work well by applying these newly added/modified tests to autorest.csharp. To realize this, run .\eng\ApplyCadlRanch.ps1 {cadl-ranch path} or just run .\eng\ApplyCadlRanch.ps1 if cadl-ranch folder is at the same folder of autorest.csharp.

PR Merge Process

When the automatic PR is created for azure-sdk-for-net if there are any issues found all other changes to autorest.csharp are blocked until those issues are resolved. This means we should be certain that the changes we are making create the expected result in azure-sdk-for-net prior to merging our PR.

Preview changes in azure-sdk-for-net

This step could be done manually or automatically with below steps:

Go to Autorest Regen Preview pipeline, and click "Run Pipeline". In "Branch/tag", type in your PR ref, i.e. refs/pull/3215/head, or refs/pull/3215/merge. Click "Run". After the build finishes, there will be a PR starting with "Autorest Regen Preview" in azure-sdk-for-net.

Make sure changes in azure-sdk-for-net is expected before merging your autorest.csharp PR

Once this is done we want to ensure this regen PR is discoverable as well as the key stakeholders who would need to sign off mark this PR as either approved or request changes.

• In the autorest.csharp PR description please add a line at the very top indicating which azure-sdk-for-net PR is the regeneration for this PR. An example would look like this
• Next have any stakeholders that would need to review do so in this PR and mark it as approved or request changes.
• Once all stakeholders review and approve of the PR we are ready for the next step of merging the autorest.csharp PR.

Merge azure-sdk-for-net PR

When the autorest.csharp PR gets merged there will be an automatic azure-sdk-for-net PR created under the azure-sdk fork but this PR will not contain any of the Export-API changes nor will it contain any custom changes to fix test cases / snippet references. It is therefore recommended that we merge this PR into our custom PR we made to validate there are no additional changes we didn't expect.

• Undo the changes to the nuget config and Packages.Data.props if you have not already done so.
• Add a note in the autogenerated PR that conflicts are being resolved in PR you created above so that people know where to follow the conversation.
• If you haven't done so add azure-sdk as an upstream and pull the branch that the automatic PR uses auto-update-autorest into your local azure-sdk-for-net branch.
  • git remote add azure-sdk https://github.com/azure-sdk/azure-sdk-for-net
  • git fetch azure-sdk
  • git pull azure-sdk auto-update-autorest
• This should have zero conflicts and if it does something wasn't done correctly in the PR that was created to demonstrate the regeneration.
  • If there are conflicts our only option here is to resolve them, but will most require another review from the stakeholders most likely.
• If there were no conflicts or after they are resolved push the changes to your branch and you can then merge the PR that was previous approved or re-approved in the case of conflicts.
• The autogenerated PR can now simply be closed

Use in azure-sdk-for-net repo

Run dotnet build /t:GenerateCode in the directory that contains your .csproj file.

This executes these targets.

Refer also to azure-sdk-for-net/CONTRIBUTING.md for more details.

PR Integration with Azure SDK Repository

Merging a change in autorest.csharp will open a PR against azure-sdk-for-net with every project’s generated code staged for review.