Visual Studio 中的 Python 项目

Python 应用程序通常仅使用文件夹和文件定义。 随着应用程序的增长，此结构可能会变得复杂，并且可能涉及自动生成的文件、Web 应用程序的 JavaScript 等。 Visual Studio 项目可帮助你管理复杂性。 项目（文件 .pyproj ）标识与项目关联的所有源文件和内容文件。 它包含每个文件的生成信息，维护与源代码管理系统集成的信息，并帮助将应用程序组织到逻辑组件中。

项目始终在 Visual Studio 解决方案中进行管理。 解决方案可以包含可能相互引用的任意数量的项目，例如引用实现扩展模块的C++项目的 Python 项目。 使用此关系，Visual Studio 会在开始调试 Python 项目时（如有必要）自动生成C++项目。 有关详细信息，请参阅 Visual Studio 中的解决方案和项目。

Visual Studio 提供了各种 Python 项目模板，用于快速创建多种类型的应用程序结构。 可以选择一个模板，从现有文件夹树创建项目，或创建一个干净的空项目。 有关可用模板的列表，请参阅 “项目模板 ”部分中的表。

有关使用 Python 项目的提示

无需使用项目在 Visual Studio 中运行 Python 代码，但这样做有好处。 开始时，请查看以下有关使用项目和 Python 的注意事项。

• 在 Visual Studio 2019 及更高版本中，可以打开包含 Python 代码的文件夹，并在不创建 Visual Studio 项目和解决方案文件的情况下运行代码。

  在快速入门：在文件夹中打开并运行 Python 代码文章中提供了此方法的引导步骤。

• 在 Visual Studio 中运行 Python 代码不需要创建项目。 Visual Studio 的所有版本都适用于 Python 代码。

  可以自行打开 Python 文件，并立即访问自动完成、IntelliSense 和调试功能。 但是，在没有项目的情况下使用代码存在一些潜在缺点：

  • 由于代码始终使用默认的全局环境，因此如果代码适用于其他环境，则可能会看到不正确的完成或错误。
  • Visual Studio 分析打开单个文件的文件夹中的所有文件和包。 此过程可能会占用相当多的 CPU 时间。

• 可以从现有代码创建 Visual Studio 项目。 此方法在 “从现有文件创建项目 ”部分中介绍。

基本项目任务：文件、环境和启动

将项目与 Python 代码一起使用时，可以完成基本任务，包括添加文件、分配启动文件以及设置 Python 解释器环境。

开发应用程序时，通常需要向项目添加新类型的文件。 添加更多文件很容易。 右键单击项目，选择“ 添加>现有项”，然后浏览以查找要添加的文件类型。 “ 添加新>项 ”选项将打开一个对话框，其中显示了可用于创建新文件的项模板。 选项包括空的 Python 文件、Python 类、单元测试以及与 Web 应用程序相关的各种文件。 可以使用测试项目浏览模板选项，了解 Visual Studio 版本中提供的内容。 有关详细信息，请参阅 项模板 参考。

每个 Python 项目都有一个分配的启动文件，该文件以粗体显示在 解决方案资源管理器中。 启动文件在开始调试时（通过选择 F5 或 调试>启动调试）或在 交互 窗口中运行项目时运行。 可以使用键盘快捷键 Shift + Alt + F5 打开此窗口，或者通过在调试>Python Interactive 中执行项目进行选择。 若要更改启动文件，请右键单击要使用的文件，然后选择“设置为 启动项 ”（或在较旧版本的 Visual Studio 中 设置为启动文件 ）。

如果从项目中删除所选启动文件，但未选择备用文件，Visual Studio 不知道用于启动项目的 Python 文件。 在这种情况下，Visual Studio 2017 版本 15.6 及更高版本会显示错误。 早期版本要么打开运行 Python 解释器的输出窗口，要么打开输出窗口，然后立即关闭。 如果遇到上述任何行为，请检查是否已分配启动文件。

小窍门

若要使输出窗口保持打开状态，请右键单击项目并选择“ 属性”。 在对话框中，选择“调试”选项卡，然后将标志添加到-i解释器参数字段。 此参数会导致解释器在程序完成后进入交互模式。 窗口保持打开状态，直到关闭它，例如使用键盘快捷方式 Ctrl+E+Enter。

