Merge pull request #164 from pspete/Standardise-Parameters

Standard Parameters

CHANGELOG.md

@@ -22,6 +22,10 @@ _2 years since first commit Anniversary Edition_
   - Default values no longer returned on pipeline
     - values for `BaseURI`, `WebSession`, `PVWAAppName`, `SessionToken` & `ExternalVersion` are
     not returned from module functions in output.
+- `UseV9API` & `UseV10API` Parameters renamed to `UseClassicAPI`
+  - Where functions support operations against both Classic & V10 API, default behaviour is to use the V10 API.
+  - Specify the `UseClassicAPI` switch parameter to force usage of the Classic API Endpoint.
+    - this parameter has an alias of `UseV9API` to attempt some backward compatibility.
 - Functions Removed
   - `New-PASSAMLSession` Removed
     - Functionality moved into `New-PASSession`.
@@ -31,6 +35,11 @@ _2 years since first commit Anniversary Edition_
     - Functionality moved into `Close-PASSession`.
   - `Close-PASSharedSession` Removed
     - Functionality moved into `Close-PASSession`.
+- Aliases Removed
+  - `Get-PASApplications` - Removed old pluralised alias
+  - `Get-PASApplicationAuthenticationMethods` - Removed old pluralised alias
+  - `Get-PASAccountCredentials` - Removed old pluralised alias
+  - `Get-PASSafeMembers` - Removed old pluralised alias
 
 ### Other Updates
 

Tests/Get-PASAccountGroup.Tests.ps1

@@ -60,7 +60,7 @@ Describe $FunctionName {
 
 		}
 
-		$response = $InputObj | Get-PASAccountGroup -UseV9API -verbose
+		$response = $InputObj | Get-PASAccountGroup -UseClassicAPI -verbose
 
 		Context "Input" {
 

Tests/Get-PASAccountPassword.Tests.ps1

@@ -56,13 +56,13 @@ Describe $FunctionName {
 
 				param($Parameter)
 
-				(Get-Command Get-PASAccountPassword).Parameters["$Parameter"].Attributes.Mandatory | Should Be $true
+				(Get-Command Get-PASAccountPassword).Parameters["$Parameter"].Attributes.Mandatory | Select-Object -Unique | Should Be $true
 
 			}
 
 		}
 
-		$response = $InputObj | Get-PASAccountPassword -verbose
+		$response = $InputObj | Get-PASAccountPassword -UseClassicAPI
 
 		Context "Input - legacy API parameterset" {
 
@@ -98,7 +98,7 @@ Describe $FunctionName {
 
 		Context "Input - v10 API parameterset" {
 
-			$InputObj | Get-PASAccountPassword -UseV10API -Reason "SomeReason" -TicketingSystemName "someSystem" -TicketId 12345
+			$InputObj | Get-PASAccountPassword -Reason "SomeReason" -TicketingSystemName "someSystem" -TicketId 12345
 
 			It "sends request" {
 
@@ -142,9 +142,9 @@ Describe $FunctionName {
 
 
 			It "throws error if version requirement not met" {
-$Script:ExternalVersion = "1.0"
-				{ $InputObj | Get-PASAccountPassword -UseV10API -Reason "SomeReason" -TicketingSystemName "someSystem" -TicketId 12345  } | Should Throw
-$Script:ExternalVersion = "0.0"
+				$Script:ExternalVersion = "1.0"
+				{ $InputObj | Get-PASAccountPassword -Reason "SomeReason" -TicketingSystemName "someSystem" -TicketId 12345 } | Should Throw
+				$Script:ExternalVersion = "0.0"
 			}
 
 
@@ -163,7 +163,7 @@ $Script:ExternalVersion = "0.0"
 				Mock Invoke-PASRestMethod -MockWith {
 					[system.Text.Encoding]::UTF8.GetBytes("psPAS")
 				}
-				$response = $InputObj | Get-PASAccountPassword -verbose
+				$response = $InputObj | Get-PASAccountPassword -UseClassicAPI
 				$response.Password | Should be "psPAS"
 
 			}
@@ -173,7 +173,7 @@ $Script:ExternalVersion = "0.0"
 				Mock Invoke-PASRestMethod -MockWith {
 					Write-Output "psPAS"
 				}
-				$response = $InputObj | Get-PASAccountPassword -verbose
+				$response = $InputObj | Get-PASAccountPassword -UseClassicAPI
 				$response.Password | Should be "psPAS"
 
 			}

Tests/New-PASUser.Tests.ps1

@@ -77,7 +77,7 @@ Describe $FunctionName {
 
 				}
 
-				$response = $InputObj | New-PASUser -UseV9API
+				$response = $InputObj | New-PASUser -UseClassicAPI
 
 			}
 
@@ -188,10 +188,10 @@ Describe $FunctionName {
 			}
 
 			It "throws error if version requirement not met" {
-$Script:ExternalVersion = "1.0"
+				$Script:ExternalVersion = "1.0"
 
-				{ $InputObj | New-PASUser  } | Should Throw
-$Script:ExternalVersion = "0.0"
+				{ $InputObj | New-PASUser } | Should Throw
+				$Script:ExternalVersion = "0.0"
 
 			}
 
@@ -215,7 +215,7 @@ $Script:ExternalVersion = "0.0"
 
 				}
 
-				$response = $InputObj | New-PASUser -UseV9API
+				$response = $InputObj | New-PASUser -UseClassicAPI
 
 			}
 

