PowerShell脚本无法向.csproj文件添加XML节点的问题排查

编写PowerShell脚本自动化配置.NET Core Blazor应用初始化流程时，遇到无法向已有.csproj文件追加XML节点的问题，测试环境下模拟文件运行脚本完全正常，路径、其余脚本逻辑均验证无误。
需要追加的节点内容：

<Project Sdk="...">
  <!-- 原有配置省略 -->
  <Target Name="Tailwind" BeforeTargets="Build">
    <Exec Command="npm run input:build" />
  </Target>
</Project>

当前使用的脚本代码：

# edit csproj as xml to include npm build scripts
$dir = Split-Path -Path (Get-Location) -Leaf
Write-Host "Adding build directives to "$dir".csproj . . .";
$xml = [XML] (Get-Content $dir".csproj");
$target = $xml.CreateElement("Target");
$target.SetAttribute("Name", "Tailwind");
$target.SetAttribute("BeforeTargets", "Build");
$cmd = $xml.CreateElement("Exec");
$cmd.SetAttribute("Command", "npm run input:build");
$xml.DocumentElement.AppendChild($target);
$target.AppendChild($cmd);
$xml.Save($dir+".csproj");
Write-Host ". . . done.";

• 默认XML命名空间未匹配
  这是最高发的原因：正式的SDK风格.csproj根节点默认声明了MSBuild专属XML命名空间xmlns="http://schemas.microsoft.com/developer/msbuild/2003"，测试用的模拟.csproj大概率省略了这个命名空间声明。直接调用无参数的CreateElement方法创建的节点属于空命名空间，追加到带默认命名空间的根节点后，要么节点写入后带xmlns=""属性导致MSBuild无法识别，要么直接抛出节点归属错误。
  修复代码：创建元素时显式传入根节点的命名空间

  # 新增这行获取根节点命名空间
  $msbuildNs = $xml.DocumentElement.NamespaceURI
  # 修改两个CreateElement调用，传入命名空间参数
  $target = $xml.CreateElement("Target", $msbuildNs);
  $cmd = $xml.CreateElement("Exec", $msbuildNs);
  

• 文件编码不匹配导致写入异常
  Get-Content默认读取文件时会根据系统区域设置选择编码，遇到UTF-8无BOM格式的.csproj文件时可能读入乱码、隐藏字符破坏XML结构；原生XmlDocument.Save()方法默认以带BOM的UTF-8格式写入，和.csproj默认的无BOM UTF-8格式不兼容，部分场景下会导致写入失败。
  修复代码：读取和写入时显式指定编码

  # 替换原有加载XML的逻辑，直接用XmlDocument的Load方法读取，自动识别XML声明的编码
  $csprojPath = Join-Path (Get-Location) ($dir + ".csproj")
  $xml = [xml]::new()
  $xml.Load($csprojPath)
  
  # 替换原有Save逻辑，指定无BOM UTF8编码写入
  $utf8NoBom = [System.Text.UTF8Encoding]::new($false)
  $writer = [System.IO.StreamWriter]::new($csprojPath, $false, $utf8NoBom)
  $xml.Save($writer)
  $writer.Dispose()
  

• 文件被进程占用导致写入失败
  测试环境下一般不会用IDE打开模拟的csproj文件，但正式环境中如果Visual Studio、Rider、dotnet后台生成进程正在占用目标.csproj文件，Save操作会静默失败，不会抛出明显的错误提示。
  修复方式：运行脚本前关闭所有打开该项目的IDE，执行命令dotnet build-server shutdown关闭所有dotnet后台占用进程即可。

• 路径拼接存在兼容隐患
  现有脚本中$dir".csproj"的写法依赖PowerShell的隐式字符串拼接，当目录名包含空格、特殊字符时会出现路径解析错误。
  修复方式：使用Join-Path显式拼接合法路径，参考上面编码修复部分的$csprojPath写法即可。

内容的提问来源于stack exchange，提问作者hbarnett91