Installing prerelease versions of Cake for Visual Studio

We released the Cake for Visual Studio extension back in September and have been thrilled with the response from the whole community. There's been plenty of activity over on the GitHub repo with new issues, bug reports, features and even PRs. Now, you can get the benefits of all the brand new features as they arrive, right in Visual Studio.

Read more...

How to debug a Cake file using Visual Studio Code

As you might already know, debugging Cake scripts using Visual Studio has been supported since the v0.12.0 release of Cake. But since the v0.16.1 release of Cake, thanks to porting Cake to .NET Core, it is now also possible to debug Cake files using Visual Studio Code.

What does this mean?

This means that while creating/modifying your Cake build script, you can use Visual Studio Code to step into the Cake file and get full debug support regardless of which operating system you are running (Windows / Linux / Mac).

How does this work?

In order to enable debugging of a Cake file using Visual Studio Code, follow these steps:

  1. Install Cake.CoreCLR NuGet package to your tools folder
  2. Install Cake Extension for Visual Studio Code
  3. Set up .NET Core debugger in Visual Studio Code. See http://aka.ms/vscclrdebugger for details
  4. Open the directory containing your Cake files in Visual Studio Code
  5. Create file .vscode/launch.json and add the following content (assuming your Cake file is build.cake)
    {
        "version": "0.2.0",
        "configurations": [
            {
                "name": ".NET Core Launch (console)",
                "type": "coreclr",
                "request": "launch",
                "program": "${workspaceRoot}/tools/Cake.CoreCLR/Cake.dll",
                "args": [
                    "${workspaceRoot}/build.cake",
                    "--debug",
                    "--verbosity=diagnostic"
                ],
                "cwd": "${workspaceRoot}",
                "stopAtEntry": true,
                "externalConsole": false
            }
        ]
    }
  6. Open your Cake file and add a breakpoint by hitting F9
  7. Hit F5 to start debugging
    Debugging

Alternative Approach

Another way to enable debugging of a Cake script is to start Cake from the commandline and then attach the debugger from within Visual Studio Code. This can be done using the following steps:

  1. Add the following configuration to the .vscode/launch.json file that you created in the previous steps
    {
        "name": ".NET Core Attach",
        "type": "coreclr",
        "request": "attach",
        "processId": "${command.pickProcess}"
    }
  2. Open your Cake file and add a breakpoint by hitting F9
  3. Select the configuration you added in the previous step
    Select config
  4. Open terminal and run
    dotnet tools/Cake.CoreCLR/Cake.dll build.cake --debug
  5. Hit F5 and select the process from the drop-down list
    Select process

Example Code

A working example can be found here

How to debug a Cake file

As you might have noticed, as part of the v0.12.0 release of Cake, thanks to a community contribution from mholo65, Cake now has debug support for Cake files.

What does this mean?

This means that while creating/modifying your Cake build script, you can use Visual Studio to step into the Cake file and get full debug support, in the same way as if you were writing something like a Windows Forms Application. This includes things like:

  • Breakpoints
  • Watches
  • Immediate Window
  • etc.

How does this work?

In order to enable debugging of a Cake file, follow these steps:

  1. Launch cake.exe with -debug flag
  2. Process will stop prior to executing script and report Attach debugger to process xxx to continue
    Pass Debug Flag
  3. Open Visual Studio, open the cake file, add a breakpoint
  4. Open Debug > Attach to Process...
    Attach To Process
  5. Attach to process with PID reported in step 2.
    Find Process Id
  6. The execution of the Cake script will then continue, and your breakpoints will be hit
    Hit Breakpoint

Alternative Approach

Another way to enable debugging of a Cake script is to directly debug the Cake Source Code, passing in the location of the Cake file that you would like to debug. This can be done using the following steps:

  1. Clone the Cake project from GitHub
  2. Open the Cake solution file src/Cake.sln
  3. Modify the project properties to specify the build.cake file that you would like to debug
    Hit Breakpoint
  4. Start debugging by pushing F5, or clicking the green play button

break preprocessor directive

In addition to directly setting breakpoints, it is also possible to place a #break pre-processor directive at the location where you want the debugger to break in your script. At runtime, this #break directive will be replaced by System.Diagnostics.Debugger.Break(); which will cause the debugger to stop at that location.

Using Break Directive

NOTE: If the debugger is not currently attached, then the #break directive is simply ignored.

Gotchas!

  1. In order to allow debugging of Cake Scripts, Visual Studio might need to run in elevated mode. If you attempt to debug a Cake script and elevation is required, you will see the following message appear.
    Elevated Permissions
  2. Sometimes VS will fail and report "Source not found", if this is the case, close the open Cake file and then from the call stack window right click on the first row and select "Go to source". This should open the source file and everything is fine.
    Source Not Found
  3. Sometimes VS will display an "opened by another project" message box. Simply click OK
    Source Not Found

Known Issues

  1. Debugging is currently not supported when using mono