PowerShell函数内执行PnP命令返回字符串而非对象问题

问题现象 #

调用PnP系列命令时，PowerShell交互环境与脚本/自定义函数环境的执行结果存在明显差异，具体表现如下：

• 执行Get-PnPFolder时的异常
  直接在PowerShell交互命令行运行以下命令，会正常返回强类型的文件夹对象，可支撑后续所有基于该对象的操作：

  $folder = Get-PnPFolder -Url $currentFolder
  

  将完全相同的命令写入.ps1脚本或.psm1模块的自定义函数中执行时，返回值类型会变为字符串，导致后续依赖文件夹对象的命令执行失败。切换为直接调用ClientContext底层方法实现相同逻辑，问题依然存在。
• 执行Add-PnPDocumentSet时的同类异常
  对应代码如下：

  $addedItem = Add-PnPDocumentSet -List $listInfo.Name -ContentType $ctInfo.Name -Name $item.Name
  

  交互环境下执行上述代码，可正常获取到新建文档集的完整路径；但在脚本环境内执行时，对应变量无法获取到任何有效值。如果去掉变量赋值语句直接运行命令，控制台会正常输出完整路径。

问题原因 #

该问题是PnP命令的输出流污染，与PowerShell本身的返回值规则共同导致的：

1. 旧版PnP模块（尤其是已停止维护的SharePointPnPPowerShellOnline）的大量cmdlet、底层扩展方法存在设计缺陷：执行过程中除了返回设计预期的目标对象（如Folder对象、ListItem对象），还会隐式向Success输出流（PowerShell默认用于变量赋值、管道传参的标准输出流）写入字符串类型的状态日志、隐式属性值等无关内容。这也是切换ClientContext方式依然报错的核心原因——底层方法执行时同样会产生输出流污染。
2. PowerShell对输出流的处理在交互环境和脚本/函数环境存在差异：
   • 交互环境下给变量赋值时，PowerShell会优先将强类型的核心目标对象绑定到变量，零散的字符串输出会直接打印到控制台，不会进入变量
   • 在自定义函数、脚本文件中执行时，PowerShell会将所有写入Success输出流的内容（无论是否是目标对象）全部按输出顺序收集为集合，作为函数/脚本的返回值。此时直接使用返回值，要么拿到排在集合前面的字符串、要么目标对象和字符串混杂在数组中，自然会出现类型不符、值丢失的问题。
3. 「去掉赋值能看到路径，赋值后变量拿不到值」的现象，本质是路径字符串被写入了输出流，真正的文档集对象要么被其他输出内容挤到了集合的非首位，要么被错误写入了其他输出流，导致直接赋值时无法捕获到目标对象。

解决方案 #

按优先级尝试以下方案，可覆盖绝大多数同类PnP命令返回值异常场景：

• 显式过滤返回值类型，只保留目标类型对象
  赋值时通过类型过滤筛掉无关的字符串输出，只取第一个匹配的目标类型对象即可：

  # 获取文件夹时过滤出Folder类型对象
  $folder = Get-PnPFolder -Url $currentFolder | Where-Object { $_ -is [Microsoft.SharePoint.Client.Folder] } | Select-Object -First 1
  
  # 创建文档集时过滤出ListItem类型对象
  $addedItem = Add-PnPDocumentSet -List $listInfo.Name -ContentType $ctInfo.Name -Name $item.Name | Where-Object { $_ -is [Microsoft.SharePoint.Client.ListItem] } | Select-Object -First 1
  

• 重定向无关输出，避免流污染
  执行PnP命令时将非目标的字符串类输出过滤掉，只保留非字符串类型的核心返回对象：

  $folder = Get-PnPFolder -Url $currentFolder 2>&1 | Where-Object { $_ -isnot [string] }
  $addedItem = Add-PnPDocumentSet -List $listInfo.Name -ContentType $ctInfo.Name -Name $item.Name 2>&1 | Where-Object { $_ -isnot [string] }
  

• 升级到新版稳定PnP.PowerShell模块
  旧版SharePointPnPPowerShellOnline已经停止维护，绝大多数输出流bug在新版PnP.PowerShell中已经被修复，升级后大部分场景不需要额外做流过滤即可正常获取返回值。升级操作参考：

  # 卸载旧版模块
  Uninstall-Module SharePointPnPPowerShellOnline -AllVersions -Force
  # 安装新版稳定模块
  Install-Module PnP.PowerShell -Force
  

• 日常编写脚本/函数时，所有不需要对外返回的命令输出，要么赋值给$null，要么通过管道传给Out-Null，避免无关内容混入返回值。

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