Tests/Remove-PASAccount.Tests.ps1

@@ -62,7 +62,7 @@ Describe $FunctionName {
 
 		}
 
-		$response = $InputObj | Remove-PASAccount -useV9API
+		$response = $InputObj | Remove-PASAccount -UseClassicAPI
 
 		Context "Input V9 API" {
 
@@ -129,9 +129,9 @@ Describe $FunctionName {
 			}
 
 			It "throws error if version requirement not met" {
-$Script:ExternalVersion = "1.0"
-				{ $InputObj | Remove-PASAccount  } | Should Throw
-$Script:ExternalVersion = "0.0"
+				$Script:ExternalVersion = "1.0"
+				{ $InputObj | Remove-PASAccount } | Should Throw
+				$Script:ExternalVersion = "0.0"
 			}
 
 		}

psPAS/Functions/AccountGroups/Get-PASAccountGroup.ps1

@@ -14,8 +14,8 @@ The following permissions are required on the safe where the account group will
 .PARAMETER Safe
 The Safe where the account groups are.
 
-.PARAMETER UseV9API
-Specify this switch to force usage of the legacy API endpoint.
+.PARAMETER UseClassicAPI
+Specify the UseClassicAPI to force usage the Classic (v9) API endpoint.
 
 .EXAMPLE
 Get-PASAccountGroup -Safe SafeName
@@ -52,7 +52,8 @@ Minimum CyberArk version 9.10
 			ValueFromPipelinebyPropertyName = $false,
 			ParameterSetName = "v9"
 		)]
