深入解析dotnet/roslyn项目中的PowerShell脚本编写规范-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00848/article/details/148374498

深入解析dotnet/roslyn项目中的PowerShell脚本编写规范

roslyn roslyn: 是 .NET 编译器的开源项目，提供了 C# 和 Visual Basic 的编译器和代码分析器。适合开发者和研究人员使用 roslyn 理解和优化 C# 和 Visual Basic 代码。项目地址: https://gitcode.com/gh_mirrors/ro/roslyn

前言

在dotnet/roslyn项目中，PowerShell脚本作为基础设施的核心组成部分，承担着构建、测试和部署等关键任务。本文将详细介绍该项目中PowerShell脚本的编写规范和最佳实践，帮助开发者编写出更加健壮、可维护的脚本。

代码风格规范

基础格式要求

大括号位置：开括号{必须放在表达式或语句的末尾，闭括号}必须独占一行
缩进规则：统一使用2个空格进行缩进
命名规范：
- 函数名采用Pascal命名法，并遵循"动词-名词"的命名约定（如Get-Content）
- 其他标识符采用Camel命名法

命令使用规范

避免使用PowerShell别名，始终使用完整的命令名称。例如：

# 不推荐
gc file.txt

# 推荐
Get-Content file.txt

这是因为别名可能被用户环境覆盖，导致脚本行为不一致。

脚本模板结构

所有在CI环境中执行的PowerShell脚本都应遵循以下标准模板：

[CmdletBinding(PositionalBinding=$false)]
param (
    [switch]$ci = $false,
    [string]$configuration = "Debug")

Set-StrictMode -version 2.0
$ErrorActionPreference="Stop"

try { 
  . (Join-Path $PSScriptRoot "build-utils.ps1")
  $prepareMachine = $ci

  # 脚本主体内容

  ExitWithExitCode 0
}
catch {
  Write-Host $_
  Write-Host $_.Exception
  Write-Host $_.ScriptStackTrace
  ExitWithExitCode 1
}

模板关键元素解析

Set-StrictMode：强制PowerShell进入严格模式，将错误处理从"出错后继续执行"改为"出错即停止"，提高脚本可靠性
$prepareMachine：确保在CI环境中ExitWithExitCode能正确退出所有构建进程
ExitWithExitCode：遵循Arcade构建系统的标准退出方式
PositionalBinding=$false：防止调用者使用错误的参数位置调用脚本

最佳实践指南

命令执行规范

使用专门的Exec-*函数来执行外部程序或dotnet命令，这能自动检测执行失败、参数错误等情况：

# 不推荐
& msbuild /v:m /m Roslyn.sln
& dotnet build Roslyn.sln

# 推荐
Exec-Command "msbuild" "/v:m /m Roslyn.sln"
Exec-DotNet "build Roslyn.sln"

对于频繁执行dotnet命令的脚本，可以将dotnet命令存储在变量中，然后使用Exec-Command。

错误检查机制

调用PowerShell脚本后，必须使用Test-LastExitCode检查执行结果：

# 不推荐
& eng/make-bootstrap.ps1
Write-Host "Done with Bootstrap"

# 推荐
& eng/make-bootstrap.ps1
Test-LastExitCode
Write-Host "Done with Bootstrap"

null值比较规范

比较$null时，必须将$null放在操作符左侧：

# 不推荐
if ($e -ne $null) { ... }

# 推荐
if ($null -ne $e) { ... }

对于集合类型，这种写法尤为重要，因为将集合放在左侧会改变-ne和-eq的含义，变成比较集合内容而非检查null值。

PowerShell版本选择

执行环境选择

dotnet/roslyn基础设施应使用powershell而非pwsh执行脚本，因为.NET基础设施仍在使用传统PowerShell。例外情况是VS Code辅助脚本，这些脚本需要跨平台运行，因此应使用pwsh。

兼容性考虑

为支持非PowerShell环境，建议为每个.ps1脚本创建对应的.cmd文件：

@echo off
set PSMODULEPATH=
powershell -noprofile -ExecutionPolicy Unrestricted -file "%~dp0\test.ps1" %*

清除PSMODULEPATH环境变量可防止pwsh环境干扰传统PowerShell的执行。

总结

遵循这些规范可以确保dotnet/roslyn项目中的PowerShell脚本具有以下特性：

跨环境一致性
错误处理可靠性
代码可维护性
执行可预测性

这些实践不仅适用于dotnet/roslyn项目，也可作为其他项目中PowerShell脚本开发的参考标准。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考