Value of task wrappers over pac cli vs calling pac cli directly?

[devkeydet]

One of the things we've recently introduced is making it easier to call pac cli directly in script tasks. Here's a trivial example.

trigger: none
pool:
  vmImage: ubuntu-latest
steps:
- task: PowerPlatformToolInstaller@2
  inputs:
    DefaultVersion: true
    AddToolsToPath: true
- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: |
      pac
    pwsh: true

For those who may not be aware, the Power Platform Build Tools tasks are almost exclusively convenience wrappers over pac, enabling you to execute pac capability using the yaml declarative syntax. We respect that there are strong opinions on the benefits of tasks vs doing the same thing with the pac directly. Some people prefer doing most of their pipeline work in script tasks and cli's. Some want the convenience of the tasks. One of the reasons we introduced AddToolsToPath is because there is effort to create each task or enhance tasks as we add capabilities to pac. We can't always get everything in pac exposed as a task in a given release and sometimes, due to other priorities, many things lag. Furthermore, it's debatable whether everything that pac offers should be a task in the first place. The "escape hatch" is "drop to pac in a script task". Personally, I have used this approach myself ever since the tasks were rewritten to be pac wrappers (and before joining the team). Increasingly, because of my own personal preference of using script tasks, I find myself using the tasks less and less, and calling pac directly in my pipelines more and more.

All of this leads to a potentially controversial, thought provoking, and opinionated discussion...

If we continue down this trend to make it "easy button" to use pac in script tasks, including making the auth setup more seamless, what's the value of task wrappers over pac vs calling pac directly to you?

Let the discussion begin...

[tehcrashxor]

As with many things, the differences come down to the tradeoffs between these different methods. One such tradeoff is in Service Connections:

Service Connections

ADO Service Connections provide a mechanism to share and control access to credentials across multiple pipelines. To take advantage of those, the task in question needs to be built to support them, so they cannot be sent to tasks such as the PowerShell script task.

As an alternative to using Service Connections, some auth information such as the username + password flow and the Service Principal via App ID + Tenant ID + Client Secret flow could be fairly easily handled with pipeline variables (or variable groups to share between multiple pipelines). This does however move the responsibility to mark the password or client secret as a secret onto the user, and not doing so could result in the credential leaking in the task logs. Using our Service Connections will always mark those values as secret, and thus ADO will mask those values in the logs without the user needing to do so themselves.

The bigger disadvantage to moving to running PAC directly here is in the Workload Identity Federation type. The ADO implementation of WIF sets the federated trust relationship between the Entra ID App and an ADO Service Connection. While there are workarounds to using that WIF Service Connection in that same linked discussion (direct link to the relevant post here), it does take some work to use that federated connection with a direct command line call, and is more of a hybrid approach.

[devkeydet]

But if we fixed those things?

[devkeydet]

There are already ways to address some of what you point out, albeit still with too much burden on the pipeline author. There is opportunity to make both of the scenarios you point out more seamless. Here are two examples of what you can do today. Imagine these two scenarios "just work" without having to do the setup below.

Workload Identity Federation, followed by multiple calls to pac in subsequent script tasks

trigger: none
pool:
  vmImage: ubuntu-latest
variables:
  BuildTools.EnvironmentUrl: "YOUR-URL"
steps:
- task: PowerPlatformToolInstaller@2
  inputs:
    DefaultVersion: true
    AddToolsToPath: true
- task: PowerPlatformWhoAmi@2
  inputs:
    authenticationType: 'PowerPlatformSPN'
    PowerPlatformSPN: 'YOU-SVC-CONN-NAME'
- task: PowerShell@2
  env:
    PAC_ADO_ID_TOKEN_REQUEST_TOKEN: $(System.AccessToken)
  inputs:
    targetType: 'inline'
    script: |
      $uri = "$(System.CollectionUri)"
      $projectId = "$(System.TeamProjectId)"
      $hub = "$(System.HostType)"
      $planId = "$(System.PlanId)"
      $jobId = "$(System.JobId)"
      $serviceConnectionId = "YOUR-SVC-CONN-ID"
      $oidcApiVersion = "7.2-preview.1"
      $env:PAC_ADO_ID_TOKEN_REQUEST_URL = "$uri$projectId/_apis/distributedtask/hubs/$hub/plans/$planId/jobs/$jobId/oidctoken?serviceConnectionId=$serviceConnectionId&api-version=$oidcApiVersion"
      $environment = "$(BuildTools.EnvironmentUrl)"

      pac auth create --name devops-temp --environment $environment --azureDevOpsFederated --tenant YOUR-TENANT-ID --applicationId YOUR-APP-ID
    pwsh: true
- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: |
      pac env who
    pwsh: true
- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: |
      pac solution list
    pwsh: true

Using Service Connection with credentials and SetConnectionVariables

trigger: none
pool:
  vmImage: windows-latest
steps:
- task: PowerPlatformToolInstaller@2
  inputs:
    DefaultVersion: true
    AddToolsToPath: true
- task: PowerPlatformSetConnectionVariables@2
  name: connectionVariables
  inputs:
    authenticationType: 'PowerPlatformSPN'
    PowerPlatformSPN: 'pipelines-spn'
