Develop with Q# and .NET

Q# is built to play well with .NET languages such as C# and F#. In this guide, we'll demonstrate how to use Q# with a host program written in a .NET language.

Prerequisites

Creating a Q# library and a .NET host

The first step is to create projects for your Q# library, and for the .NET host that will call into the operations and functions defined in your Q# library.

  • Create a new Q# library
    • Go to File -> New -> Project
    • Type "Q#" in the search box
    • Select Q# Library
    • Select Next
    • Choose a name and location for your library
    • Make sure that "place project and solution in same directory" is unchecked
    • Select Create
  • Create a new C# or F# host program
    • Go to FileNewProject
    • Select "Console App (.NET Core")" for either C# or F#
    • Select Next
    • Under solution, select "add to solution"
    • Choose a name for your host program
    • Select Create

Calling into Q# from .NET

Once you have your projects set up following the above instructions, you can call into Q# from your .NET console application. The Q# compiler will create .NET classes for each Q# operation and function that allow you to run your quantum programs on a simulator.

For example, the .NET interoperability sample includes the following example of a Q# operation:

/// # Summary
/// Instantiates the oracle and runs the parameter restoration algorithm.
operation RunAlgorithm(bits : Bool[]) : Bool[] {
    Message("Hello, quantum world!");
    // construct an oracle using the input array
    let oracle = ApplyProductWithNegationFunction(bits, _, _);
    // run the algorithm on this oracle and return the result
    return ReconstructOracleParameters(Length(bits), oracle);
}

To call this operation from .NET on a quantum simulator, you can use the Run method of the RunAlgorithm .NET class generated by the Q# compiler:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using static System.Diagnostics.Debug;

using Microsoft.Quantum.Simulation.Core;
using Microsoft.Quantum.Simulation.Simulators;

namespace Microsoft.Quantum.Samples
{
    static class Program
    {
        static async Task Main(string[] args)
        {
            var bits = new[] { false, true, false };
            using var sim = new QuantumSimulator();

            Console.WriteLine($"Input: {bits.ToDelimitedString()}");

            var restored = await RunAlgorithm.Run(sim, new QArray<bool>(bits));
            Console.WriteLine($"Output: {restored.ToDelimitedString()}");

            Assert(bits.Parity() == restored.Parity());
        }

        static bool Parity(this IEnumerable<bool> bitVector) =>
            bitVector.Aggregate(
                (acc, next) => acc ^ next
            );

        static string ToDelimitedString(this IEnumerable<bool> values) =>
            String.Join(", ", values.Select(x => x.ToString()));
    }
}

Next steps

Now that you have Quantum Development Kit set up for both Q# command-line programs, and for interoperability with .NET, you can write and run your first quantum program.