Merge branch 'feature/v3' of https://github.com/Azure/autorest.csharp …

…into contentType3793

Packages.Data.props

@@ -8,7 +8,7 @@
   </ItemGroup>
 
   <ItemGroup Condition="$(MSBuildProjectName.EndsWith('.Tests'))">
-    <PackageReference Update="Azure.Identity" Version="1.7.0" />
+    <PackageReference Update="Azure.Identity" Version="1.10.4" />
     <PackageReference Update="NUnit3TestAdapter" Version="4.4.2" />
     <PackageReference Update="Microsoft.NET.Test.Sdk" Version="17.0.0" />
   </ItemGroup>
@@ -27,9 +27,9 @@
   <ItemGroup>
     <PackageReference Update="NUnit" Version="3.13.2" />
     <PackageReference Update="System.Net.ClientModel" Version="1.0.0-beta.1" />
-    <PackageReference Update="Azure.Core" Version="1.35.0" />
+    <PackageReference Update="Azure.Core" Version="1.36.0" />
     <PackageReference Update="Azure.Core.Experimental" Version="0.1.0-preview.18" />
-    <PackageReference Update="Azure.ResourceManager" Version="1.8.1" />
+    <PackageReference Update="Azure.ResourceManager" Version="1.9.0" />
     <PackageReference Update="Azure.Core.Expressions.DataFactory" Version="1.0.0-beta.4" />
     <PackageReference Update="Microsoft.AspNetCore.Server.Kestrel" Version="2.2.0" />
     <PackageReference Update="System.Diagnostics.DiagnosticSource" Version="6.0.1" />

package.json

@@ -3,11 +3,21 @@
   "private": true,
   "description": "package.json intended for in-repo use only, package.json used for publishing is located in src/AutoRest.CSharp/package.json",
   "devDependencies": {
-    "@azure-tools/typespec-csharp": "file:src/TypeSpec.Extension/Emitter.Csharp",
     "@azure-tools/cadl-ranch-mockapis": "file:test/CadlRanchMockApis",
+    "@azure-tools/typespec-autorest": "0.36.1",
+    "@azure-tools/typespec-azure-core": "0.36.0",
+    "@azure-tools/typespec-azure-resource-manager": "0.36.1",
+    "@azure-tools/typespec-client-generator-core": "0.36.0",
+    "@azure-tools/typespec-csharp": "file:src/TypeSpec.Extension/Emitter.Csharp",
     "@microsoft.azure/autorest.testserver": "3.3.48",
-    "autorest": "3.6.3",
-    "@typespec/openapi": "^0.49.0",
-    "@typespec/openapi3": "^0.49.0"
+    "@typespec/compiler": "0.50.0",
+    "@typespec/eslint-config-typespec": "0.50.0",
+    "@typespec/eslint-plugin": "0.50.0",
+    "@typespec/http": "0.50.0",
+    "@typespec/openapi": "0.50.0",
+    "@typespec/openapi3": "0.50.0",
+    "@typespec/rest": "0.50.0",
+    "@typespec/versioning": "0.50.0",
+    "autorest": "3.6.3"
   }
 }

readme.md

@@ -164,19 +164,84 @@ Note:
 
 For more details please refer [these](https://github.com/Azure/autorest/tree/master/docs/generate) docs to generate code from your OpenAPI definition using AutoRest.
 
-## Debugging 
+## Debugging
 
-There are two entry points for debugging autorest.csharp:
+The generator consists of two parts, first part consumes the input (swagger or TypeSpec) and produce an intermediate result which the second part consumes them to produce the generated code.
 
-- Opening AutoRest.CSharp.sln in Visual Studio will contain a debugging profile for each sample and test. These only run the "back half", using the yaml file generated by autorest.core as input.
-- ./Generate.ps1 will execute the entire pipeline by invoking autorest and including autorest.csharp as a plugin. Add:
+When the input is swagger files, the generator leverages the processes and pipelines from [autorest](https://github.com/Azure/autorest), and its first part is the autorest plugin `autorest.modelerfour` which produces the file `CodeModel.yaml` and `Configuration.json`.
 
+When the input is TypeSpec files, the first part is the autorest plugin `@azure-tools/typespec-csharp` which produces the file `tspCodeModel.json` and `Configuration.json`.
+
+The second part of the generator is written in `C#` and consumes `Configuration.json` and `CodeModel.yaml`/`tspCodeModel.json` to produce the generated code.
+
+This section shows how to debug the second part of the generator which takes `Configuration.json` and `CodeModel.yaml`/`tspCodeModel.json` as input.
+
+### Debugging the projects inside the `autorest.csharp` repo
+
+The `autorest.csharp` repo contains quite a few sample projects and test projects to verify various of features of the generator. To debug these projects, you could just simply open the solution file `AutoRest.CSharp.sln` in Visual Studio and Visual Studio already has a corresponding debugging profile for each project which you could start debugging with.
+
+### Debugging the projects outside the `autorest.csharp` repo
+
+To debug a project outside the `autorest.csharp` repo, in addition to the prerequisites you must do to let your project be able to use the generator, you also need to do the following depending on the input type of your project.
+
+If your project is using the swagger files as input, and you use a markdown file (like `readme.md` or `autorest.md`) as the configuration of your autorest command, you need to add the following to your configuration `md` file
+
+```yml
+csharpgen:
+  attach: true
+```
+
+This will attach the debugger to either an existing Visual Studio instance or opening a new Visual Studio instance to debug the generator.
+
+If your project is using the swagger files as input, and you use the autorest command line to pass in the configurations, you need to add the following options to your autorest command:
+
+```bash
+--csharpgen.attach=true
+```
+to attach a debugger to the plugin process.
+
+If your project is using the TypeSpec files as input, you need to add the following options to your command line
+
+```
+--option @azure-tools/typespec-csharp.debug=true
+```
+to attach a debugger to the plugin process.
+
+If you need to use a locally built generator, you could use the following options to specify the path to the generator dll file:
+
+```
+--option @azure-tools/typespec-csharp.csharpGeneratorPath=/absolute/path/to/AutoRest.CSharp.dll
+```
+
+Usually you should find the `AutoRest.CSharp.dll` file here: `[Root of autorest.csharp repo]/artifacts/bin/AutoRest.CSharp/Debug/net6.0/AutoRest.CSharp.dll`.
+
+### Debugging the projects in the `azure-sdk-for-net` repo
+
+There is a target defined in `azure-sdk-for-net` repo to generate the library code:
+```bash
+dotnet build /t:GenerateCode
 ```
+
+In `azure-sdk-for-net` repo, to debug a project that uses swagger files as input, you need to add the following to your `autorest.md` file
+
+```yml
 csharpgen:
   attach: true
 ```
 
-to the autorest configuration to attach a debugger to the plugin process.
+and then run `dotnet build /t:GenerateCode` and it will attach a debugger to the plugin process.
+
+To debug a TypeSpec project inside `azure-sdk-for-net` repo, you could run
+```powershell
+dotnet build /t:GenerateCode /p:typespecAdditionalOptions="debug=true"
+```
+to attach a debugger to the plugin process.
+
+If you are trying to use a locally built generator `dll` and debug it, you should run
+```powershell
+dotnet build /t:GenerateCode /p:typespecAdditionalOptions="csharpGeneratorPath=/absolute/path/to/AutoRest.CSharp.dll%3Bdebug=true"
+```
+where you must use `%3B` as escape of the semicolon to append multiple options.
 
 ## Debugging transforms