dotnet run

本文适用于： ✔️ .NET 6 SDK 及更高版本

“属性”

dotnet run - 无需任何显式编译或启动命令即可运行源代码。

摘要

dotnet run [<applicationArguments>]
  [-a|--arch <ARCHITECTURE>] [--artifacts-path <ARTIFACTS_DIR>]
  [-c|--configuration <CONFIGURATION>] [--disable-build-servers]
  [-e|--environment <KEY=VALUE>] [--file <FILE_PATH>]
  [-f|--framework <FRAMEWORK>] [--force] [--interactive]
  [-lp|--launch-profile <NAME>] [--no-build] [--no-cache]
  [--no-dependencies] [--no-launch-profile] [--no-restore] [--os <OS>]
  [-p|--property:<PROPERTYNAME>=<VALUE>]
  [--project <PATH>] [-r|--runtime <RUNTIME_IDENTIFIER>]
  [--sc|--self-contained] [--tl:[auto|on|off]] [-v|--verbosity <LEVEL>]
  [[--] [application arguments]]

dotnet run -h|--help

描述

dotnet run 命令为从源代码使用一个命令运行应用程序提供了一个方便的选项。 这对从命令行中进行快速迭代开发很有帮助。 命令取决于生成代码的 dotnet build 命令。 生成的任何要求 dotnet run 也适用于此版本。

输出文件会写入到默认位置，即 bin/<configuration>/<target>。 例如，如果具有 netcoreapp2.1 应用程序并且运行 dotnet run，则输出置于 bin/Debug/netcoreapp2.1。 将根据需要覆盖文件。 临时文件将置于 obj 目录。

如果该项目指定多个框架，在不使用 dotnet run 选项指定框架时，执行 -f|--framework <FRAMEWORK> 将导致错误。

在项目上下文，而不是生成程序集中使用 dotnet run 命令。 如果尝试改为运行依赖于框架的应用程序 DLL，则必须在不使用命令的情况下使用 dotnet。 例如，若要运行 myapp.dll，请使用：

dotnet myapp.dll

有关 dotnet 驱动程序的详细信息，请参阅 .NET CLI 概述。

若要运行应用程序，dotnet run 命令需从 NuGet 缓存解析共享运行时之外的应用程序依赖项。 因为它使用缓存的依赖项，因此，不推荐在生产中使用 dotnet run 来运行应用程序。 相反，使用 命令dotnet publish，并部署已发布的输出。

隐式还原

无需运行 dotnet restore，因为它由所有需要还原的命令隐式运行，如 dotnet new、dotnet build、dotnet run、dotnet test、dotnet publish 和 dotnet pack。 若要禁用隐式还原，请使用 --no-restore 选项。

命令在某些显式还原有意义的方案中仍然很有用，例如 < Azure DevOps Services1>连续集成生成，或者在需要显式控制还原时间的生成系统中。

有关如何使用 NuGet 源的信息，请参阅 dotnet restore 文档。

以长格式传入时，此命令支持 dotnet restore 选项（例如，--source）。 不支持缩写选项，例如 -s。

工作负载清单下载

运行此命令时，它将为工作负载启动播发清单的异步后台下载。 如果此命令完成后，下载仍在运行，则将停止下载。 有关详细信息，请参阅播发清单。

启动配置

启动配置文件配置 dotnet run 如何在开发过程中启动应用。 对于 SDK 样式的项目，请将设置 Properties/launchSettings.json放入 。 Visual Basic项目改用My Project/launchSettings.json。

基于文件的应用可以使用 [ApplicationName].run.json 源文件旁边的文件。 有关文件查找顺序和示例，请参阅 基于文件的应用的启动配置文件。

启动设置文件包含顶级 profiles 对象。 中的每个 profiles 属性定义一个命名配置文件：

{
  "profiles": {
    "Local": {
      "commandName": "Project",
      "commandLineArgs": "--input sample.txt",
      "dotnetRunMessages": true,
      "environmentVariables": {
        "APP_MODE": "local"
      }
    }
  }
}

.NET SDK 启动设置分析器接受 JSON 注释和尾随逗号。

选择配置文件

用于 --launch-profile <NAME> 选择命名配置文件。 名称匹配不区分大小写。 仅区分大小写的配置文件名称不明确，并产生错误。