新项目始终与默认全局 Python 环境相关联。 若要将项目与其他环境（包括虚拟环境）相关联，请右键单击项目中的 Python 环境 节点。 选择 “添加环境” ，然后选择所需的环境。 还可以使用工具栏上的环境下拉列表控件来选择环境或向项目添加另一个环境。

若要更改活动环境，请在 解决方案资源管理器 中右键单击所需的环境，然后选择“ 激活环境 ”，如下图所示。 有关详细信息，请参阅 为项目选择环境。

项目模板

Visual Studio 提供了多种设置 Python 项目的方法，无论是从头开始还是从现有代码设置。 若要使用模板，请选择“ 文件>新建>项目 ”或右键单击 解决方案资源管理器 中的解决方案，然后选择“ 添加新>项目”。 在新项目对话框中，可以通过搜索 Python 或选择语言> 节点来查看特定于 Python 的模板：

Visual Studio 版本 2022 中提供了以下模板。

Template	Description
从现有 Python 代码	从文件夹结构中的现有 Python 代码创建 Visual Studio 项目。
Python 应用程序	为具有单个空源文件的新 Python 应用程序提供基本项目结构。 默认情况下，项目在默认全局环境的控制台解释器中运行。 可以更改 分配不同的环境。
Web 项目	基于各种框架的 Web 应用项目，包括 Bottle、Django 和 Flask。
后台应用程序 （IoT）	支持部署 Python 项目以在设备上作为后台服务运行。 有关详细信息，请参阅 Windows IoT 开发人员中心。
Python 扩展模块	如果在 Visual Studio 2017 或更高版本中使用 Python 工作负载安装 Python 本机开发工具 （请参阅 安装），此模板会显示在 Visual C++ 下。 该模板为C++扩展 DLL 提供核心结构，类似于 为 Python 创建C++扩展中所述的结构。

注释

由于 Python 是一种解释语言，因此 Visual Studio 中的 Python 项目不会像 C# 等其他已编译语言项目一样生成独立可执行文件。 有关详细信息，请参阅 问题和解答。

从现有文件创建项目

按照以下步骤从现有文件创建项目。

重要

以下过程不会移动或复制任何原始源文件。 如果要处理文件的副本，请先复制该文件夹，然后创建项目。

1. 启动 Visual Studio 并选择“ 文件>新建>项目”。

2. 在“ 创建新项目 ”对话框中，搜索 python，然后选择“ 从现有 Python 代码 模板”，然后选择“ 下一步”。

3. 在“配置新项目”对话框中，输入项目名称和位置，选择包含项目的解决方案，然后选择“创建”。

4. 在 “从现有 Python 代码创建新项目 ”向导中，将 文件夹路径 设置为现有代码，设置文件类型 筛选器 ，并指定项目所需的任何 搜索路径 ，然后选择“ 下一步”。 如果不知道搜索路径，请将字段留空。

   

5. 在下一页上，选择项目的 启动文件 。 Visual Studio 选择默认的全局 Python 解释器和版本。 可以使用下拉菜单更改环境。 准备就绪后，选择“下一步”。

   注释

   该对话框仅显示根文件夹中的文件。 如果所需的文件位于子文件夹中，请将启动文件留空。 可以在 解决方案资源管理器中设置启动文件，如后续步骤中所述。

   

6. 选择用于存储项目文件的位置（磁盘上的 .pyproj 文件）。 如果适用，还可以包括虚拟环境的自动检测，并为不同的 Web 框架自定义项目。 如果不确定这些选项，请将字段设置为默认值。

   

7. 选择完成。

   Visual Studio 将创建项目并在 解决方案资源管理器中打开它。 如果要将 .pyproj 文件移动到其他位置，请在 解决方案资源管理器中选择该文件，然后在工具栏上选择“ 文件>另存为 ”。 此作更新项目中的文件引用，但它不会移动任何代码文件。

8. 若要设置其他启动文件，请在 解决方案资源管理器中找到该文件，右键单击该文件，然后选择“ 设置为启动文件”。

链接的文件

链接的文件是导入项目但通常位于应用程序项目文件夹外部的文件。 这些文件以普通文件的形式显示在 解决方案资源管理器 中，并带有叠加的快捷图标：

