你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 Q# 项目

  • 项目

通过 Azure Quantum Development Kit的发布，可以定义 Q# 项目，这些项目是包含多个 Q# 文件的文件夹结构，这些文件可以访问彼此的资源。 项目有助于创建可重用的库和以逻辑方式组织源代码。

项目 Q# 包含一个名为 Q#qsharp.json 的清单文件，以及指定文件夹结构中的一个或多个 *.qs 文件。 当用户在 VS Code 中打开 *.qs 文件或在 Jupyter Notebook 或 Python 文件中设置 project_root 时，编译器会在周围的文件夹层次结构中搜索清单文件并确定项目的范围。 如果未找到清单文件，编译器将在单个文件模式下运行。 Q#可以手动或直接在 VS Code 中创建项目。

先决条件

Q#定义项目

Q#项目由存在qsharp.json清单文件和包含源文件) Q#的 src 文件夹 (定义，这两个文件都必须位于项目的根文件夹中。 对于 Q# 程序， Q# 编译器会自动检测项目文件夹。 对于 Python 程序和 Jupyter Notebook，必须通过qsharp.init调用指定Q#项目文件夹。 但是，项目的文件夹结构 Q# 对于所有类型的程序都保持不变。

显示项目的文件夹层次结构的 Q# 图片。