如果未指定名称， dotnet run 则按文件顺序 commandName 选择其支持的第一个配置文件。 用于 --no-launch-profile 跳过启动设置文件。

应用配置文件时 dotnet run ，它会在启动过程中设置为 DOTNET_LAUNCH_PROFILE 所选配置文件名称。 稍后的环境变量源可以重写该值。

支持的配置文件类型

.NET SDK 支持这些commandName值dotnet run。 这些值区分大小写。

commandName Behavior
Project 生成项目并启动项目生成的命令。
Executable 启动由 executablePath. 指定的命令。 除非指定 --no-build， dotnet run 否则仍先生成项目。

公共属性

dotnet run 识别这两种受支持的配置文件类型的这些属性：

dotnet run 在 %NAME% 支持的字符串值中扩展环境变量引用。 在 .NET 11 及更高版本中，它还使用与Visual Studio相同的令牌替换来扩展用于启动进程的值中的 MSBuild 属性引用。 它不会扩展 shell 样式 $NAME 引用。

财产 Behavior
commandLineArgs 指定启动进程的参数。 命令行上的显式应用程序参数优先。 Project对于配置文件，project提供的参数也优先。
environmentVariables 指定启动进程的环境变量。 配置文件值会替代继承的环境变量和 SDK 生成的环境变量，值 -e\|--environment 会替代配置文件值。
dotnetRunMessages 在生成项目之前dotnet run打印Building...。true 默认值为 false。 此属性不控制标识启动设置文件的消息。

用于 environmentVariables 应用具有环境变量形式的开发时运行时配置设置。 例如，配置文件可以设置 GC 设置，例如 DOTNET_gcServer。 有关可用设置、环境变量名称和优先规则，请参阅.NET用于垃圾回收的运行时配置设置和运行时配置选项。

并非每个运行时设置都有一个环境变量形式。 若要独立于其启动配置文件配置应用，请使用项目中的 MSBuild 属性或 RuntimeHostConfigurationOption 项，或使用 runtimeconfig.template.json 文件。 还可以使用 AppContext.SetSwitch 在代码中更改某些设置。 这些机制生成或修改应用的运行时配置;它们不是其他 launchSettings.json 属性。

Project 属性

dotnet run在以下Project情况下commandName识别这些附加属性：

财产 Behavior
applicationUrl 在启动过程中设置 ASPNETCORE_URLS 。 ASPNETCORE_URLS传入或传出environmentVariables-e\|--environment的值优先。
launchBrowser 告知启动工具是否打开浏览器。 dotnet run 在分析的配置文件中保留此属性，但不打开浏览器。
launchUrl 告知启动工具要打开的 URL。 dotnet run 在分析的配置文件中保留此属性，但不打开浏览器或使用 URL。

该applicationUrl行为支持 ASP.NET Core，但启动配置文件和其他常见属性适用于任何可运行的 SDK 样式.NET项目。

Executable 属性

dotnet run在以下Executable情况下commandName识别这些附加属性：

财产 Behavior
executablePath 必填。 指定要启动的进程。 SDK 扩展支持的变量引用，但它不会解析针对启动设置文件的相对值。 使用操作系统可以找到的绝对路径或命令。
workingDirectory Optional. 指定启动进程的工作目录。 SDK 扩展支持的变量引用，并根据包含启动设置文件的目录解析相对路径。 如果省略属性，工作目录默认为包含项目或基于文件的应用的目录。

Visual Studio和调试器扩展

launchSettings.json 是共享输入格式，但每个使用者决定支持哪些值以及如何解释它们。 Visual Studio、调试器和其他工具可以识别更多的commandNamedotnet run值和属性。

下表将dotnet run协定与Visual Studio中常见的.NET项目系统行为进行比较：

