Expand your azure pipelines yaml template in a webeditor

[ChristopherHX]

Url https://christopherhx.github.io/runner.server/ExpandAzurePipelines/

TODO

• Allow creating more yaml files to allow template references
• Allow hiding right panel
• Automatically resize instead of pressing the Layout button

[bryanbcook]

@ChristopherHX,

I love the idea of the idea of the editor, as the commit-push-test cycle for Azure Pipelines is brutal. In my scenario we use a lot of templating and cross-repo templating as well, so the challenge I see with the editor is bringing all of the templates into the web interface.

The main gem in this prototype is the conversion of the Pipeline back into YAML.

var newcontent = pipeline.ToContextData().ToJToken().ToString();
var deserializer = new YamlDotNet.Serialization.DeserializerBuilder().Build();
var serializer = new YamlDotNet.Serialization.SerializerBuilder().WithEventEmitter(emitter => {
      return new MyEventEmitter(emitter);
   }).Build();
newcontent = serializer.Serialize(deserializer.Deserialize<Object>(newcontent));

Could this be introduced as Pipeline.ToYaml() as part of the SDK? Maybe an extension method?

From our conversation in #222 (comment)

My ideal scenario would be to run the yaml verification without having to spin up a web-server. For example, extracting the ObjectTemplating SDK capabilities into a Visual Studio Code extension that can perform the template parsing...

My concerns about having to spin up the web server are twofold:

• it feels a little overkill to use an exe to launch a web server to invoke a web request to perform the 7 lines of template loading. Admittedly, there's a lot going on in the server for resolving repositories, variables, secrets, etc. Though I'm not convinced those aspects are necessary to expand and validate the template.
• launching a web-server process requires administrative rights. Although this isn't impossible to overcome, it can be a concern for some developers without access. And if we wanted to leverage the exe from a typescript VSCode extension, calling out to this executable in admin mode could have an impact there.

Given that Runner.Client has all the command-line arguments necessary to provide variables and repositories, it might make sense to have a new command for azpipeline-preview that just does the template expansion. Thoughts?

[ChristopherHX]

Could this be introduced as Pipeline.ToYaml() as part of the SDK?

Yes this makes sense, if it is used more than in one place like for a vscode extension..

launching a web-server process requires administrative rights. Although this isn't impossible to overcome, it can be a concern for some developers without access. And if we wanted to leverage the exe from a typescript VSCode extension, calling out to this executable in admin mode could have an impact there.

My idea is to use wasm to interact with javascript vscode extension (I have a prototype in .net8.0-rc1). Works on all os/arch's, supported by vscode.

Any design mockup of what you expect from a good vscode extension?

• A command to validate the current opened template file "Validate Azure Pipeline" (Just a notification showing the progress / success / failure)
• A Validate Azure Pipeline button for "azure-pipeline" file type in the buttom toolbar / for yaml files matching some azure content / for files in the config
• A "Expand Azure Pipeline" command to open a new yaml editor with the expanded pipeline yaml, you can save or delete it
• Maybe configure azure pipelines credentials for downloading all dependent template file
  • Optionally allow local edits of them

Given that Runner.Client has all the command-line arguments necessary to provide variables and repositories, it might make sense to have a new command for azpipeline-preview that just does the template expansion

I think this can be added to the cli tool, should be pretty straightforward to add.

[bryanbcook]

Few things that I would want the extension to do:

Core:

• > Validate Azure Pipeline: a command to validate the current opened pipeline. Simple notification with either "OK" or error messages similar to how Azure Pipelines "validate" works inside the online editor. Or, if this could open a terminal window and show the output from the tool.

• > Expand Azure Pipeline: Either a command that shows the expanded template in a new tab, or maybe a toolbar button at the top of the pipeline file, similar to the built-in markdown previewer feature in VSCode that opens a tab with the evaluated content.

• Icon in the bottom toolbar that contains either a ✅ or ❌ that indicates whether there are files with errors. Clicking on the toolbar could open the terminal/logs and show the latest output?

Logging:

• As a pipeline author, I want the extension to provide trace information about the template being evaluated so that I can understand where in the process the template expansion failed...

  Sometimes, the final error message isn't enough to understand where the template expansion and parsing failed. The extension should have an output provider that contains the output from the TraceWriter. This information is especially useful when debugging multi-stage templates that contain many references to the same template.

• As a pipeline author, I want file names in the output to be clickable hyperlinks so that I can quickly navigate to referenced files instead of manually locating the file...

  I believe VSCode automatically processes URLs in the output as hyperlinks, but you can extend this using a DefinitionProvider.

