From ac60f61c1024be64f683e8d132b58969e8935ed3 Mon Sep 17 00:00:00 2001 From: Nanxiang Liu Date: Mon, 27 Mar 2023 16:07:02 +0800 Subject: [PATCH 1/3] add parameter sets doc --- docs/parametersets.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 docs/parametersets.md diff --git a/docs/parametersets.md b/docs/parametersets.md new file mode 100644 index 0000000000..d8383db74c --- /dev/null +++ b/docs/parametersets.md @@ -0,0 +1,18 @@ +# ParameterSets in Autorest Generation + +When developing PowerShell commands for a service, you may encounter various command variants related to creating new resources. These variants correspond to different parameter sets and are used in different scenarios, let's take `create` for example: + +1. Create: This is the standard Create command that accepts a request body as input and creates a new resource in the service. + +2. CreateExpanded: This variant is used when the request body contains nested objects or arrays. It flattens the request body and expands the properties, making it easier to work with in PowerShell. + +3. CreateViaIdentity: This variant is used when you want to create a new resource by referencing an existing resource in the service. It accepts an identity object as input (suppoorting Powershell pipeline) and uses it to create the new resource. + +4. CreateViaIdentityExpanded: This variant combines the functionality of CreateExpanded and CreateViaIdentity. It accepts an identity object as input and flattens the request body, expanding the properties. + +Similar variants may exist for other verbs, such as Update, Get, Remove, etc. +For New-* cmdlets, ViaIdentity is not required, so CreateViaIdentityExpanded is removed as well. + +Whether or not to use these variants in your service depends on the specific requirements and scenarios of your service. In general, you may want to consider using these variants if your service has complex request bodies with nested objects or arrays, or if you want to support creating resources via identity objects. + +Documentation on these variants may vary depending on the service and platform you are using. However, you can refer to the example of readme.md in [here](https://eng.ms/docs/cloud-ai-platform/azure-core/azure-management-and-platforms/control-plane-bburns/azure-cli-tools-azure-cli-powershell-and-terraform/azure-cli-tools/onboarding/azurepowershell/dev_guidance_codegen#service-configuration). From 57132029e24b5a676f11ce7a6598f95dafd0ec52 Mon Sep 17 00:00:00 2001 From: Nanxiang Liu Date: Mon, 27 Mar 2023 16:10:35 +0800 Subject: [PATCH 2/3] add parameter sets doc --- docs/parametersets.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/parametersets.md b/docs/parametersets.md index d8383db74c..dc8e1a4a91 100644 --- a/docs/parametersets.md +++ b/docs/parametersets.md @@ -10,8 +10,7 @@ When developing PowerShell commands for a service, you may encounter various com 4. CreateViaIdentityExpanded: This variant combines the functionality of CreateExpanded and CreateViaIdentity. It accepts an identity object as input and flattens the request body, expanding the properties. -Similar variants may exist for other verbs, such as Update, Get, Remove, etc. -For New-* cmdlets, ViaIdentity is not required, so CreateViaIdentityExpanded is removed as well. +Similar variants may exist for other verbs, such as Update, Get, Remove, etc. For New-* cmdlets, ViaIdentity is not required, so CreateViaIdentityExpanded is removed as well. Whether or not to use these variants in your service depends on the specific requirements and scenarios of your service. In general, you may want to consider using these variants if your service has complex request bodies with nested objects or arrays, or if you want to support creating resources via identity objects. From c4727a1e96ee19713f632d075770a7deaa95b52b Mon Sep 17 00:00:00 2001 From: Nanxiang Liu Date: Wed, 5 Apr 2023 15:31:19 +0800 Subject: [PATCH 3/3] revise doc --- docs/parametersets.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/parametersets.md b/docs/parametersets.md index dc8e1a4a91..3b1da2e016 100644 --- a/docs/parametersets.md +++ b/docs/parametersets.md @@ -1,6 +1,14 @@ # ParameterSets in Autorest Generation -When developing PowerShell commands for a service, you may encounter various command variants related to creating new resources. These variants correspond to different parameter sets and are used in different scenarios, let's take `create` for example: +In PowerShell, cmdlets are typically named with prefixes such as "New-", "Set-", "Get-", "Remove-", etc. to indicate the type of operation performed by the cmdlet, such as: + +New-Resource: Create a new resource +Set-Resource: Update an existing resource +Get-Resource: Retrieve a resource +Remove-Resource: Delete a resource +In addition, you can add additional prefixes and suffixes to differentiate between different cmdlets, such as "New-ResourceTemplate", "Get-ResourceUsage", etc., to better indicate their functionality and usage. + +When developing PowerShell commands for a service, you may encounter various command variants related to creating new resources. These variants correspond to different parameter sets and are used in different scenarios. The naming convention for ParameterSets variants typically involves a verb as a prefix, followed by an optional suffix such as "Expanded", "ViaIdentity", or "ViaIdentityExpanded" to specify different use cases and parameter sets. Let's take `create` for example: Variants for the Create command are often named "Create", "CreateExpanded", "CreateViaIdentity", and "CreateViaIdentityExpanded". 1. Create: This is the standard Create command that accepts a request body as input and creates a new resource in the service.