环境或行为 dotnet run Visual Studio
支持的配置文件类型 支持 Project 和 Executable。 支持 Project和 Executable空 commandName。 已安装的项目系统扩展可以添加其他配置文件类型。
变量扩展 展开 %NAME% 环境变量引用。 在 .NET 11 及更高版本中，还会在用于启动进程的值中扩展 MSBuild 属性引用。 在 、、commandLineArgs、workingDirectory、launchUrl环境变量值和字符串值扩展设置中executablePath扩展环境变量和 MSBuild 属性。
commandLineArgs 用于 Project 仅当项目不提供运行参数且未在命令行上传递应用程序参数时，才使用配置文件值。 将配置文件值追加到项目中的运行参数。
workingDirectory 用于 Project 忽略属性。 支持该属性。 相对路径相对于项目目录。
workingDirectory 用于 Executable 相对路径相对于包含启动设置文件的目录。 如果省略，则路径默认为项目或基于文件的应用目录。 相对路径相对于项目目录。 如果省略，则路径默认为输出目录（如果存在该目录）或项目目录。否则，路径将默认为输出目录。
相对 executablePath 将该值传递给操作系统，而无需重新设置该值。 解析具有配置文件工作目录中的路径组件的值。 对于裸露的可执行文件名称，Visual Studio检查其自己的当前目录，然后PATH。
launchBrowser 和 launchUrl 保留分析配置文件中的值，但不打开浏览器。 使值可用于启动提供程序。 例如，ASP.NET Core工具可以打开浏览器。
applicationUrl 设置 ASPNETCORE_URLS。 使值可用于已安装的启动提供程序，例如 ASP.NET Core工具。
dotnetRunMessages Building...控制消息。 不使用属性来控制Visual Studio输出。
调试器属性 忽略特定于调试器的属性。 使用诸如、sqlDebugging、jsWebView2Debugging以及remoteDebugEnabledhotReloadEnabled项目和调试器等nativeDebugging属性支持该功能时。

在 .NET 11 及更高版本中，这两个使用者都在扩展"$(ProjectDir)"。 在早期版本中，没有单个 workingDirectory 值标识这两个使用者的项目目录。 Visual Studio展开"$(ProjectDir)"，同时dotnet run将其视为文本文本，并解析包含启动设置文件的目录的相对路径。 因此，用于".."dotnet run常规Properties/launchSettings.json文件或My Project/launchSettings.json文件。 Visual Studio将相同的值解析为项目目录的父目录。

Windows 窗体和WPF应用不会添加其他dotnet run配置文件类型。 Project使用具有常见设置的配置文件，例如commandLineArgs和 environmentVariables。 在Visual Studio中，这些桌面项目类型还可以使用适用的调试器属性，例如nativeDebugging混合托管调试和本机调试或 jsWebView2Debugging WebView2。 当启动提供程序或应用程序使用浏览器和 URL 属性时，浏览器和 URL 属性才有效。

其他项目类型和Visual Studio工作负载可以安装可添加配置文件类型或解释额外属性的启动提供程序。 这些扩展不会向 dotnet run以下扩展添加支持：CLI 在默认选择期间跳过不受支持的配置文件类型，并在显式选择一个配置文件时报告错误。

有关Visual Studio支持的调试器设置和project UI，请参阅.NET C# 调试配置的Project设置。

Arguments

<applicationArguments>

传递给正在运行的应用程序的参数。

任何无法识别的参数 dotnet run 都传递给应用程序。 若要将应用程序的自变量与参数 dotnet run 分开，请使用 -- 该选项。

将参数转发到应用程序

dotnet run 转发它无法识别到应用程序的任何令牌。 转发的令牌保留其原始顺序，但 dotnet run 首先删除它理解的选项。 当识别的选项出现在无法识别的选项名称与其值之间时，删除已识别的选项可能会更改剩余令牌的含义。

例如，以下命令将应用程序要接收的令牌之间的已识别选项 --project 交错：

dotnet run --app-flag --app-name --project ConsoleApp.csproj A.txt

使用dotnet run后--project ConsoleApp.csproj，应用程序会收到--app-flag --app-name A.txt。 然后，应用程序将 A.txt 被视为与原始命令行不匹配的值 --app-name。

为了避免这种歧义，请将应用程序参数放在文本 --后面：

dotnet run --project ConsoleApp.csproj -- --app-flag --app-name A.txt

分隔 -- 符将以下每个标记标记为应用程序参数，因此 dotnet run 不会重新排序或重新解释它们。 该分隔符还会针对以后可能与以前转发到应用程序的令牌匹配的新 dotnet run 选项的脚本。

Note

相同的行为适用于dotnet build和dotnet test在Microsoft。Testing.Platform （MTP）模式，将无法识别的令牌分别转发到 MSBuild 或测试应用程序。 有关详细信息 dotnet test，请参阅 将参数转发到测试应用程序。