定义项目文件夹 (Q# 程序)

在 VS Code 中打开 *.qs 文件时，编译器在 Q# 文件夹结构中向上搜索 qsharp.json 清单文件。 如果找到清单文件，编译器随后向下搜索 src 目录的所有子文件夹以获取 *.qs 文件，并缓存任何操作或函数，并按照清单文件的排除规则将这些操作和函数提供给所有 *.qs 文件。

例如，给定此文件夹结构：

  • Teleportation_project
    • qsharp.json
    • src
      • RunTeleport.qs
      • TeleportOperations
        • Teleport.qs
        • PrepareState
          • PrepareState.qs

打开文件 /src/TeleportOperation/PrepareState/PrepareState.qs 时，编译器：Q#

  1. 检查 /src/TeleportOperation/PrepareState/是否有qsharp.json 文件。
  2. 检查 /src/TeleportOperationqsharp.json。
  3. 检查 /srcqsharp.json。
  4. 检查/qsharp.json。
  5. /建立为项目的根目录，并包括项目根下的所有 *.qs 文件，根据清单文件的设置。

创建清单文件

清单文件是名为 qsharp.json 的简单 .json 文件，可以选择性地包含 作者、 许可证和 .ints 字段。 最小可行清单文件是字符串 {}。 在 VS Code 中创建 Q# 项目时，会为你创建一个最少的清单文件。

{}

清单文件示例

下面是清单文件如何定义项目范围的 Q# 一些示例。

在此示例中， author 是指定的唯一字段，因此此目录中的所有 *.qs 文件及其所有子目录都包含在 Q# 项目中。

{
    "author":"Microsoft"
}

{
    "author":"Microsoft",
    "license":"MIT"
}

在项目中 Q# ，还可以使用清单文件微调 VS Code Q# Linter 设置。 默认情况下，三个 Linter 规则为：

  • needlessParens：default = allow
  • divisionByZero：default = warn
  • redundantSemicolons：default = warn

使用清单文件，可以将每个规则设置为 allow、、 warn或 error，例如

{
    "author":"Microsoft",
    "lints": [
        {
          "lint": "needlessParens",
          "level": "allow"
        },
        {
          "lint": "redundantSemicolons",
          "level": "warn"
        },
        {
          "lint": "divisionByZero",
          "level": "error"
        }
      ]
}

Q# 项目要求和属性

以下要求和配置适用于所有 Q# 项目。

  • 要包含在项目中的所有 *.qs 文件都必须位于名为 src 的文件夹下，该文件夹必须位于项目根文件夹下 Q# 。 在 VS Code 中创建 Q# 项目时， /src 会自动创建文件夹。
  • qsharp.json清单文件应与 src 文件夹位于同一级别。 Q#在 VS Code 中创建项目时，会自动创建 qsharp.json 文件。
  • 可以使用 语句访问 open 可用源文件中的操作和函数：
open MyMathLib;
...
    Multiply(x,y);

或使用 命名空间引用它们：

MyMathLib.Multiply(x,y);

仅适用于 Q# 程序

  • 项目中只有一个 Q# *.qs 文件可以 @EntryPoint() 定义 。
  • 具有 @EntryPoint() 定义的 *.qs 文件可以位于清单文件下方的任何级别。
  • 从项目中任意位置 Q# 的 *.qs 文件缓存的任何操作或函数都以 VS Code 中的预测文本形式显示。
  • 如果尚未添加所选操作或函数的命名空间，VS Code 会自动添加必要的 open 语句。

创建 Q# 项目的步骤

  1. 在 VS Code 文件资源管理器中，右键单击要用于Q#项目根文件夹的文件夹，然后选择CreateQ#项目，或打开文件夹并选择“查看>命令面板>Q#：CreateQ#项目...”。

  2. VS Code 在 文件夹中创建一个最小qsharp.json清单文件，并添加包含/srcMain.qs模板文件的文件夹。

  3. 根据需要编辑清单文件。 请参阅 清单文件示例。

  4. 在 文件夹下/src添加和组织Q#源文件。

  5. 如果要从 Python 程序或Jupyter Notebook访问Q#项目，请使用 qsharp.init设置根文件夹路径。 此示例假定程序与项目的根文件夹位于同一文件夹中 Q# ：

    qsharp.init(project_root = './Teleportation_project')

  6. 如果仅 Q# 使用 VS Code 中的文件，则在打开 Q# 文件时，编译器将搜索 qsharp.json 清单文件，确定项目根文件夹，然后扫描子文件夹中的 *.qs 文件。

注意

还可以在步骤 2 中手动创建清单文件和 /src 文件夹。

示例项目

此量子传送程序是基于前面所示的文件夹结构的项目示例 Q# ，在 VS Code 的本地模拟器上运行。 若要在 Azure Quantum 硬件或第三方模拟器上运行程序，请参阅程序和 VSCode 入门Q#，了解编译程序和连接到 Azure 工作区的步骤。

该示例使用此目录结构：

  • Teleportation_project
    • qsharp.json
    • src
      • RunTeleport.qs
      • TeleportOperations
        • Teleport.qs
        • PrepareState
          • PrepareState.qs

qsharp.json清单文件包含作者和许可证字段：

{
    "author":"Microsoft",
    "license":"MIT"
}

Q# 源文件

有一个细微的@EntryPoint()区别（ 语句），源文件对于Q#程序、Python 程序或Jupyter Notebook是相同的。

main文件 RunTeleport.qs 包含入口点，并引用 TeleportLibTeleport.qs 中的命名空间。

namespace RunTeleport {

    open TeleportLib;   // references the TeleportLib namespace in Teleport.qs

    @EntryPoint()       // @EntryPoint() not necessary for Python or Jupyter Notebook programs
    operation RunTeleportationExample() : Unit {
        use msg = Qubit();
        use target = Qubit();

        H(msg);
        Teleport(msg, target);    // calls the Teleport() operation from Teleport.qs
        H(target);

        if M(target) == Zero {
            Message("Teleported successfully!");
        
        Reset(msg);
        Reset(target);
        }
    }
}

Teleport.qs 定义 操作并从 Teleport()PrepareState.qs 调用PrepareBellPair()操作。

namespace TeleportLib {

    open PrepareBell;     // references the PrepareBell namespace in PrepareState.qs
 
    operation Teleport(msg : Qubit, target : Qubit) : Unit {
        use here = Qubit();

        PrepareBellPair(here, target);      // calls the PrepareBellPair() operation from PrepareState.qs
        Adjoint PrepareBellPair(msg, here);

        if M(msg) == One { Z(target); }
        if M(here) == One { X(target); }

        Reset(here);
    }
}

PrepareState.qs 文件包含用于创建 Bell 对的标准可重用操作。

namespace PrepareBell {    
    
    operation PrepareBellPair(left : Qubit, right : Qubit) : Unit is Adj + Ctl {
        H(left);
        CNOT(left, right);
    }
}

运行程序

选择运行程序的环境的选项卡。

若要运行此程序，请在 VS Code 中打开 RunTeleport.qs 文件，然后选择“ 运行”。