-		[switch]$UseV9API
+		[Alias("UseV9API")]
+		[switch]$UseClassicAPI
 	)
 
 	BEGIN {
@@ -61,7 +62,7 @@ Minimum CyberArk version 9.10
 
 	PROCESS {
 
-		If($PSCmdlet.ParameterSetName -eq "v9") {
+		If ($PSCmdlet.ParameterSetName -eq "v9") {
 
 			Assert-VersionRequirement -ExternalVersion $Script:ExternalVersion -RequiredVersion $MinimumVersion
 
@@ -84,14 +85,14 @@ Minimum CyberArk version 9.10
 		#send request to PAS web service
 		$result = Invoke-PASRestMethod -Uri $URI -Method GET -WebSession $Script:WebSession
 
-		if($result) {
+		if ($result) {
 
 			$result | Add-ObjectDetail -typename psPAS.CyberArk.Vault.Account.Group
 
 		}
 
 	}#process
 
-	END {}#end
+	END { }#end
 
 }

psPAS/Functions/Accounts/Get-PASAccountPassword.ps1

@@ -17,8 +17,8 @@ If using version 10.1+ of the API:
 .PARAMETER AccountID
 The ID of the account whose password will be retrieved.
 
-.PARAMETER UseV10API
-Specify switch to explicitly use the version 10 api when only providing AccountID.
+.PARAMETER UseClassicAPI
+Specify the UseClassicAPI to force usage the Classic (v9) API endpoint.
 
 .PARAMETER Reason
 The reason that is required to be specified to retrieve the password/SSH key.
@@ -59,9 +59,9 @@ Password
 Ra^D0MwM666*&U
 
 .EXAMPLE
-Get-PASAccount -Keywords root -Safe Prod_Safe | Get-PASAccountPassword -UseV10API
+Get-PASAccount -Keywords root -Safe Prod_Safe | Get-PASAccountPassword -UseClassicAPI
 
-Will retrieve the password value of the account found by Get-PASAccount using the v10 API:
+Will retrieve the password value of the account found by Get-PASAccount using the classic (v9) API:
 
 Password
 --------
@@ -95,22 +95,27 @@ From version 10.1 onwards both passwords and ssh keys can be retrieved.
 
 .LINK
 #>
-	[Alias("Get-PASAccountCredentials")]
-	[CmdletBinding()]
+	[CmdletBinding(DefaultParameterSetName = "v10")]
 	param(
 		[parameter(
 			Mandatory = $true,
-			ValueFromPipelinebyPropertyName = $true
+			ValueFromPipelinebyPropertyName = $true,
+			ParameterSetName = "ClassicAPI"
+		)]
+		[parameter(
+			Mandatory = $true,
+			ValueFromPipelinebyPropertyName = $true,
+			ParameterSetName = "v10"
 		)]
 		[Alias("id")]
 		[string]$AccountID,
 
 		[parameter(
 			Mandatory = $false,
 			ValueFromPipelinebyPropertyName = $false,
-			ParameterSetName = "v10"
+			ParameterSetName = "ClassicAPI"
 		)]
-		[switch]$UseV10API,
+		[switch]$UseClassicAPI,
 
 		[parameter(
 			Mandatory = $false,
@@ -184,13 +189,13 @@ From version 10.1 onwards both passwords and ssh keys can be retrieved.
 				"Method" = "POST"
 
 				#Get all parameters that will be sent in the request
-				"Body"   = $PSBoundParameters | Get-PASParameter -ParametersToRemove AccountID, UseV10API | ConvertTo-Json
+				"Body"   = $PSBoundParameters | Get-PASParameter -ParametersToRemove AccountID | ConvertTo-Json
 
 			}
 
 		}
 
-		Else {
+		ElseIf ($($PSCmdlet.ParameterSetName) -eq "ClassicAPI") {
 
 			#For Version 9.7+
 			$Request = @{

psPAS/Functions/Accounts/Remove-PASAccount.ps1

@@ -12,8 +12,8 @@ If running against a CyberArk version earlier than 10.4, you must specify the Us
 The unique ID  of the account to delete.
 This is retrieved by the Get-PASAccount function.
 
-.PARAMETER UseV9API
-Specify this switch to force usage of the legacy API endpoint.
+.PARAMETER UseClassicAPI
+Specify the UseClassicAPI to force usage the Classic (v9) API endpoint.
 
 .EXAMPLE
 Remove-PASAccount -AccountID 19_1
@@ -46,7 +46,8 @@ None
 			ValueFromPipelinebyPropertyName = $false,
 			ParameterSetName = "v9"
 		)]
-		[switch]$UseV9API
+		[Alias("UseV9API")]
+		[switch]$UseClassicAPI
 	)
 
 	BEGIN {
@@ -55,7 +56,7 @@ None
 
 	PROCESS {
 
-		If($PSCmdlet.ParameterSetName -eq "V9") {
+		If ($PSCmdlet.ParameterSetName -eq "V9") {
 
 			#Create URL for request (earlier than 10.4)
 			$URI = "$Script:BaseURI/WebServices/PIMServices.svc/Accounts/$AccountID"
@@ -72,7 +73,7 @@ None
 
 		}
 
-		if($PSCmdlet.ShouldProcess($AccountID, "Delete Account")) {
+		if ($PSCmdlet.ShouldProcess($AccountID, "Delete Account")) {
 
 			#Send request to webservice
 			Invoke-PASRestMethod -Uri $URI -Method DELETE -WebSession $Script:WebSession
@@ -81,5 +82,5 @@ None
 
 	}#process
 
-	END {}#end
+	END { }#end
 }

psPAS/Functions/Applications/Get-PASApplication.ps1

@@ -69,7 +69,6 @@ To force all output to be shown, pipe to Select-Object *
 .LINK
 
 #>
-	[Alias("Get-PASApplications")]
 	[CmdletBinding(DefaultParameterSetName = 'byQuery')]
 	param(
 		[parameter(
@@ -108,23 +107,23 @@ To force all output to be shown, pipe to Select-Object *
 		[boolean]$IncludeSublocations
 	)
 
-	BEGIN {}#begin
+	BEGIN { }#begin
 
 	PROCESS {
 
 		#Base URL for Request
 		$URI = "$Script:BaseURI/WebServices/PIMServices.svc/Applications"
 
 		#If AppID specified
-		If($($PSCmdlet.ParameterSetName) -eq "byAppID") {
+		If ($($PSCmdlet.ParameterSetName) -eq "byAppID") {
 
 			#Build URL from base URL
 			$URI = "$URI/$($AppID | Get-EscapedString)"
 
 		}
 
 		#If search query specified
-		ElseIf($($PSCmdlet.ParameterSetName) -eq "byQuery") {
+		ElseIf ($($PSCmdlet.ParameterSetName) -eq "byQuery") {
 
 			#Get Parameters to include in request
 			$boundParameters = $PSBoundParameters | Get-PASParameter
@@ -144,7 +143,7 @@ To force all output to be shown, pipe to Select-Object *
 		#Send request to web service
 		$result = Invoke-PASRestMethod -Uri $URI -Method GET -WebSession $Script:WebSession
 
-		if($result) {
+		if ($result) {
 
 			#Return results
 			$result.application | Add-ObjectDetail -typename psPAS.CyberArk.Vault.Application
@@ -153,6 +152,6 @@ To force all output to be shown, pipe to Select-Object *
 
 	}#process
 
-	END {}#end
+	END { }#end
 
 }

psPAS/Functions/Applications/Get-PASApplicationAuthenticationMethod.ps1

@@ -33,7 +33,6 @@ To force all output to be shown, pipe to Select-Object *
 .LINK
 
 #>
-	[Alias("Get-PASApplicationAuthenticationMethods")]
 	[CmdletBinding()]
 	param(
 		[parameter(
@@ -43,7 +42,7 @@ To force all output to be shown, pipe to Select-Object *
 		[string]$AppID
 	)
 
-	BEGIN {}#begin
+	BEGIN { }#begin
 
 	PROCESS {
 
@@ -53,14 +52,14 @@ To force all output to be shown, pipe to Select-Object *
 
 		$result = Invoke-PASRestMethod -Uri $URI -Method GET -WebSession $Script:WebSession
 
-		if($result) {
+		if ($result) {
 
 			$result.authentication | Add-ObjectDetail -typename psPAS.CyberArk.Vault.ApplicationAuth
 
 		}
 
 	}#process
 
-	END {}#end
+	END { }#end
 
 }