选项

  • --

    将参数分隔到正在运行的应用程序的参数的 dotnet run。 在此分隔符后的所有参数均传递给已运行的应用程序。

  • -a|--arch <ARCHITECTURE>

    指定目标体系结构。 这是用于设置运行时标识符 (RID) 的简写语法，其中提供的值与默认 RID 相结合。 例如，在 win-x64 计算机上，指定 --arch x86 会将 RID 设置为 win-x86。 如果使用此选项，请不要使用 -r|--runtime 选项。 自 .NET 6 预览版 7 起可用。

  • --artifacts-path <ARTIFACTS_DIR>

    执行命令中的所有生成输出文件都将位于指定路径下的子文件夹中，由项目分隔。 有关详细信息，请参阅 Artifacts 输出布局。 此选项和提供的值必须在依赖于另一dotnet个命令的输出的任何dotnet命令中显式级联，例如，使用时和 。dotnet build --no-restoredotnet publish --no-build 自 .NET 8 SDK 起可用。

  • -c|--configuration <CONFIGURATION>

    定义生成配置。 大多数项目的默认配置为 Debug，但你可以覆盖项目中的生成配置设置。

  • --disable-build-servers

    强制运行命令以忽略任何永久性生成服务器。 此选项提供一种一致的方法来禁止对生成缓存的所有使用，这会强制从头开始生成。 当缓存可能由于某种原因而损坏或不正确时，不依赖缓存的生成非常有用。 自 .NET 7 SDK 以来可用。

  • -e|--environment <KEY=VALUE>

    设置将由命令运行的进程中的指定环境变量。 指定的环境变量 不 应用于 dotnet run 进程。

    通过此选项传递的环境变量优先于环境环境变量、System.CommandLine env 指令以及 environmentVariables 所选启动配置文件中的环境变量。 有关详细信息，请参阅环境变量。

    （.NET SDK 9.0.200 中添加了此选项。

  • -f|--framework <FRAMEWORK>

    使用指定框架生成并运行应用。 框架必须在项目文件中进行指定。

  • --file <FILE_PATH>

    要运行的基于文件的应用的路径。 如果未指定路径，则当前目录用于查找并运行文件。 有关基于文件的应用的详细信息，请参阅 生成基于文件的 C# 应用。

    在 Unix 上，通过添加 shebang （#!） 指令并设置执行权限，直接使用文件名执行基于文件的应用。 有关详细信息，请参阅 Unix shebang （#!） 支持。

    .NET SDK 10.0.100 中引入。

  • --force

    强制解析所有依赖项，即使上次还原已成功，也不例外。 指定此标记等同于删除 project.assets.json 文件。

  • --interactive

    允许命令停止并等待用户输入或操作。 例如，完成身份验证。

  • -lp|--launch-profile <NAME>

    启动应用程序时要使用的启动配置文件的名称。 有关详细信息，请参阅 启动配置文件。

  • --no-build

    运行前不生成项目。 还将隐式设置 --no-restore 标记。

  • --no-cache

    跳过最新的检查，并在运行之前始终生成程序。

  • --no-dependencies

    当使用项目到项目 (P2P) 引用还原项目时，还原根项目，不还原引用。

  • --no-launch-profile

    不尝试使用 launchSettings.json 配置应用程序 。

  • --no-restore

    运行此命令时不执行隐式还原。

  • --no-self-contained

    将应用程序发布为依赖于框架的应用程序。 必须在目标计算机上安装兼容的.NET运行时才能运行应用程序。

  • --os <OS>

    指定目标操作系统 (OS)。 这是用于设置运行时标识符 (RID) 的简写语法，其中提供的值与默认 RID 相结合。 例如，在 win-x64 计算机上，指定 --os linux 会将 RID 设置为 linux-x64。 如果使用此选项，请不要使用 -r|--runtime 选项。 自 .NET 6 起可用。

  • --project <PATH>

    指定要运行的项目文件的路径（文件夹名称或完整路径）。 如果未指定，则默认为当前目录。

    从 .NET 6 SDK 开始，-p的 --project 缩写已弃用。 在有限的时间内， -p 尽管弃用警告，仍可用于 --project 。 如果为选项提供的参数不包含 =，则命令将接受 -p 的短格式 --project。 否则，命令会假设 -p 是 --property 的短格式。 -p对 --project 的灵活使用将在 .NET 7 中逐步淘汰。

  • --property:<NAME>=<VALUE>

    设置一个或多个 MSBuild 属性。 指定以分号分隔的多个属性，或通过重复该选项指定多个属性：

    --property:<NAME1>=<VALUE1>;<NAME2>=<VALUE2>
