如何调试Azure Functions自定义MSBuild Task？Task未按预期执行

核心问题 #

基于C# Azure Functions（进程外）项目，已集成Microsoft.Azure.Functions.Worker.Extensions.OpenApi扩展生成Swagger文档。自定义MSBuild Task期望在构建和热重载后自动下载localhost上的Swagger.json，但Task未执行，无日志输出，msbuild -bl日志中无Task执行记录；测试<MakeDir>等非自定义任务也未按预期运行，但<Message>任务正常输出。

排查与修复步骤 #

1. 修正自定义Task的Assembly路径配置 #

当前.props文件中CustomTasksAssembly指向开发时的本地Debug路径，打包成NuGet后该路径不存在，导致MSBuild无法加载Task程序集：

<!-- 原错误配置 -->
<CustomTasksFolder>$(MSBuildThisFileDirectory)..\bin\Debug\netstandard2.0</CustomTasksFolder>
<CustomTasksAssembly>$(CustomTasksFolder)\FileWatcher.dll</CustomTasksAssembly>

修复方案：
修改为NuGet包内的相对路径，确保打包后能正确找到程序集。假设Task DLL打包后位于NuGet包的build/netstandard2.0目录下：

<CustomTasksAssembly>$(MSBuildThisFileDirectory)netstandard2.0\FileWatcher.dll</CustomTasksAssembly>

同时调整Task项目的.csproj，确保DLL和依赖打包到正确位置：

<Target Name="CopyProjectReferencesToPackage" DependsOnTargets="ResolveReferences">
    <ItemGroup>
        <BuildOutputInPackage Include="@(ReferenceCopyLocalPaths)" TargetPath="build/netstandard2.0/%(ReferenceCopyLocalPaths.DestinationSubPath)" />
        <BuildOutputInPackage Include="$(OutputPath)$(AssemblyName).dll" TargetPath="build/netstandard2.0/" />
        <BuildOutputInPackage Include="$(OutputPath)$(AssemblyName).pdb" TargetPath="build/netstandard2.0/" />
    </ItemGroup>
</Target>

2. 检查Target触发条件与时机 #

（1）FunctionFiles计数为0导致Target跳过

RunningFileWatcher Target的条件是@(FunctionFiles -> Count()) != 0，如果FunctionFiles未匹配到任何文件，Target会直接跳过：

• 先查看Tester Target输出的计数：运行构建后检查@(FunctionFiles->Count())的输出值
• 修正RootFunctionsFolder的默认路径，确保匹配到项目中的函数文件，比如如果函数文件在Functions目录下：

  <RootFunctionsFolder Condition="'$(RootFunctionsFolder)' == ''">$(RootFolder)\Functions\</RootFunctionsFolder>
  

• 临时移除Condition测试：注释掉RunningFileWatcher的Condition，确认Target是否能触发

（2）调整Target的触发时机

Azure Functions进程外项目的热重载基于DotNetWatch，默认触发的是WatchRun目标而非Build，因此需要扩展Target的触发目标：

<Target Name="RunningFileWatcher" Condition="@(FunctionFiles -> Count()) != 0" BeforeTargets="Build;WatchRun">
    <!-- 任务内容 -->
</Target>

同时对CreateRootFunctionsFolder、CreateSwaggerFile等Target做相同调整，确保构建和热重载场景都能触发。

3. 验证非自定义任务的执行逻辑 #

对于<MakeDir>未执行的问题，添加日志输出确认路径和Condition：

<Target Name="CreateRootFunctionsFolder" BeforeTargets="Build;WatchRun">
    <Message Text="Checking folder: $(RootFunctionsFolder)" Importance="High" />
    <MakeDir Directories="$(RootFunctionsFolder)" Condition="!Exists('$(RootFunctionsFolder)')" />
    <Message Text="Folder created or already exists: $(RootFunctionsFolder)" Importance="High" />
</Target>

通过msbuild -v:detailed查看详细日志，确认目标是否触发、路径是否正确。

4. 修正自定义Task的日志输出逻辑 #

Task代码中使用Console.WriteLine的输出在MSBuild构建场景下可能无法显示，改为使用MSBuild日志API：

// 替换 Console.WriteLine
Log.LogMessage(MessageImportance.High, "Swagger.json has been downloaded and saved.");
Log.LogError("Error downloading swagger.json: {0}", ex.Message);

同时确保Task的Execute方法中正确抛出或记录异常，便于排查加载或执行错误。

5. 确认NuGet包的安装与导入 #

• 确保自定义Task的NuGet包已正确安装到Azure Functions项目
• 检查项目文件（.csproj）中是否自动导入了FileWatcher.props和FileWatcher.targets，若未自动导入，手动添加：

  <Import Project="..\packages\FileWatcher.1.0.0\build\FileWatcher.props" />
  <Import Project="..\packages\FileWatcher.1.0.0\build\FileWatcher.targets" />
  

验证步骤 #

1. 重新打包自定义Task的NuGet包并安装到目标项目
2. 运行msbuild -v:detailed查看构建日志，确认Target和Task是否触发
3. 启动Azure Functions项目，触发热重载（修改函数文件），检查Swagger.json是否自动下载

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