Develop with Q# and .NET

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

First we create the Q# application and .NET host, and then demonstrate how to call to Q# from the host.


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.

Follow the instructions in the tab corresponding to your development environment. If you are using an editor other than Visual Studio or VS Code, simply follow the command line steps.

  • Create a new Q# library

    dotnet new classlib -lang Q# -o quantum
  • Create a new C# or F# console project

    dotnet new console -lang C# -o host  
  • Add your Q# library as a reference from your host program

    cd host
    dotnet add reference ../quantum/quantum.csproj
  • [Optional] Create a solution for both projects

    dotnet new sln -n quantum-dotnet
    dotnet sln quantum-dotnet.sln add ./quantum/quantum.csproj
    dotnet sln quantum-dotnet.sln add ./host/host.csproj

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) =>
                (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.