Error Highlighting:

• As a pipeline author, I want error messages that refer to a file + line position to be highlighted with a tooltip that includes the error message so that I can quickly identify the files that have issues...

  The markdownlint extension has some relevant Diagnostics usages that highlight errors and provide context for the error message. In this example, it's providing "code fixes", though it might be possible that these fixes are optional.

• _As a pipeline author, I want files that have issues to be marked red in the TreeView (File Explorer) so that I can easily locate impacted files without having to inspect multiple error messages.

  I believe the markdownlint extension also can mark files in the TreeView that have issues. For example, files with issues could be marked red in the TreeView.

Background Validation:

• As a pipeline author, I want any files that have been flagged with issues to be validated in the background as I make changes so that I can get visual feedback that issues have been fixed or as new issues are introduced...

  The extension could keep track of the pipelines that it sent for validation and could use a file-system watcher to inspect when files with issues have been modified as a trigger to revalidate. Any diagnostics that were captured for these files should be cleared and repopulated.

Configuration:

• Global settings for preferences - eg Background Validation
• Ability to specify known folder locations for repositories
• Ability to set common parameters like $(System.CollectionUri), $(System.TeamProject), $(Build.BuildId), $(Build.SourceBranch)
• Ability to specify different sets of static variables. For example, variables for a pull-request or manual-ci. ($(Build.BuildReason), $(Build.PullRequest.SourceBranch), etc)

Other:

• Prompt for parameters if they do not have default values.

[ChristopherHX]

• Ability to specify different sets of static variables. For example, variables for a pull-request or manual-ci. ($(Build.BuildReason), $(Build.PullRequest.SourceBranch), etc)

Prompt with multiple choise on press validate, if you added multiple profiles?

Having a lot of file related configuration might fit better as Launch / Debug config.

• Ability to specify known folder locations for repositories

Part of #241

Maybe configure azure pipelines credentials for downloading all dependent template file

I don't see the point of downloading the templates from git. You should assume that the developer has the source code checked out and is making edits locally. If there's a template reference to another repository, provide a configuration setting that allows them to map the folder locations for the repositories.

The Azure Repos plugin seems to allow this already via vscode exension fs api, just with a repo@ref => vscode uri mapping. The complexity doesn't need to get into the extension.

As a pipeline author, I want the extension to provide trace information about the template being evaluated so that I can understand where in the process the template expansion failed...

It also makes sense to trace the result of the ReadTemplate call, so we can see the final yaml per instantiated template before it is interpreted by the Pipeline parser

the .net browser-wasm target of .net8 allows pretty seamless integration with js code, so we need a new tracewriter and logging more.

I guess to trace ReadTemplate, we need to be able to also convert a TemplateToken back to yaml. The ToContextData interface is not applicable for that lowlevel class.

[ChristopherHX]

I'm going to enable logging use Developer: Set Log Level... to view [debug] log lines (not persistet during reopening vscode)

See #242

For example the output tab can be used to view the log

2023-10-19 20:53:15.340 [info] Updating Runtime
2023-10-19 20:53:16.214 [info] Starting extension main to keep dotnet alive
2023-10-19 20:53:16.214 [info] Runtime is now ready
2023-10-19 20:53:27.563 [info] Parsing template my.yml resolved to my.yml (self) using Schema pipeline-root
2023-10-19 20:53:27.565 [info] Begin evaluating template 'my.yml'
2023-10-19 20:53:27.565 [info] Evaluating: join(split('3,4,5', ','), '|')
2023-10-19 20:53:27.569 [info] Result: '|'
2023-10-19 20:53:27.573 [info] Evaluating: split('3,4,5', ',')
2023-10-19 20:53:27.574 [info] Expanded: split('3,4,5', ',')
2023-10-19 20:53:27.575 [info] Result: Array
2023-10-19 20:53:27.576 [info] Evaluating: x
2023-10-19 20:53:27.576 [info] Result: '3'
2023-10-19 20:53:27.576 [info] Evaluating: x
2023-10-19 20:53:27.576 [info] Result: '4'
2023-10-19 20:53:27.577 [info] Evaluating: x
2023-10-19 20:53:27.577 [info] Result: '5'
2023-10-19 20:53:27.577 [info] Finished evaluating template 'my.yml'
2023-10-19 20:53:46.442 [info] Parsing template my.yml resolved to my.yml (self) using Schema pipeline-root
2023-10-19 20:53:46.442 [debug] resources:
  repositories:
  - repository: me
    name: test
    ref: ref
    type: git
