From 1472f63764c04116348f26a564b897a9f75a36e6 Mon Sep 17 00:00:00 2001 From: Ryan Yates Date: Sun, 25 May 2025 00:15:57 +0100 Subject: [PATCH 1/8] Add an extended Snippet for Advanced Functions fixes #5197 --- snippets/PowerShell.json | 87 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) diff --git a/snippets/PowerShell.json b/snippets/PowerShell.json index 61fa010c85..65e66eca7b 100644 --- a/snippets/PowerShell.json +++ b/snippets/PowerShell.json @@ -238,6 +238,93 @@ "\t}", "}" ] + }, + "Function-Advanced-Doc": { + "prefix": ["function-advanced-doc", "cmdlet-doc"], + "description": "Script advanced function definition with full comment-based help and parameter attributes.", + "body": [ + "function ${1:Verb-Noun} {", + "\t<#", + "\t.SYNOPSIS", + "\tShort description", + "\t.DESCRIPTION", + "\tLong description", + "\t.EXAMPLE", + "\tExample of how to use this cmdlet", + "\t.EXAMPLE", + "\tAnother example of how to use this cmdlet", + "\t.INPUTS", + "\tInputs to this cmdlet (if any)", + "\t.OUTPUTS", + "\tOutput from this cmdlet (if any)", + "\t.NOTES", + "\tGeneral notes", + "\t.COMPONENT", + "\tThe component this cmdlet belongs to", + "\t.ROLE", + "\tThe role this cmdlet belongs to", + "\t.FUNCTIONALITY", + "\tThe functionality that best describes this cmdlet", + "\t#>", + "\t[CmdletBinding(DefaultParameterSetName = 'Parameter Set 1',", + "\t\tSupportsShouldProcess = $true,", + "\t\tPositionalBinding = $false,", + "\t\tHelpUri = 'http://www.microsoft.com/',", + "\t\tConfirmImpact = 'Medium')]", + "\t[Alias()]", + "\t[OutputType([String])]", + "\tparam (", + "\t\t# Param1 help description", + "\t\t[Parameter(Mandatory = $true,", + "\t\t\tValueFromPipeline = $true,", + "\t\t\tValueFromPipelineByPropertyName = $true,", + "\t\t\tValueFromRemainingArguments = $false,", + "\t\t\tPosition = 0,", + "\t\t\tParameterSetName = 'Parameter Set 1')]", + "\t\t[ValidateNotNull()]", + "\t\t[ValidateNotNullOrEmpty()]", + "\t\t[ValidateCount(0, 5)]", + "\t\t[ValidateSet(\"sun\", \"moon\", \"earth\")]", + "\t\t[Alias(\"p1\")]", + "\t\t$Param1,", + "", + "\t\t# Param2 help description", + "\t\t[Parameter(ParameterSetName = 'Parameter Set 1')]", + "\t\t[AllowNull()]", + "\t\t[AllowEmptyCollection()]", + "\t\t[AllowEmptyString()]", + "\t\t[ValidateScript({ $true })]", + "\t\t[ValidateRange(0, 5)]", + "\t\t[int]", + "\t\t$Param2,", + "", + "\t\t# Param3 help description", + "\t\t[Parameter(ParameterSetName = 'Another Parameter Set')]", + "\t\t[ValidatePattern(\"[a-z]*\")]", + "\t\t[ValidateLength(0, 15)]", + "\t\t[String]", + "\t\t$Param3", + "\t)", + "", + "\tbegin {", + "\t\t#BeginCodeHere", + "\t}", + "", + "\tprocess {", + "\t\tif ($pscmdlet.ShouldProcess(\"Target\", \"Operation\")) {", + "\t\t\t#ProcessCodeHere", + "\t\t}", + "\t}", + "", + "\tend {", + "\t\t#EndCodeHere", + "\t}", + "", + "\tclean {", + "\t\t#CleanCodeHere - Added in 7.3 for more information see https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_advanced_methods?view=powershell-7.5#clean", + "\t}", + "}" + ] }, "Function-Inline": { "prefix": "function-inline", From 90f312b9f2abf513ce02e412d0fe0cacb310e384 Mon Sep 17 00:00:00 2001 From: Ryan Yates Date: Sun, 25 May 2025 20:25:54 +0100 Subject: [PATCH 2/8] missed the escape chars --- snippets/PowerShell.json | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/snippets/PowerShell.json b/snippets/PowerShell.json index 65e66eca7b..d096243bf0 100644 --- a/snippets/PowerShell.json +++ b/snippets/PowerShell.json @@ -267,18 +267,18 @@ "\tThe functionality that best describes this cmdlet", "\t#>", "\t[CmdletBinding(DefaultParameterSetName = 'Parameter Set 1',", - "\t\tSupportsShouldProcess = $true,", - "\t\tPositionalBinding = $false,", + "\t\tSupportsShouldProcess = \\$true,", + "\t\tPositionalBinding = \\$false,", "\t\tHelpUri = 'http://www.microsoft.com/',", "\t\tConfirmImpact = 'Medium')]", "\t[Alias()]", "\t[OutputType([String])]", "\tparam (", "\t\t# Param1 help description", - "\t\t[Parameter(Mandatory = $true,", - "\t\t\tValueFromPipeline = $true,", - "\t\t\tValueFromPipelineByPropertyName = $true,", - "\t\t\tValueFromRemainingArguments = $false,", + "\t\t[Parameter(Mandatory = \\$true,", + "\t\t\tValueFromPipeline = \\$true,", + "\t\t\tValueFromPipelineByPropertyName = \\$true,", + "\t\t\tValueFromRemainingArguments = \\$false,", "\t\t\tPosition = 0,", "\t\t\tParameterSetName = 'Parameter Set 1')]", "\t\t[ValidateNotNull()]", @@ -286,24 +286,24 @@ "\t\t[ValidateCount(0, 5)]", "\t\t[ValidateSet(\"sun\", \"moon\", \"earth\")]", "\t\t[Alias(\"p1\")]", - "\t\t$Param1,", + "\t\t\\$Param1,", "", "\t\t# Param2 help description", "\t\t[Parameter(ParameterSetName = 'Parameter Set 1')]", "\t\t[AllowNull()]", "\t\t[AllowEmptyCollection()]", "\t\t[AllowEmptyString()]", - "\t\t[ValidateScript({ $true })]", + "\t\t[ValidateScript({ \\$true })]", "\t\t[ValidateRange(0, 5)]", "\t\t[int]", - "\t\t$Param2,", + "\t\t\\$Param2,", "", "\t\t# Param3 help description", "\t\t[Parameter(ParameterSetName = 'Another Parameter Set')]", "\t\t[ValidatePattern(\"[a-z]*\")]", "\t\t[ValidateLength(0, 15)]", "\t\t[String]", - "\t\t$Param3", + "\t\t\\$Param3", "\t)", "", "\tbegin {", @@ -311,7 +311,7 @@ "\t}", "", "\tprocess {", - "\t\tif ($pscmdlet.ShouldProcess(\"Target\", \"Operation\")) {", + "\t\tif (\\$pscmdlet.ShouldProcess(\"Target\", \"Operation\")) {", "\t\t\t#ProcessCodeHere", "\t\t}", "\t}", From fca641c5b131e14d73a86267cd17e0f5f0a2079a Mon Sep 17 00:00:00 2001 From: Ryan Yates Date: Wed, 28 May 2025 01:16:35 +0100 Subject: [PATCH 3/8] Name and prefix update --- snippets/PowerShell.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/snippets/PowerShell.json b/snippets/PowerShell.json index d096243bf0..0c7e7a230a 100644 --- a/snippets/PowerShell.json +++ b/snippets/PowerShell.json @@ -239,8 +239,8 @@ "}" ] }, - "Function-Advanced-Doc": { - "prefix": ["function-advanced-doc", "cmdlet-doc"], + "Function-Advanced-Doc-Full-Example-From-ISE": { + "prefix": ["function-advanced-doc-fromISE", "cmdlet-doc-fromISE"], "description": "Script advanced function definition with full comment-based help and parameter attributes.", "body": [ "function ${1:Verb-Noun} {", From 42e594b62605278405bb5d45db9243a9b57d74f7 Mon Sep 17 00:00:00 2001 From: Ryan Yates Date: Wed, 28 May 2025 01:17:29 +0100 Subject: [PATCH 4/8] address comments --- snippets/PowerShell.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/snippets/PowerShell.json b/snippets/PowerShell.json index 0c7e7a230a..e427d3315d 100644 --- a/snippets/PowerShell.json +++ b/snippets/PowerShell.json @@ -267,9 +267,9 @@ "\tThe functionality that best describes this cmdlet", "\t#>", "\t[CmdletBinding(DefaultParameterSetName = 'Parameter Set 1',", - "\t\tSupportsShouldProcess = \\$true,", - "\t\tPositionalBinding = \\$false,", - "\t\tHelpUri = 'http://www.microsoft.com/',", + "\t\tSupportsShouldProcess,", + "\t\tPositionalBinding", + "\t\tHelpUri = 'http://yourwebsiteforhelp.here',", "\t\tConfirmImpact = 'Medium')]", "\t[Alias()]", "\t[OutputType([String])]", From a8bacf6355391c891534bc7bd6ca3f5d6d56cf8f Mon Sep 17 00:00:00 2001 From: Ryan Yates Date: Wed, 28 May 2025 01:27:59 +0100 Subject: [PATCH 5/8] add new param with link to Argument Completer Docs --- snippets/PowerShell.json | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/snippets/PowerShell.json b/snippets/PowerShell.json index e427d3315d..676c23e8cc 100644 --- a/snippets/PowerShell.json +++ b/snippets/PowerShell.json @@ -304,6 +304,13 @@ "\t\t[ValidateLength(0, 15)]", "\t\t[String]", "\t\t\\$Param3", + "", + "\t\t# Checkout the docs https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_argument_completion?view=powershell-7.5#argumentcompletions-attribute on differnet ways to provide Argumnet Completion", + "\t\t[Parameter(ParameterSetName = 'Yet Another Parameter Set')]", + "\t\t[ArgumentCompleter({'add script'})]", + "\t\t[ValidateLength(0, 15)]", + "\t\t[String]", + "\t\t\\$Param4", "\t)", "", "\tbegin {", From 3edda97316e5fb620fc427c01c78bc87f03d3347 Mon Sep 17 00:00:00 2001 From: Ryan Yates Date: Wed, 28 May 2025 01:30:25 +0100 Subject: [PATCH 6/8] =?UTF-8?q?=F0=9F=A4=A6=F0=9F=8F=BB=E2=80=8D=E2=99=82?= =?UTF-8?q?=EF=B8=8F=20spellings,=20if=20only=20I=20could=20nto=20mkae=20d?= =?UTF-8?q?ez=20mistakes=20=F0=9F=A4=A6=F0=9F=8F=BB=E2=80=8D=E2=99=82?= =?UTF-8?q?=EF=B8=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- snippets/PowerShell.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/snippets/PowerShell.json b/snippets/PowerShell.json index 676c23e8cc..9aa19f61c1 100644 --- a/snippets/PowerShell.json +++ b/snippets/PowerShell.json @@ -305,7 +305,7 @@ "\t\t[String]", "\t\t\\$Param3", "", - "\t\t# Checkout the docs https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_argument_completion?view=powershell-7.5#argumentcompletions-attribute on differnet ways to provide Argumnet Completion", + "\t\t# Checkout the docs https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_argument_completion?view=powershell-7.5#argumentcompletions-attribute on different ways to provide Argument Completion", "\t\t[Parameter(ParameterSetName = 'Yet Another Parameter Set')]", "\t\t[ArgumentCompleter({'add script'})]", "\t\t[ValidateLength(0, 15)]", From 788eab17af481f565762f5f9614ac16a5c99bbce Mon Sep 17 00:00:00 2001 From: Ryan Yates Date: Wed, 28 May 2025 01:39:37 +0100 Subject: [PATCH 7/8] add multiple function aliases to show how to used them --- snippets/PowerShell.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/snippets/PowerShell.json b/snippets/PowerShell.json index 9aa19f61c1..452164e050 100644 --- a/snippets/PowerShell.json +++ b/snippets/PowerShell.json @@ -271,7 +271,7 @@ "\t\tPositionalBinding", "\t\tHelpUri = 'http://yourwebsiteforhelp.here',", "\t\tConfirmImpact = 'Medium')]", - "\t[Alias()]", + "\t[Alias('Be-lazyWithThis','lzy','Use-OldFunctionName')]", "\t[OutputType([String])]", "\tparam (", "\t\t# Param1 help description", From 04eb12bb75585449a2213cf7967b046461c00943 Mon Sep 17 00:00:00 2001 From: Ryan Yates Date: Wed, 28 May 2025 02:05:55 +0100 Subject: [PATCH 8/8] drop use of $true for param attributes --- snippets/PowerShell.json | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/snippets/PowerShell.json b/snippets/PowerShell.json index 452164e050..1595b1bc21 100644 --- a/snippets/PowerShell.json +++ b/snippets/PowerShell.json @@ -275,10 +275,10 @@ "\t[OutputType([String])]", "\tparam (", "\t\t# Param1 help description", - "\t\t[Parameter(Mandatory = \\$true,", - "\t\t\tValueFromPipeline = \\$true,", - "\t\t\tValueFromPipelineByPropertyName = \\$true,", - "\t\t\tValueFromRemainingArguments = \\$false,", + "\t\t[Parameter(Mandatory,", + "\t\t\tValueFromPipeline,", + "\t\t\tValueFromPipelineByPropertyName,", + "\t\t\tValueFromRemainingArguments,", "\t\t\tPosition = 0,", "\t\t\tParameterSetName = 'Parameter Set 1')]", "\t\t[ValidateNotNull()]", @@ -307,7 +307,7 @@ "", "\t\t# Checkout the docs https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_argument_completion?view=powershell-7.5#argumentcompletions-attribute on different ways to provide Argument Completion", "\t\t[Parameter(ParameterSetName = 'Yet Another Parameter Set')]", - "\t\t[ArgumentCompleter({'add script'})]", + "\t\t[ArgumentCompleter({'add completer script'})]", "\t\t[ValidateLength(0, 15)]", "\t\t[String]", "\t\t\\$Param4",