- task: PowerShell@2
  name: authenticatePac
  inputs:
    targetType: 'inline'
    script: |
      $clientId = "$(connectionVariables.BuildTools.ApplicationId)"
      $clientSecret = "$(connectionVariables.BuildTools.ClientSecret)"
      $tenantId = "$(connectionVariables.BuildTools.TenantId)"
      $url = "$(BuildTools.EnvironmentUrl)"
      pac auth create --name devops-temp --tenant $tenantId --applicationId $clientId --clientSecret $clientSecret --environment $url
    pwsh: true
- task: PowerShell@2
  name: pacEnvWho
  inputs:
    targetType: 'inline'
    script: |
      pac env who
    pwsh: true
- task: PowerShell@2
  name: pacSolutionList
  inputs:
    targetType: 'inline'
    script: |
      pac solution list
    pwsh: true

Imagine a world where in both the examples above, we had a task that did all the extra work, including wiring up pac auth so all you had to do was something like...

trigger: none
pool:
  vmImage: ubuntu-latest
steps:
- task: PowerPlatformToolInstaller@2
  inputs:
    DefaultVersion: true
    AddToolsToPath: true
- task: PowerPlatformInitCLI@2
  inputs:
    authenticationType: 'PowerPlatformSPN'
    PowerPlatformSPN: 'pipelines-spn'
- task: PowerShell@2
  name: pacEnvWho
  inputs:
    targetType: 'inline'
    script: |
      pac env who
    pwsh: true
- task: PowerShell@2
  name: pacSolutionList
  inputs:
    targetType: 'inline'
    script: |
      pac solution list
    pwsh: true

We could even do something like

trigger: none
pool:
  vmImage: windows-latest
steps:
- task: PowerPlatformToolInstaller@2
  inputs:
    DefaultVersion: true
    AddToolsToPath: true
- task: PowerPlatformCLI@2
  name: pacEnvWho
  inputs:
    authenticationType: 'PowerPlatformSPN'
    PowerPlatformSPN: 'pipelines-spn'
    targetType: 'inline'
    script: |
      pac env who
    pwsh: true
- task: PowerPlatformCLI@2
  name: pacSolutionList
  inputs:
    authenticationType: 'PowerPlatformSPN'
    PowerPlatformSPN: 'pipelines-spn'
    targetType: 'inline'
    script: |
      pac solution list
    pwsh: true

My original goal of this discussion is less about how we can make using the CLI directly a smoother experience. We can. We have thoughts here and can explore more. What I was really intending to get feedback on is whether people would be ok with dropping to pac if we made it easier or would there still be strong opinion that people expect a task for everything pac does. I suspect there are lots of other things we can do to simplify. But this is a pattern we've seen in some other tasks. Specifically, there are examples of tasks that are just tasks to bootstrap using a specific CLI.

[devkeydet]

BTW, SetConnectionVariables already marks the variables as secrets.

[Lukis]

Drop the task wrappers, make direct invocation the most supported path so the team can focus on more pac investment, and less wrapping.

[devkeydet]

Appreciate the feedback @Lukis. You certainly identified one of our motivations seeking feedback on this topic. Spending less time on wrappers will give us more capacity to invest in other efforts the team works on.

[filcole]

I initially started using multiple wrappers for pac when ADO tasks did not meet the need, and migrated to using the ADO tasks when the functionality became available. Benefits of the tasks:

• Clearer purpose - each ADO task is clearly documented and standardised, whereas each powershell script can be different
• GUI builder (even when using yaml pipelines) in ADO
• Warm feeling that this is the "correct way" of using pac CLI because there's an ADO task for it

The escape hatch of pac pipelines is still very necessary. Perhaps monitor the telemetry of pac from ADO and only create ADO new tasks for the common scenario.

[devkeydet]

Thanks for feedback @filcole. But would you be terribly upset if we never got to creating wrappers and spend our time on other backlog items? We do monitor the telemetry and that will certainly help shape any decisions we make. But customer voice matters and often surfaces discussions that telemetry never will.

[filcole]

I personally wouldn't be terribly upset, but there are people that haven't made the switch to YAML pipelines and like the GUI/tasks in ADO.

[Joseph-Duty-VA]

My deployments tend to be many steps. We're using GitHub actions (while most of the discussion above is about ADO, I would say the same concepts still apply to GitHub actions), and what takes 6 lines in yaml can be 1 in powershell with pac cli. Multiply that by 10 or more steps, and a powershell scripted deployment can fit on one screen vs yaml means lots of scrolling. There's also a lot of redundancy/overhead to just execute what you want to with GitHub Actions (e.g. if I'm importing 2 data files, 3 solutions, and some power pages customizations, its all going into the same environment - which pac assumes - but with build tools, you specify the url, clientid, secret, tenant every time). Additionally, if I always want to perform some additional task as part of one of the build tool actions - say I want to increase my version number when doing a solution export - I have to sequence out 2 steps (the custom script to increase the version number and then the actual export).

I find the wrappers to be a nice way of simplifying things when you dont want to write a script, but the verbosity of yaml makes it impractical and error-prone for most of my practical needs.

[devkeydet]

Appreciate the feedback @Joseph-Duty-VA . The tools cater to many personas with many varied preferences and opinions. The more we hear all the nuances of different people's preferences and opinions, the more we can optimize our prioritization.

[skfd]

Incredible idea! I want to be able to use pac to query some metadata, but there is no way to do it in a wrapper. Would love love love to have the proposed - task: PowerPlatformInitCLI@2 step!

Two use cases for me:

• Query solution version to check if I even need to perform deployment or nothing has changed between envs
• Double check that Export step actually did export and not exited without error because of "Version is the same, nothing to update".