steps:
- script: test
- script: test
- script: test
- script: ${{ join(split('3,4,5', ','), '|')}}
- ${{ each x in split('3,4,5', ',')}}:
  - script: ${{ x }}

# - template: testworkflows/azpipelines/matrixjoboutputs/pipeline.yml@me
2023-10-19 20:53:46.443 [info] Begin evaluating template 'my.yml'
2023-10-19 20:53:46.443 [info] Evaluating: join(split('3,4,5', ','), '|')
2023-10-19 20:53:46.444 [debug] Evaluating join:
2023-10-19 20:53:46.444 [debug] ..Evaluating String:
2023-10-19 20:53:46.445 [debug] ..=> '|'
2023-10-19 20:53:46.446 [debug] => '|'
2023-10-19 20:53:46.446 [info] Result: '|'
2023-10-19 20:53:46.448 [info] Evaluating: split('3,4,5', ',')
2023-10-19 20:53:46.448 [debug] Evaluating split:
2023-10-19 20:53:46.449 [debug] ..Evaluating String:
2023-10-19 20:53:46.450 [debug] ..=> '3,4,5'
2023-10-19 20:53:46.450 [debug] ..Evaluating String:
2023-10-19 20:53:46.451 [debug] ..=> ','
2023-10-19 20:53:46.452 [debug] => Array
2023-10-19 20:53:46.453 [info] Expanded: split('3,4,5', ',')
2023-10-19 20:53:46.454 [info] Result: Array
2023-10-19 20:53:46.455 [info] Evaluating: x
2023-10-19 20:53:46.456 [debug] Evaluating x:
2023-10-19 20:53:46.457 [debug] => '3'
2023-10-19 20:53:46.457 [info] Result: '3'
2023-10-19 20:53:46.458 [info] Evaluating: x
2023-10-19 20:53:46.458 [debug] Evaluating x:
2023-10-19 20:53:46.459 [debug] => '4'
2023-10-19 20:53:46.461 [info] Result: '4'
2023-10-19 20:53:46.461 [info] Evaluating: x
2023-10-19 20:53:46.462 [debug] Evaluating x:
2023-10-19 20:53:46.463 [debug] => '5'
2023-10-19 20:53:46.463 [info] Result: '5'
2023-10-19 20:53:46.464 [info] Finished evaluating template 'my.yml'
2023-10-19 20:53:46.465 [debug] {
  "resources": {
    "repositories": [
      {
        "repository": "me",
        "name": "test",
        "ref": "ref",
        "type": "git"
      }
    ]
  },
  "steps": [
    {
      "script": "test"
    },
    {
      "script": "test"
    },
    {
      "script": "test"
    },
    {
      "script": "|"
    },
    {
      "script": "3"
    },
    {
      "script": "4"
    },
    {
      "script": "5"
    }
  ]
}
2023-10-19 20:53:46.480 [debug] resources:
  repositories:
  - repository: me
    name: test
    ref: ref
    type: git
stages:
- stage: 
  jobs:
  - job: 
    steps:
    - task: CmdLine@2
      inputs:
        script: test
    - task: CmdLine@2
      inputs:
        script: test
    - task: CmdLine@2
      inputs:
        script: test
    - task: CmdLine@2
      inputs:
        script: '|'
    - task: CmdLine@2
      inputs:
        script: 3
    - task: CmdLine@2
      inputs:
        script: 4
    - task: CmdLine@2
      inputs:
        script: 5

[bryanbcook]

It might be easier to set up a "project" for the vscode-extension and track these requirements outside of this discussion?

[ChristopherHX]

It might be easier to set up a "project" for the vscode-extension and track these requirements outside of this discussion?

See here https://github.com/users/ChristopherHX/projects/1

Please open issues about the items to improve you have mentioned so far, to add them in the project.

If you want I can invite you to that project board.

I think further discussions about the extension should move to #262

[ChristopherHX]

vscode extension experiment in marketplace https://marketplace.visualstudio.com/items?itemName=christopherhx.azure-pipelines-vscode-ext

type >Expand Azure Pipeline on the entrypoint. After downloading ca 24MiB (should get a notification with progress), it processes the current pipeline yml and put the result / error in a new texteditor.

If you want to use remote workflows, create a folder like owner/repo@main / repo@main same format as of the cli and put it's file inside that folder.

This extension needs a lot of work to be a good and useful extension.