Merge pull request #8271 from maddieclayton/fixtestdocs

Fix test cmdlets

Author: cormacpayne

documentation/testing-docs/using-azure-test-framework.md

@@ -6,10 +6,8 @@
 	- [New-TestCredential](#new-testcredential)
 		- [Create New Service Principal](#create-new-service-principal)
 		- [Use Existing Service Principal](#use-existing-service-principal)
-		- [UserId](#userid)
 	- [Set-TestEnvironment](#set-testenvironment)
 		- [Existing Service Principal](#existing-service-principal)
-		- [UserId](#userid)
 	- [Manually Set Environment Variables](#manually-set-environment-variables)
 		- [Environment Variables](#environment-variables)
 		- [Playback Test](#playback-test)
@@ -51,11 +49,11 @@ This cmdlet, located in the [`Repo-Tasks` module](/tools/Repo-Tasks.psd1), which
 Using a service principal is the preferred option for recording tests because it works with both .NET Framework and .NET Core.  In order to create a new service principal, run this command with an unused service principal display name:
 
 ```powershell
-New-TestCredential -ServicePrincipalDisplayName "ScenarioTestCredentials" -ServicePrincipalSecret `
-"testpassword" -SubscriptionId <subscriptionId> -TenantId <tenantId> -RecordMode "Record"
+New-TestCredential -ServicePrincipalDisplayName "ScenarioTestCredentials" -SubscriptionId `
+<subscriptionId> -TenantId <tenantId> -RecordMode "Record"
 ```
 
-This command will create a new service principal, set the correct role assignment for this service principal based upon the subscription provided, and place the service principal id and secret into the credentials file.
+This command will create a new service principal, set the correct role assignment for this service principal based upon the subscription provided, and place the service principal id and automatically generated secret into the credentials file.
 
 Alternatively, to create a service principal, follow the [Azure AD guide to create a Application Service Principal](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-create-service-principal-portal#create-an-active-directory-application). The application type should be `Web app / API` and the sign-on URL value is irrelevant (you can set any value).
 
@@ -68,15 +66,6 @@ New-TestCredential -ServicePrincipalDisplayName "Existing Service Principal" -Se
 "testpassword" -SubscriptionId <subscriptionId> -TenantId <tenantId> -RecordMode "Record"
 ```
 
-#### UserId
-
-This is no longer the preferred option because it only works when running on .NET Framework. When running on .NET Core you may get an error like `Interactive Login is supported only in NET45 projects`.  Additionally, you will have to manually log in when running the scenario tests rather than being automatically validated.
-
-```powershell
-New-TestCredential -UserId "[email protected]" -SubscriptionId <subscriptionId> `
--TenantId <tenantId> -RecordMode "Record"
-```
-
 ### Set-TestEnvironment
 
 This cmdlet, located in the [`Repo-Tasks` module](/tools/Repo-Tasks.psd1), will directly set the environment variable for the session.
@@ -90,15 +79,6 @@ Set-TestEnvironment -ServicePrincipalId <servicePrincipalId> -ServicePrincipalSe
 "testpassword" -SubscriptionId <subscriptionId> -TenantId <tenantId> -RecordMode "Record"
 ```
 
-#### UserId
-
-This is no longer the preferred option because it only works when running on .NET Framework. When running on .NET Core you may get an error like `Interactive Login is supported only in NET45 projects`.
-
-```powershell
-Set-TestEnvironment -UserId "[email protected]" -SubscriptionId <subscriptionId> `
--TenantId <tenantId> -RecordMode "Record"
-```
-
 ### Manually Set Environment Variables
 
 #### Environment Variables
@@ -118,21 +98,8 @@ TEST_CSM_ORGID_AUTHENTICATION=
 AZURE_TEST_MODE=Playback
 ```
 
-#### Record Test with Interactive login using OrgId
-
-This is no longer the preferred option because it only works when running on .NET Framework. When running on .NET Core you may get an error like `Interactive Login is supported only in NET45 projects`.
-
-To use this option, set the following environment variables before starting Visual Studio:
-
-```
-TEST_CSM_ORGID_AUTHENTICATION=SubscriptionId={SubId};UserId={orgId};AADTenant={tenantId};Environment={env};HttpRecorderMode=Record;
-AZURE_TEST_MODE=Record
-```
-
 #### Record Test with service principal
 
-This is the preferred option for recording tests because it works with both .NET Framework and .NET Core.
-
 After the service principal is created, you will need to give it access to Azure resources. This can be done with the following PowerShell command, with the [Service Principal Application ID](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-create-service-principal-portal#get-application-id-and-authentication-key) (this is a guid, not the display name of the service principal) substituted in for `{clientId}`.
 
 ```powershell

tools/Modules/TestFx-Tasks.psd1

@@ -51,7 +51,7 @@ Copyright = '(c) 2016 ShahAbhijeet. All rights reserved.'
 # ProcessorArchitecture = ''
 
 # Modules that must be imported into the global environment prior to importing this module
-RequiredModules = @(@{ModuleName = 'AzureRM.Resources'; ModuleVersion = '5.0.0'; })
+RequiredModules = @(@{ModuleName = 'Az.Resources'; ModuleVersion = '1.0.0'; })
 
 # Assemblies that must be loaded prior to importing this module
 # RequiredAssemblies = @()

tools/Modules/TestFx-Tasks.psm1

@@ -1,39 +1,28 @@
 Function New-TestCredential
 {
     [CmdletBinding(
-        DefaultParameterSetName='SpnParamSet', 
         SupportsShouldProcess=$true
         )]
     param(
-        [Parameter(ParameterSetName='SpnParamSet', Mandatory=$true, HelpMessage='ServicePrincipal/ClientId you would like to use')]   
         [ValidateNotNullOrEmpty()]
         [string]$ServicePrincipalDisplayName,
 
-        [Parameter(ParameterSetName='SpnParamSet', Mandatory=$true, HelpMessage='ServicePrincipal Secret/ClientId Secret you would like to use')]
-        [ValidateNotNullOrEmpty()]
-        [securestring]$ServicePrincipalSecret,
-
-        [Parameter(ParameterSetName='UserIdParamSet', Mandatory=$true, HelpMessage = "UserId (OrgId) you would like to use")]
-        [ValidateNotNullOrEmpty()]
-        [string]$UserId,
-
-        [Parameter(ParameterSetName='CreateSpnParamSet', Mandatory=$true, HelpMessage = "SubscriptionId you would like to use")]
-        [Parameter(ParameterSetName='SpnParamSet', Mandatory=$true, HelpMessage = "SubscriptionId you would like to use")]
-        [Parameter(ParameterSetName='UserIdParamSet', Mandatory=$true, HelpMessage = "SubscriptionId you would like to use")]
+        [Parameter(Mandatory=$true, HelpMessage = "SubscriptionId you would like to use")]
         [ValidateNotNullOrEmpty()]
         [string]$SubscriptionId,
 
-        [Parameter(ParameterSetName='CreateSpnParamSet', Mandatory=$true, HelpMessage='AADTenant/TenantId you would like to use')]
-        [Parameter(ParameterSetName='SpnParamSet', Mandatory=$true, HelpMessage='AADTenant/TenantId you would like to use')]
+        [Parameter(Mandatory=$true, HelpMessage='AADTenant/TenantId you would like to use')]
         [ValidateNotNullOrEmpty()]
         [string]$TenantId,
 
-        [Parameter(ParameterSetName='CreateSpnParamSet', Mandatory=$true, HelpMessage = "SubscriptionId you would like to use")]
-        [Parameter(ParameterSetName='SpnParamSet', Mandatory=$true, HelpMessage = "Record tests, Playback tests, or neither")]
-        [Parameter(ParameterSetName='UserIdParamSet', Mandatory=$true, HelpMessage = "Record tests, Playback tests, or neither")]
+        [Parameter(Mandatory=$true, HelpMessage = "SubscriptionId you would like to use")]
         [ValidateSet("Playback", "Record", "None")]
         [string]$RecordMode,
 
+        [Parameter(Mandatory=$false, HelpMessage='ServicePrincipal Secret/ClientId Secret you would like to use (required for existing Service Principal)')]
+        [ValidateNotNullOrEmpty()]
+        [securestring]$ServicePrincipalSecret,
+
         [Parameter(Mandatory=$false, HelpMessage="Environment you would like to run in")]
         [ValidateSet("Prod", "Dogfood", "Current", "Next", "Custom")]
         [string]$TargetEnvironment='Prod',
@@ -81,15 +70,20 @@
     $credentials.Environment = $TargetEnvironment
 
     if ([string]::IsNullOrEmpty($ServicePrincipalDisplayName) -eq $false) {
-        $existingServicePrincipal = Get-AzureRmADServicePrincipal -SearchString $ServicePrincipalDisplayName | Where-Object {$_.DisplayName -eq $ServicePrincipalDisplayName}
+        $existingServicePrincipal = Get-AzADServicePrincipal -SearchString $ServicePrincipalDisplayName | Where-Object {$_.DisplayName -eq $ServicePrincipalDisplayName}
         if ($existingServicePrincipal -eq $null -and ($Force -or $PSCmdlet.ShouldContinue("ServicePrincipal `"" + $ServicePrincipalDisplayName + "`" does not exist, would you like to create a new ServicePrincipal with this name?", "Create ServicePrincipal?")))
         {
+            if (![string]::IsNullOrEmpty($ServicePrincipalSecret))
+            {
+                Write-Warning "Service Principal secrets are randomly generated, so provided secret value will not be used during creation."
+            }
+
             if ($TargetEnvironment -ne 'Prod')
             {
                 throw "To create a new Service Principal you must be in Prod. Please run again with `$TargetEnvironment set to 'Prod'"
             }
             $Scope = "/subscriptions/" + $SubscriptionId
-            $NewServicePrincipal = New-AzureRMADServicePrincipal -DisplayName $ServicePrincipalDisplayName -Password $ServicePrincipalSecret
+            $NewServicePrincipal = New-AzADServicePrincipal -DisplayName $ServicePrincipalDisplayName
             Write-Host "New ServicePrincipal created: " + $NewServicePrincipal.ApplicationId
 
             $NewRole = $null
@@ -98,30 +92,31 @@
             {
                 # Sleep here for a few seconds to allow the service principal application to become active (should only take a couple of seconds normally)
                 Start-Sleep 5
-                New-AzureRMRoleAssignment -RoleDefinitionName Contributor -ServicePrincipalName $NewServicePrincipal.ApplicationId -Scope $Scope | Write-Verbose -ErrorAction SilentlyContinue
-                $NewRole = Get-AzureRMRoleAssignment -ObjectId $NewServicePrincipal.Id -ErrorAction SilentlyContinue
+                New-AzRoleAssignment -RoleDefinitionName Contributor -ServicePrincipalName $NewServicePrincipal.ApplicationId -Scope $Scope | Write-Verbose -ErrorAction SilentlyContinue
+                $NewRole = Get-AzRoleAssignment -ObjectId $NewServicePrincipal.Id -ErrorAction SilentlyContinue
                 $Retries++;
             }
 
             $credentials.ServicePrincipal = $NewServicePrincipal.ApplicationId
+            $ServicePrincipalSecret = $NewServicePrincipal.Secret
             $BSTR = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($ServicePrincipalSecret)
             $UnsecurePassword = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($BSTR)
             $credentials.ServicePrincipalSecret = $UnsecurePassword
         }
 
         else
         {
+            if ([string]::IsNullOrEmpty($ServicePrincipalSecret))
+            {
+                throw "Service Principal secret required for existing Service Principal."
+            }
             $credentials.ServicePrincipal = $existingServicePrincipal.ApplicationId
             $BSTR = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($ServicePrincipalSecret)
             $UnsecurePassword = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($BSTR)
             $credentials.ServicePrincipalSecret = $UnsecurePassword
         }
     }
 
-    if ([string]::IsNullOrEmpty($UserId) -eq $false) {
-        $credentials.UserId = $UserId
-    }
-
     if ([string]::IsNullOrEmpty($TenantId) -eq $false) {
         $credentials.TenantId = $TenantId
     }
@@ -191,31 +186,25 @@ In order to successfully run a test, you will need SubscriptionId, TenantId
 This cmdlet will only prompt you for Subscription and Tenant information, rest all other parameters are optional
 
 #>
-    [CmdletBinding(DefaultParameterSetName='UserIdParamSet')]
+    [CmdletBinding()]
     param(
-        [Parameter(ParameterSetName='UserIdParamSet', Mandatory=$true, HelpMessage = "UserId (OrgId) you would like to use")]
-        [ValidateNotNullOrEmpty()]
-        [string]$UserId,
-
-        [Parameter(ParameterSetName='SpnParamSet', Mandatory=$true, HelpMessage='ServicePrincipal/ClientId you would like to use')]   
+        [Parameter(Mandatory=$true, HelpMessage='ServicePrincipal/ClientId you would like to use')]   
         [ValidateNotNullOrEmpty()]
         [string]$ServicePrincipalId,
 
-        [Parameter(ParameterSetName='SpnParamSet', Mandatory=$true, HelpMessage='ServicePrincipal Secret/ClientId Secret you would like to use')]
+        [Parameter(Mandatory=$true, HelpMessage='ServicePrincipal Secret/ClientId Secret you would like to use')]
         [ValidateNotNullOrEmpty()]
         [string]$ServicePrincipalSecret,
 
-        [Parameter(ParameterSetName='SpnParamSet', Mandatory=$true, HelpMessage = "SubscriptionId you would like to use")]
-        [Parameter(ParameterSetName='UserIdParamSet', Mandatory=$true, HelpMessage = "SubscriptionId you would like to use")]
+        [Parameter(Mandatory=$true, HelpMessage = "SubscriptionId you would like to use")]
         [ValidateNotNullOrEmpty()]
         [string]$SubscriptionId,
 
-        [Parameter(ParameterSetName='SpnParamSet', Mandatory=$true, HelpMessage='AADTenant/TenantId you would like to use')]
+        [Parameter(Mandatory=$true, HelpMessage='AADTenant/TenantId you would like to use')]
         [ValidateNotNullOrEmpty()]
         [string]$TenantId,
 
-	    [Parameter(ParameterSetName='SpnParamSet', Mandatory=$true, HelpMessage = "Would you like to record or playback your tests?")]
-        [Parameter(ParameterSetName='UserIdParamSet', Mandatory=$true, HelpMessage = "Would you like to record or playback your tests?")]
+	    [Parameter(Mandatory=$true, HelpMessage = "Would you like to record or playback your tests?")]
         [ValidateSet("Playback", "Record", "None")]
         [string]$RecordMode='Playback',
 
@@ -237,11 +226,6 @@ This cmdlet will only prompt you for Subscription and Tenant information, rest a
 
     $formattedConnStr = [string]::Format("SubscriptionId={0};HttpRecorderMode={1};Environment={2}", $SubscriptionId, $RecordMode, $TargetEnvironment)
 
-    if([string]::IsNullOrEmpty($UserId) -eq $false)
-    {
-        $formattedConnStr = [string]::Format([string]::Concat($formattedConnStr, ";UserId={0}"), $UserId)
-    }
-
     if([string]::IsNullOrEmpty($TenantId) -eq $false)
     {
         $formattedConnStr = [string]::Format([string]::Concat($formattedConnStr, ";AADTenant={0}"), $TenantId)
@@ -314,7 +298,7 @@ This cmdlet will only prompt you for Subscription and Tenant information, rest a
     }
 
     Write-Host "Below connection string is ready to be set"
-    Print-ConnectionString $UserId $SubscriptionId $TenantId $ServicePrincipal $ServicePrincipalSecret $RecordMode $TargetEnvironment
+    Print-ConnectionString $SubscriptionId $TenantId $ServicePrincipal $ServicePrincipalSecret $RecordMode $TargetEnvironment
 
     #Set connection string to Environment variable
     $env:TEST_CSM_ORGID_AUTHENTICATION=$formattedConnStr
@@ -333,13 +317,6 @@ This cmdlet will only prompt you for Subscription and Tenant information, rest a
 
 Function Print-ConnectionString([string]$uid, [string]$subId, [string]$aadTenant, [string]$spn, [string]$spnSecret, [string]$recordMode, [string]$targetEnvironment)
 {
-
-    if([string]::IsNullOrEmpty($uid) -eq $false)
-    {
-        Write-Host "UserId=" -ForegroundColor Green -NoNewline
-        Write-Host $uid";" -NoNewline 
-    }
-
     if([string]::IsNullOrEmpty($subId) -eq $false)
     {
         Write-Host "SubscriptionId=" -ForegroundColor Green -NoNewline