MegaBites-AI/Windows-powershell

1---2applyTo: ".pipelines/**/*.{yml,yaml}"3---4 5# OneBranch Pipeline Condition Syntax6 7## Overview8Azure Pipelines (OneBranch) uses specific syntax for referencing variables and parameters in condition expressions. Using the wrong syntax will cause conditions to fail silently or behave unexpectedly.9 10## Variable Reference Patterns11 12### In Condition Expressions13 14**✅ Correct Pattern:**15```yaml16condition: eq(variables['VariableName'], 'value')17condition: or(eq(variables['VAR1'], 'true'), eq(variables['VAR2'], 'true'))18condition: and(succeeded(), eq(variables['Architecture'], 'fxdependent'))19```20 21**❌ Incorrect Patterns:**22```yaml23# Don't use $(VAR) string expansion in conditions24condition: eq('$(VariableName)', 'value')25 26# Don't use direct variable references27condition: eq($VariableName, 'value')28```29 30### In Script Content (pwsh, bash, etc.)31 32**✅ Correct Pattern:**33```yaml34- pwsh: |35    $value = '$(VariableName)'36    Write-Host "Value: $(VariableName)"37```38 39### In Input Fields40 41**✅ Correct Pattern:**42```yaml43inputs:44  serviceEndpoint: '$(ServiceEndpoint)'45  sbConfigPath: '$(SBConfigPath)'46```47 48## Parameter References49 50### Template Parameters (Compile-Time)51 52**✅ Correct Pattern:**53```yaml54parameters:55  - name: OfficialBuild56    type: boolean57    default: false58 59steps:60  - task: SomeTask@161    condition: eq('${{ parameters.OfficialBuild }}', 'true')62```63 64Note: Parameters use `${{ parameters.Name }}` because they're evaluated at template compile-time.65 66### Runtime Variables (Execution-Time)67 68**✅ Correct Pattern:**69```yaml70steps:71  - pwsh: |72      Write-Host "##vso[task.setvariable variable=MyVar]somevalue"73    displayName: Set Variable74 75  - task: SomeTask@176    condition: eq(variables['MyVar'], 'somevalue')77```78 79## Common Scenarios80 81### Scenario 1: Check if Variable Equals Value82 83```yaml84- task: DoSomething@185  condition: eq(variables['PREVIEW'], 'true')86```87 88### Scenario 2: Multiple Variable Conditions (OR)89 90```yaml91- task: DoSomething@192  condition: or(eq(variables['STABLE'], 'true'), eq(variables['LTS'], 'true'))93```94 95### Scenario 3: Multiple Variable Conditions (AND)96 97```yaml98- task: DoSomething@199  condition: and(succeeded(), eq(variables['Architecture'], 'fxdependent'))100```101 102### Scenario 4: Complex Conditions103 104```yaml105- task: DoSomething@1106  condition: and(107    succeededOrFailed(),108    ne(variables['UseAzDevOpsFeed'], ''),109    eq(variables['Build.SourceBranch'], 'refs/heads/master')110  )111```112 113### Scenario 5: Built-in Variables114 115```yaml116- task: CodeQL3000Init@0117  condition: eq(variables['Build.SourceBranch'], 'refs/heads/master')118 119- step: finalize120  condition: eq(variables['Agent.JobStatus'], 'SucceededWithIssues')121```122 123### Scenario 6: Parameter vs Variable124 125```yaml126parameters:127  - name: OfficialBuild128    type: boolean129 130steps:131  # Parameter condition (compile-time)132  - task: SignFiles@1133    condition: eq('${{ parameters.OfficialBuild }}', 'true')134 135  # Variable condition (runtime)136  - task: PublishArtifact@1137    condition: eq(variables['PUBLISH_ENABLED'], 'true')138```139 140## Why This Matters141 142**String Expansion `$(VAR)` in Conditions:**143- When you use `'$(VAR)'` in a condition, Azure Pipelines attempts to expand it as a string144- If the variable is undefined or empty, it becomes an empty string `''`145- The condition `eq('', 'true')` will always be false146- This makes debugging difficult because there's no error message147 148**Variables Array Syntax `variables['VAR']`:**149- This is the proper way to reference runtime variables in conditions150- Azure Pipelines correctly evaluates the variable's value151- Undefined variables are handled properly by the condition evaluator152- This is the standard pattern used throughout Azure Pipelines153 154## Reference Examples155 156Working examples can be found in:157- `.pipelines/templates/linux.yml` - Build.SourceBranch conditions158- `.pipelines/templates/windows-hosted-build.yml` - Architecture conditions159- `.pipelines/templates/compliance/apiscan.yml` - CODEQL_ENABLED conditions160- `.pipelines/templates/insert-nuget-config-azfeed.yml` - Complex AND/OR conditions161 162## Quick Reference Table163 164| Context | Syntax | Example |165|---------|--------|---------|166| Condition expression | `variables['Name']` | `condition: eq(variables['PREVIEW'], 'true')` |167| Script content | `$(Name)` | `pwsh: Write-Host "$(PREVIEW)"` |168| Task input | `$(Name)` | `inputs: path: '$(Build.SourcesDirectory)'` |169| Template parameter | `${{ parameters.Name }}` | `condition: eq('${{ parameters.Official }}', 'true')` |170 171## Troubleshooting172 173### Condition Always False174If your condition is always evaluating to false:1751. Check if you're using `'$(VAR)'` instead of `variables['VAR']`1762. Verify the variable is actually set (add a debug step to print the variable)1773. Check the variable value is exactly what you expect (case-sensitive)178 179### Variable Not Found180If you get errors about variables not being found:1811. Ensure the variable is set before the condition is evaluated1822. Check that the variable name is spelled correctly1833. Verify the variable is in scope (job vs. stage vs. pipeline level)184 185## Best Practices186 1871. **Always use `variables['Name']` in conditions** - This is the correct Azure Pipelines pattern1882. **Use `$(Name)` for string expansion** in scripts and inputs1893. **Use `${{ parameters.Name }}` for template parameters** (compile-time)1904. **Add debug steps** to verify variable values when troubleshooting conditions1915. **Follow existing patterns** in the repository - grep for `condition:` to see examples192 193## Common Mistakes194 195❌ **Mistake 1: String expansion in condition**196```yaml197condition: eq('$(PREVIEW)', 'true')  # WRONG198```199 200✅ **Fix:**201```yaml202condition: eq(variables['PREVIEW'], 'true')  # CORRECT203```204 205❌ **Mistake 2: Missing quotes around parameter**206```yaml207condition: eq(${{ parameters.Official }}, true)  # WRONG208```209 210✅ **Fix:**211```yaml212condition: eq('${{ parameters.Official }}', 'true')  # CORRECT213```214 215❌ **Mistake 3: Mixing syntax**216```yaml217condition: or(eq('$(STABLE)', 'true'), eq(variables['LTS'], 'true'))  # INCONSISTENT218```219 220✅ **Fix:**221```yaml222condition: or(eq(variables['STABLE'], 'true'), eq(variables['LTS'], 'true'))  # CORRECT223```224