--property:<NAME1>=<VALUE1> --property:<NAME2>=<VALUE2>

    短格式 -p 可用于 --property。 如果为选项提供的参数包含 =，则接受 -p 作为 --property 的短格式。 否则，命令会假设 -p 是 --project 的短格式。

    若要将 --property 传递给应用程序而不是设置 MSBuild 属性，请在 -- 语法分隔符后面提供该选项，例如：

    dotnet run -- --property name=value

  • -r|--runtime <RUNTIME_IDENTIFIER>

    指定要为其还原包的目标运行时。 有关运行时标识符 (RID) 的列表，请参阅 RID 目录。

  • --sc|--self-contained

    使用应用程序发布.NET运行时，以便无需在目标计算机上安装运行时。

  • --tl:[auto|on|off]

    指定是否应将 终端记录器 用于生成输出。 默认值为 auto，它首先验证环境，然后再启用终端日志记录。 在启用新的记录器之前，环境检查会验证终端能否使用新式输出功能，并且不使用重定向的标准输出。 on 跳过环境检查并启用终端日志记录。 off 跳过环境检查并使用默认控制台记录器。

    终端记录器显示还原阶段，后跟生成阶段。 在每个阶段，当前生成项目显示在终端的底部。 每个正在生成的项目都会输出当前正在生成的 MSBuild 目标，以及在该目标上花费的时间。 可以搜索此信息以了解有关生成的详细信息。 项目生成完成后，将会编写一个“已完成生成”部分以捕获以下内容：

    • 生成项目的名称。
    • 目标框架（如果是多目标）。
    • 该生成的状态。
    • 该生成的主要输出（它设置了超链接）。
    • 为该项目生成的任何诊断。

    此选项从 .NET 8 开始可用。

  • -v|--verbosity <LEVEL>

    设置命令的详细级别。 允许使用的值为 q[uiet]、m[inimal]、n[ormal]、d[etailed] 和 diag[nostic]。 默认值为 minimal。 有关详细信息，请参阅 LoggerVerbosity。

  • -?|-h|--help

    打印出有关如何使用命令的说明。

环境变量

以下源将环境变量应用于启动的应用程序：

  1. 运行命令时，作系统的环境环境变量。
  2. System.CommandLine env 指令，如 [env:key=value]. 这些内容适用于整个过程 dotnet run ，而不仅仅是由 dotnet run其运行的项目。
  3. 从所选启动配置文件生成的值。 dotnet run设置DOTNET_LAUNCH_PROFILE和applicationUrlProject配置文件集中ASPNETCORE_URLS。
  4. environmentVariables 来自 所选启动配置文件（如果有）。 这些内容适用于正在由其运行 dotnet run的项目。
  5. -e|--environment CLI 选项值（.NET SDK 版本 9.0.200 中添加）。 这些内容适用于正在由其运行 dotnet run的项目。

环境按与此列表相同的顺序构造，因此 -e|--environment 该选项具有最高优先级。

示例

  • 运行当前目录中的项目：

    dotnet run

  • 在当前目录中运行基于文件的指定应用：

    dotnet run --file ConsoleApp.cs

    .NET SDK 10.0.100 中添加了基于文件的应用支持。

  • 运行指定的项目：

    dotnet run --project ./projects/proj1/proj1.csproj

  • 运行当前目录中的项目，并指定 Release 配置：

    dotnet run --property:Configuration=Release

  • 运行当前目录中的项目（在本例中，--help 参数被传递到应用程序，因为使用了空白的 -- 选项）：

    dotnet run --configuration Release -- --help

  • 在仅显示最小输出的当前目录中还原项目的依赖项和工具，然后运行项目：

    dotnet run --verbosity m

  • 使用指定的框架在当前目录中运行项目，并将参数传递给应用程序：

    dotnet run -f net6.0 -- arg1 arg2

    在以下示例中，将三个参数传递给应用程序。 使用 -一个参数传递，两个参数在以下之后 --传递：

    dotnet run -f net6.0 -arg1 -- arg2 arg3
  • 上次更新时间为