Add dotnet new template for Azure.Template (Azure#23984)

Resolves Azure#22782
kasobol-msft · Sep 16, 2021 · 9dc7eb7 · 9dc7eb7
1 parent ca89328
commit 9dc7eb7
Show file tree

Hide file tree

Showing 5 changed files with 160 additions and 60 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -58,7 +58,7 @@ Nuget package will be created in root directory under \artifacts\packages\Debug
 Run e.g. `msbuild eng\mgmt.proj /t:"Runtests" /p:Scope=Compute`
 In the above example _RunTests_ will build and run tests for Compute only or you can use command line CLI:
 
-```bash
+```dotnetcli
 dotnet test Compute\Microsoft.Azure.Management.Compute\tests\Microsoft.Azure.Management.Tests.csproj
 ```
 
@@ -75,7 +75,7 @@ Now you can use the same command on non-windows as above for e.g. on Ubuntu you
 
 If you want to enable code coverage reporting, on the command line pass `/p:CollectCoverage=true` like so:
 
-```bash
+```dotnetcli
 dotnet tool restore
 dotnet test /p:CollectCoverage=true
 ```
@@ -410,66 +410,85 @@ If you are adding a new service directory, ensure that it is mapped to a friendl
 
 ## On-boarding New generated code library
 
-1. Make a copy of `/sdk/template/Azure.Template` in you appropriate service directory and rename projects to `Azure.Management.*` for management libraries or `Azure.*` (e.g.  `sdk/storage/Azure.Management.Storage` or `sdk/storage/Azure.Storage.Blobs`)
+1. Install templates for both data-plane and management-plane (control-plan) SDKs:
+
+   ```dotnetcli
+   # Data-plane SDK
+   dotnet new --install sdk/template
+   dotnet new azuresdk --name Azure.MyService --output sdk/myservice --ServiceDirectory myservice --ProjectName Azure.MyService
+
+   # Management-plane SDK
+   dotnet new --install eng/templates/Azure.ResourceManager.Template
+   dotnet new azuremgmt --help
+   ```
+
+   There are several options available for management-plane SDKs. You can see all those available with `--help` as shown above, or
+   [read about them](https://github.com/heaths/azure-sdk-for-net/blob/main/eng/templates/README.md) in our documentation.
+
+   This will perform most of the renames, namespace fix-ups, etc., for you automatically; though, be sure to check all files - especially the README.md file(s) - for required manual changes.
+   If the template is already installed, this same command will upgrade it.
+
 2. Modify `autorest.md` to point to you Swagger file or central README.md file. E.g.
 
-``` yaml
-input-file:
-    - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/specification/storage/resource-manager/Microsoft.Storage/stable/2019-06-01/blob.json
-    - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/specification/storage/resource-manager/Microsoft.Storage/stable/2019-06-01/file.json
-    - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/specification/storage/resource-manager/Microsoft.Storage/stable/2019-06-01/storage.json
-```
+   ``` yaml
+   input-file:
+       - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/specification/storage/resource-manager/Microsoft.Storage/stable/2019-06-01/blob.json
+       - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/specification/storage/resource-manager/Microsoft.Storage/stable/2019-06-01/file.json
+       - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/specification/storage/resource-manager/Microsoft.Storage/stable/2019-06-01/storage.json
+   ```
 
-``` yaml
-require: https://github.com/Azure/azure-rest-api-specs/blob/49fc16354df7211f8392c56884a3437138317d1f/specification/azsadmin/resource-manager/storage/readme.md
-```
+   ``` yaml
+   require: https://github.com/Azure/azure-rest-api-specs/blob/49fc16354df7211f8392c56884a3437138317d1f/specification/azsadmin/resource-manager/storage/readme.md
+   ```
 
 3. Run `dotnet build /t:GenerateCode` in src directory of the project (e.g. `net\sdk\storage\Azure.Management.Storage\src`). This would run AutoRest and generate the code. (NOTE: this step requires Node 14).
 4. For management plan libraries add `azure-arm: true` setting to `autorest.md` client constructors and options would be auto-generated. For data-plane libraries follow the next two steps.
-4. Add a `*ClientOptions` type that inherits from `ClientOptions` and has a service version enum:
-
-``` C#
-namespace Azure.Management.Storage
-{
-    public class StorageManagementClientOptions: ClientOptions
-    {
-        private const ServiceVersion Latest = ServiceVersion.V2019_06_01;
-        internal static StorageManagementClientOptions Default { get; } = new StorageManagementClientOptions();
-
-        public StorageManagementClientOptions(ServiceVersion serviceVersion = Latest)
-        {
-            VersionString = serviceVersion switch
-            {
-                ServiceVersion.V2019_06_01 => "2019-06-01",
-                _ => throw new ArgumentOutOfRangeException(nameof(serviceVersion))
-            };
-        }
-
-        internal string VersionString { get; }
-
-        public enum ServiceVersion
-        {
-#pragma warning disable CA1707
-            V2019_06_01 = 1
-#pragma warning restore CA1707
-        }
-    }
-}
-```
-5. Add public constructors to all the clients using a partial class.
-``` C#
- public partial class FileSharesClient
-    {
-        public FileSharesClient(string subscriptionId, TokenCredential tokenCredential): this(subscriptionId, tokenCredential, StorageManagementClientOptions.Default)
-        {
-        }
-
-        public FileSharesClient(string subscriptionId, TokenCredential tokenCredential, StorageManagementClientOptions options):
-            this(new ClientDiagnostics(options), ManagementClientPipeline.Build(options, tokenCredential), subscriptionId, apiVersion: options.VersionString)
-        {
-        }
-    }
-```
+5. Add a `*ClientOptions` type that inherits from `ClientOptions` and has a service version enum:
+
+   ``` C#
+   namespace Azure.Management.Storage
+   {
+       public class StorageManagementClientOptions: ClientOptions
+       {
+           private const ServiceVersion Latest = ServiceVersion.V2019_06_01;
+           internal static StorageManagementClientOptions Default { get; } = new StorageManagementClientOptions();
+   
+           public StorageManagementClientOptions(ServiceVersion serviceVersion = Latest)
+           {
+               VersionString = serviceVersion switch
+               {
+                   ServiceVersion.V2019_06_01 => "2019-06-01",
+                   _ => throw new ArgumentOutOfRangeException(nameof(serviceVersion))
+               };
+           }
+   
+           internal string VersionString { get; }
+   
+           public enum ServiceVersion
+           {
+   #pragma warning disable CA1707 // Identifiers should not contain underscores
+               V2019_06_01 = 1
+   #pragma warning restore CA1707
+           }
+       }
+   }
+   ```
+
+6. Add public constructors to all the clients using a partial class.
+
+   ``` C#
+    public partial class FileSharesClient
+       {
+           public FileSharesClient(string subscriptionId, TokenCredential tokenCredential): this(subscriptionId, tokenCredential, StorageManagementClientOptions.Default)
+           {
+           }
+   
+           public FileSharesClient(string subscriptionId, TokenCredential tokenCredential, StorageManagementClientOptions options):
+               this(new ClientDiagnostics(options), ManagementClientPipeline.Build(options, tokenCredential), subscriptionId, apiVersion: options.VersionString)
+           {
+           }
+       }
+   ```
 
 ### Code Review Process
 

diff --git a/eng/templates/Azure.ResourceManager.Template/.template.config/template.json b/eng/templates/Azure.ResourceManager.Template/.template.config/template.json
@@ -1,7 +1,7 @@
 {
   "$schema": "http://json.schemastore.org/template",
   "author": "[email protected]",
-  "classifications": [ "ClassLibrary" ],
+  "classifications": [ "Azure", "ClassLibrary" ],
   "identity": "Azure.Management.TemplateProject",
   "name": "Azure Management SDK template: client project",
   "shortName": "azuremgmt",

diff --git a/sdk/template/.template.config/template.json b/sdk/template/.template.config/template.json
@@ -0,0 +1,79 @@
+{
+    "$schema": "http://json.schemastore.org/template",
+    "author": "Azure SDK for .NET",
+    "description": "Create a new Azure SDK e.g. dotnet new azuresdk --name Azure.MyService --output sdk/myservice --ServiceDirectory myservice --ProjectName Azure.MyService",
+    "classifications": [ "Azure", "ClassLibrary" ],
+    "identity": "Azure.Template",
+    "name": "Azure SDK",
+    "shortName": "azuresdk",
+    "tags": {
+        "language": "C#",
+        "type": "project"
+    },
+    "sourceName": "Azure.Template",
+    "preferNameDirectory": true,
+    "symbols": {
+        "ServiceDirectory": {
+            "type": "parameter",
+            "description": "This must match the name of the directory you create under the \"sdk\" directory e.g., \"myservice\" if outputting \"sdk/mysevice\".",
+            "datatype": "text",
+            "isRequired": true
+        },
+        "ProjectName": {
+            "type": "parameter",
+            "description": "This must match the name of the project e.g. pass the same value as you do to the built-in \"--name\" parameter.",
+            "datatype": "text",
+            "isRequired": true
+        },
+        "ServiceDirectoryPath": {
+            "type": "generated",
+            "generator": "join",
+            "parameters": {
+                "symbols": [
+                    {
+                        "type": "const",
+                        "value": "sdk/"
+                    },
+                    {
+                        "type": "ref",
+                        "value": "ServiceDirectory"
+                    }
+                ],
+                "separator": ""
+            },
+            "replaces": "sdk/template"
+        },
+        "SafeProjectName": {
+            "type": "generated",
+            "generator": "regex",
+            "parameters": {
+                "source": "ProjectName",
+                "steps": [
+                    {
+                        "regex": "\\.",
+                        "replacement": ""
+                    }
+                ]
+            },
+            "replaces": "AzureTemplate"
+        },
+        "YamlServiceDirectory": {
+            "type": "generated",
+            "generator": "join",
+            "parameters": {
+                "symbols": [
+                    {
+                        "type": "const",
+                        "value": "ServiceDirectory: "
+                    },
+                    {
+                        "type": "ref",
+                        "value": "ServiceDirectory"
+                    }
+                ],
+                "separator": ""
+            },
+            "replaces": "ServiceDirectory: template"
+        }
+    }
+}
diff --git a/sdk/template/ci.yml b/sdk/template/ci.yml
@@ -19,11 +19,13 @@ pr:
   paths:
     include:
     - sdk/template/
-    # The following paths should only be included in template/ci.yml, and removed from any other
-    # SDKs which copy this file.
+#if (false)
+    # The following paths should only be included in template/ci.yml, and removed from any other SDKs which copy this file.
+    # The surrounding conditions should accomplish that when installed with `dotnet new azsdk`.
     - common/Perf/
     - common/PerfStressShared/
     - common/Stress/
+#endif
 
 extends:
   template: ../../eng/pipelines/templates/stages/archetype-sdk-client.yml

diff --git a/sdk/template/test-resources.json b/sdk/template/test-resources.json
@@ -1,5 +1,5 @@
 {
-    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
+    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
     "contentVersion": "1.0.0.0",
     "parameters": {
         "baseName": {