Getting started

Install the package

dotnet package add Meziantou.Framework.DiffEngine

The examples of this documentation omit the using directives: they need using Meziantou.Framework.DiffEngine;, and using System.Diagnostics; to start a process.

Find a tool by name

DiffTools.TryFindByName looks for one tool, and returns it as a ResolvedTool when it is installed:

if (DiffTools.TryFindByName(DiffTool.VisualStudioCode, out var tool))
{
    var arguments = tool.GetArguments("received.json", "verified.json");
    Assert.Equal("--diff received.json verified.json", arguments);

    // Start the tool with Process.Start(tool.ExePath, arguments)
}

GetArguments(tempFile, targetFile) takes the file with the new content first (here received.json), and the file to compare it with, usually the one to update (verified.json). It returns the arguments in the syntax of the tool, here --diff for Visual Studio Code. Paths are quoted when they contain spaces or quotes.

ResolvedTool describes the tool that was found:

Find a tool for a file

DiffTools.TryFindByExtension looks at every tool installed on the machine and returns the first one that lists the extension in its BinaryExtensions, or else the first one that supports text. Then start the executable with the arguments:

// A tool that supports this binary extension, or else the first tool that supports text
if (!DiffTools.TryFindByExtension(Path.GetExtension(verifiedFile), out var tool))
{
    Console.WriteLine("No diff tool found");
    return;
}

// The received file holds the new content; the verified file is the one to update
var arguments = tool.GetArguments(receivedFile, verifiedFile);
using var process = Process.Start(tool.ExePath, arguments);

• The extension can be written with or without its leading dot (".png" or "png"), in any case. An empty extension, as Path.GetExtension returns for a file without one, selects a text tool.
• The tools are tried in the order of the DiffTool enumeration. To prefer a tool, look for it with TryFindByName first.
• TryFindByExtension can return a terminal tool, Vim or Neovim, which needs a console to run in. Check Tool before starting it from a process that has none, such as a test run.
• Many tools hand the files over to a running instance and exit immediately: the process ending does not mean the user closed the diff.

Next steps

• Finding tools: how the executables are found, and how to override them.