链接的文件是使用.pyproj元素在<Compile Include="...">文件中指定的。 当使用目录结构之外的相对路径时，链接文件是隐式的。 如果文件使用 解决方案资源管理器中的路径，则链接的文件是 显式的。 以下示例明确显示了链接的文件：

<Compile Include="..\test2.py">
    <Link>MyProject\test2.py</Link>
</Compile>

链接文件在以下情况下将被忽略：

• 链接文件包含 Link 属性中指定的 Include 元数据和路径位于项目目录中。
• 链接文件复制项目层次结构中存在的文件。
• 链接文件包含 Link 元数据， Link 路径是项目层次结构外部的相对路径。
• 链接路径是从根目录开始的。

使用链接的文件

若要将现有项添加为链接，请右键单击要在其中添加该文件的项目中的文件夹，然后选择“ 添加>现有项”。 在对话框中，选择一个文件，然后选择“ 添加>为链接”。 如果没有冲突的文件，此命令将在所选文件夹中创建链接。 但是，如果存在具有相同名称的现有文件或指向该项目中已存在该文件的链接，则不会添加该链接。

如果尝试链接到项目文件夹中已存在的文件，该文件将添加为普通文件，而不是链接。 若要将文件转换为链接，请选择“ 文件>另存为” ，将文件保存到项目层次结构外部的位置。 Visual Studio 会自动将文件转换为链接。 同样，可以使用 文件>另存为 将文件保存到项目层次结构中的某个位置来转换链接。

如果在 解决方案资源管理器中移动链接文件，则会移动链接，但实际文件不受影响。 同样，删除链接会删除该链接，而不会影响文件。

无法重命名链接的文件。

References

Visual Studio 项目支持添加对项目和扩展的引用，这些引用显示在解决方案资源管理器中的“引用”节点下：

扩展引用通常指示项目之间的依赖关系，用于在设计时提供 IntelliSense 或在编译时链接。 Python 项目以类似的方式使用引用，但由于 Python 的动态性质，它们主要用于在设计时提供改进的 IntelliSense。 它们还可以用于将其他依赖项部署到Microsoft Azure。

使用扩展模块

对 .pyd 文件的引用为生成的模块启用 IntelliSense。 Visual Studio 将 .pyd 文件加载到 Python 解释器中，并反省其类型和函数。 Visual Studio 还尝试分析函数的文档字符串以提供签名帮助。

如果在磁盘上随时更新扩展模块，Visual Studio 会在后台重新分析模块。 此操作对运行时行为没有影响，但在分析完成之前，某些完成选项不可用。

可能还需要将 搜索路径 添加到包含模块的文件夹。

处理 .NET 项目

使用 IronPython 时，可以添加对 .NET 程序集的引用以启用 IntelliSense。 对于解决方案中的 .NET 项目，右键单击 Python 项目中的 “引用 ”节点，然后选择“ 添加引用”。 在对话框中，选择“ 项目 ”选项卡，然后浏览到所需的项目。 对于单独下载的 DLL，请改为选择 “浏览 ”选项卡并浏览到所需的 DLL。

由于 IronPython 中的引用在调用 clr.AddReference('<AssemblyName>') 方法后才可用，因此还需要向程序集添加适当的 clr.AddReference 方法调用。 此调用通常在代码开头添加。 例如，Visual Studio 中 IronPython Windows 窗体应用程序 （在 Visual Studio 2019 中提供）项目模板创建的代码包括文件顶部的两个调用：

import clr
clr.AddReference('System.Drawing')
clr.AddReference('System.Windows.Forms')

from System.Drawing import *
from System.Windows.Forms import *

# Other code omitted

使用 WebPI 项目

可以添加对 Web 平台安装程序（WebPI）产品条目的引用，以便部署到 Microsoft Azure 云服务，可以在其中通过 WebPI 源安装更多组件。 默认情况下，显示的源特定于 Python，包括 Django、CPython 和其他核心组件。 还可以选择自己的信息源，如下图所示。 发布到 Microsoft Azure 时，安装任务将安装所有引用的产品。

重要

Visual Studio 2017 或 Visual Studio 2019 中不提供 WebPI 项目。

相关内容

• Visual Studio 中的解决方案和项目
• 为项目选择环境
• 在 Visual Studio 中安装 Python 支持