Develop with Q# and .NET

The Q# programming language is built to work 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.

Prerequisites

• Install the Quantum Development Kit (QDK) for use with Q# projects.

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 prompt steps.

Visual Studio Code or command prompt

• 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

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

Visual Studio 2022

• 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 File → New → Project
  • 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:

/// 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:

C#

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()));
    }
}

F#

open System.Diagnostics
// Namespace in which quantum code resides
open Microsoft.Quantum.Samples
// Namespace in which quantum simulator resides
open Microsoft.Quantum.Simulation.Simulators
// Namespace in which QArray resides
open Microsoft.Quantum.Simulation.Core

[<EntryPoint>]
let main _ =
    printfn "Hello, classical world!"
    // Create a full-state simulator
    use simulator = new QuantumSimulator()

    let parity = Seq.reduce (<>)

    // Construct the parameter to be passed to the quantum algorithm.
    // QArray is a data type for fixed-length arrays.
    // You can modify this parameter to see how the algorithm recovers 
    let oracleBits = new QArray<bool>([| false; true; false |])
    printfn "%A" oracleBits
    
    // Run the quantum algorithm
    let restoredBits = RunAlgorithm.Run(simulator, oracleBits).Result
    printfn "%A" restoredBits

    // Process the results: in this case, verify that:
    // - the length of the return array equals the length of the input array
    Debug.Assert(restoredBits.Length = oracleBits.Length, "Return array length differs from the input array length")
    // - the parity of the returned array matches the parity of the input one
    Debug.Assert((restoredBits |> parity) = (oracleBits |> parity), "Return array should have the same parity as the input one")

    0 // return an integer exit code

Next steps

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