.NET 6 :命令行接口 (2)

总有一片天

Dotnet Build
dotnet构建（真是令人震惊！）您的项目及其所有依赖性。 这是一个直接的命令，一组选项有限。 列表3-7显示其选项。
Usage:
  dotnet [options] build [<PROJECT | SOLUTION>...]
Arguments:
  <PROJECT | SOLUTION>  要操作的项目或解决方案文件。 如果未指定文件，该命令将在当前目录中搜索一个。
Options :
  --use-current-runtime          使用当前运行时作为目标运行时。
  -f, --framework <FRAMEWORK>       要为其构建的目标框架。 还必须在项目文件中指定目标框架。
  -c, --configuration <CONFIGURATION>   用于构建项目的配置。 大多数项目的默认设置是“debug”。
  -r, --runtime <RUNTIME_IDENTIFIER>   要为其构建的目标运行时。
  --version-suffix <VERSION_SUFFIX>    设置要在构建项目时使用的 $(VersionSuffix) 属性的值。
  --no-restore               不要在构建之前恢复项目。
  --interactive               允许命令停止并等待用户输入或操作（例如，完成身份验证）。
  -v, --verbosity <LEVEL>         设置 MSBuild 详细级别。 允许的值为 q[uiet]、m[inimal]、n[ormal]、d[etailed] 和 diag[nostic]。
  --debug
  -o, --output <OUTPUT_DIR>        放置构建工件的输出目录。
  --no-incremental             不要使用增量构建。
  --no-dependencies             不要构建项目到项目的引用，只构建指定的项目。
  --nologo                  不要显示启动横幅或版权信息。
  --sc, --self-contained          与您的应用程序一起发布 .NET 运行时，这样运行时就不需要安装在目标机器上。
                        如果指定了运行时标识符，则默认值为“true”。
  --no-self-contained            将您的应用程序发布为依赖于框架的应用程序。 必须在目标计算机上安装兼容的 .NET 运行时才能运行您的应用程序。
  -a, --arch <arch>             目标架构。
  --os <os>                 目标操作系统。
  -?, -h, --help              显示命令行帮助。Dotnet build 触发与 Visual Studio 中 Build Solution 相同的工作流； 每当您在 Visual Studio 中单击构建解决方案时，它都会在后台启动 dotnet 构建。 它获取您的代码及其依赖项并将其编译为 DLL、可执行文件、符号等。

在我们构建应用程序之前，我们需要确保所有依赖项都已恢复。 这可以通过运行我们在本章前面看到的 dotnet restore 来完成。 但是，我们不必每次都在构建项目之前运行 dotnet restore； 它在执行 dotnet build 时隐式运行。 除非我们使用 dotnet build --no-restore。

Dotnet build 使用 msbuild 进行代码的实际编译。 可以通过 -l 等参数传递 MSBuild 选项以进行日志记录。 可以使用 dotnet msbuild <arguments> 直接从 dotnet 工具调用 MSBuild。 我们不会在本书中深入探讨 msbuild 选项。 dotnet build 命令与 msbuild -restore 基本相同，尽管输出看起来不同。

dotnet build 命令的两个重要参数是配置和运行时。 Configuration 指定用于此构建的配置，而 runtime 参数指定我们正在构建的 .NET 运行时版本。

.NET 中的默认配置是 Release 和 Debug。 如果我们不指定配置，默认情况下将使用 Debug 配置。 根据所选的配置，构建输出将默认出现在 bin\<config>\net6.0 中。 这些配置的不同之处在于它们为调试目的或性能优化代码的方式。 清单 3-8 展示了我们如何切换配置。
dotnet build -c release运行时使用运行时标识符 (RID) 指定。 RID 用于定义应用程序将运行的系统架构类型。 应用程序需要针对 64 位 Intel 处理器和 64 位 ARM 处理器以及不同的操作系统及其版本进行不同的编译。 RID 遵循清单 3-9 中所示的模式。
<os>.<version>-<architecture>-<additional>例如，让我们构建一个在ARM64上使用的应用程序，该应用程序是Windows可以运行并尝试运行应用程序的体系结构。 图3-6显示了运行应用程序的构建和尝试。


.NET运行时包含一个runtime.json文件。 在此文件中是一个运行时图； 它指定了哪些操作系统以及哪些版本/架构可用或后备是什么。 列表3-10显示了Runtime.json的示例条目。
"alpine.3.13": {
  "#import": [
    "alpine.3.12"
  ]
}列表3-10显示了Alpine Linux的条目，这是轻型Linux分布。 该条目指定了Alpine版本3.13，但导入3.12; 当.NET试图为针对高山Linux的项目还原Nuget软件包时，它将尝试找到针对Alpine 3.13的软件包。 如果有一个不瞄准此版本的软件包，它将寻找Alpine 3.12支持的后备。 完整的Runtime.json文件可以在github https://github.com/dotnet/runtime/blob/main/src/src/libraries/microsoft.netcore.platforms/src/src/runtime.json。
.net最常见的运行时间：
Windows Portable
win-x64
win-x86
win-arm
win-arm64
Windows 7/Windows Server 2008 R2
win7-x64
win7-x86
Windows 8.1/Windows Server 2012 R2
win81-x64
win81-x86
win81-arm
Windows 10/Windows Server 2016
win10-x64
win10-x86
win10-arm
win10-arm64
Linux Portable
linux-x64
linux-musl-x64
linux-arm
linux-arm64
Red Hat Enterprise Linux
rhel-x64
rhel.6-x64
MacOS Portable
osx-x64 (Minimum OS version is macOS 10.12 Sierra.)
macOS 10.x
osx.10.10-x64
osx.10.11-x64
osx.10.12-x64
osx.10.13-x64
osx.10.14-x64
osx.10.15-x64
macOS 11.x
osx.11.0-x64
osx.11.0-arm64
Dotnet Publish
dotnet Publish获取编译的应用程序及其依赖项，并将其发布到文件系统中，可以通过网络服务器或通过MSI或设置文件进行部署，…
Usage:
  dotnet [options] publish [<PROJECT | SOLUTION>...]
Arguments:
  <PROJECT | SOLUTION>  要操作的项目或解决方案文件。 如果未指定文件，该命令将在当前目录中搜索一个。
Options:
  --use-current-runtime           使用当前运行时作为目标运行时。
  -o, --output <OUTPUT_DIR>         放置已发布工件的输出目录。
  --manifest <MANIFEST>           包含要从发布步骤中排除的包列表的目标清单文件的路径。
  --no-build                 不要在发布前构建项目。 暗示 --no-restore。
  --sc, --self-contained          与您的应用程序一起发布 .NET 运行时，这样运行时就不需要安装在目标机器上。
                        如果指定了运行时标识符，则默认值为“true”。
  --no-self-contained           将您的应用程序发布为依赖于框架的应用程序。 必须在目标机器上安装兼容的 .NET 运行时才能运行您的应用程序。
  --nologo                 不要显示启动横幅或版权信息。
  -f, --framework <FRAMEWORK>       要发布的目标框架。 必须在项目文件中指定目标框架。
  -r, --runtime <RUNTIME_IDENTIFIER>   要为其发布的目标运行时。 这在创建独立部署时使用。
                       默认是发布依赖于框架的应用程序。
  -c, --configuration <CONFIGURATION>  要发布的配置。 大多数项目的默认设置是“调试”。
  --version-suffix <VERSION_SUFFIX>   设置要在构建项目时使用的 $(VersionSuffix) 属性的值。
  --interactive              允许命令停止并等待用户输入或操作（例如，完成身份验证）。
  --no-restore               不要在构建之前恢复项目。
  -v, --verbosity <LEVEL>         设置 MSBuild 详细级别。 允许的值为 q[uiet]、m[inimal]、n[ormal]、d[etailed] 和 diag[nostic]。
  -a, --arch <arch>            目标架构。
  --os <os>                 目标操作系统。
  -?, -h, --help              显示命令行帮助。运行DotNet发布将编译应用程序并将输出发布到特定目录。 输出将包含dlls，a *.deps.json文件列出了所有项目依赖项，a *.runtime.json文件指定应用程序的运行时以及应用程序的依赖项。 就像dotnet构建一样，此命令还隐式运行dotnet还原，就像dotnet build一样，dotnet还原也调用MSBUILD，并将参数传递。
Dotnet发布带有大量选择； 但是，其中大多数只是通往发行时调用的dotnet build命令的传递。 在谈论dotnet构建时已经讨论了这些参数，因此让我们专注于DotNet部署特定的参数。
- 框架或-F部署特定目标框架的应用程序。 请注意，目标框架绰号（TFM）需要在项目文件中指定。 如果我们指定多个框架，我们将使用一个部署命令为所有这些不同的框架获得输出。 列表3-13列出了.NET 6的TFM。
.NET 6的目标框架
net6.0
net6.0-android
net6.0-ios
net6.0-macos
net6.0-maccatalyst
net6.0-tvos
net6.0-windows
显示项目文件中如何指定目标框架。
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>
</Project>列表3-14来自命令行类型应用程序。 它将.NET 6指定为目标框架； 这不是特定于OS的TFM，因此该应用程序将在任何地方运行.NET 6受支持（Windows，Linux，MacOS，…）。 项目可以通过将目标帧标签更改为复数框架来指定多个TFM。
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFrameworks>net6.0;net45</TargetFrameworks>
  </PropertyGroup>
</Project>列出3-15个目标.NET 6和.NET 4.5。 如果要构建此项目，我们将获得两个输出文件夹，一个用于每个目标平台，其中包含为该特定平台编译的二进制文件夹。

-p：PublishingLefile = true为您提供一个文件作为输出。 该单个文件可执行文件是一个自我提取的存档，其中包含用于应用程序的所有依赖项和库。 首先，它根据应用程序的版本编号和名称提取目录中的所有内容。 该应用程序的每个新启动都会从该文件夹启动，这意味着首先需要进行提取，因此首次运行将较慢。 拥有一个文件可以更轻松地分发应用程序。 自.NET CORE 3.0以来，以单个文件的形式发布； 如果您针对较旧版本，则会出现编译器错误。 图3-7显示了发布单文件的差异。


--self-contained自包含的应用程序包括您的应用程序指定的.NET运行时，因此无需安装在目标机器上。 这消除了必须在计算机上安装多个版本的.NET运行时的风险，从而可能引起冲突。 使用您的应用程序运输.NET运行时大大简化了安装，但确实带有警告。 软件包含错误，尤其是在.NET之类的复杂软件中； 这些错误可能会在其寿命后期出现，并可能引起严重的安全问题。 像微软这样的公司通常很快解决这些安全问题并推出更新。 如果您将应用程序包装特定的.NET运行时版本，则应由您作为应用程序开发人员进行跟进这些.NET更新，并在需要时使用.NET运行时的新版本更新您的应用程序。 换句话说，您负责在应用程序中替换脆弱的.NET二进制文件。
--no-self-contained不会将.NET运行时间与应用程序一起运送。 在这种情况下，该应用程序依赖于用户计算机上安装的.NET运行时的版本。
Dotnet Run
dotnet运行运行您的应用程序。 它使用dotnet build构建应用程序并启动应用程序。
Usage:
  dotnet [options] run [[--] <additional arguments>...]]
Options:
  -c, --configuration <CONFIGURATION>  要运行的配置。 大多数项目的默认设置是“调试”。
  -f, --framework <FRAMEWORK>       要运行的目标框架。 还必须在项目文件中指定目标框架。
  -r, --runtime <RUNTIME_IDENTIFIER>   要运行的目标运行时。
  --project <project>           要运行的项目文件的路径（如果只有一个项目，则默认为当前目录）。
  -p, --property <property>        要传递给 MSBuild 的属性。
  --launch-profile <launch-profile>   启动应用程序时要使用的启动配置文件的名称（如果有）。
  --no-launch-profile           不要尝试使用 launchSettings.json 来配置应用程序。
  --no-build                不要在运行前构建项目。 暗示 --no-restore。
  --interactive               允许命令停止并等待用户输入或操作（例如，完成身份验证）。
  --no-restore               不要在构建之前恢复项目。
  --sc, --self-contained          与您的应用程序一起发布 .NET 运行时，这样运行时就不需要安装在目标机器上。
                        如果指定了运行时标识符，则默认值为“true”。
  --no-self-contained            将您的应用程序发布为依赖于框架的应用程序。 必须在目标机器上安装兼容的 .NET 运行时才能运行您的应用程序。
  -v, --verbosity <LEVEL>          设置 MSBuild 详细级别。 允许的值为 q[uiet]、m[inimal]、n[ormal]、d[etailed] 和 diag[nostic]。
  -a, --arch <arch>              目标架构。
  --os <os>                 目标操作系统。
  -?, -h, --help                显示命令行帮助。dotnet Run在bin/<config>/<tfm>文件夹中执行二进制文件。 这是放置构建命令的输出的位置。 如果是.NET 6，则可以是/BIN/< Configuration>/net6.0。 可以使用-framework参数指定其他框架。 可以使用 - 配置参数来指定配置。 列表3-17显示了dotnet Run命令的完整示例。
dotnet run --configuration Release --framework net6.0 --project .\CliDemo.csprojDotnet Test
DotNet测试用于运行项目中包含的单元测试。
Usage:
  dotnet [options] test [<PROJECT | SOLUTION>...]
Arguments:
  <PROJECT | SOLUTION>  要操作的项目或解决方案文件。 如果未指定文件，该命令将在当前目录中搜索一个。
Options:
  -s, --settings <SETTINGS_FILE>        运行测试时要使用的设置文件。
  -t, --list-tests                      列出发现的测试而不是运行测试。
  -e, --environment <NAME="VALUE">      设置环境变量的值。
                                        如果变量不存在则创建变量，如果存在则覆盖
                                        这将强制测试在隔离的进程中运行。
                                        可以多次指定此参数以提供多个变量。dotnet test命令触发dotnet构建，然后执行其找到的任何单元测试。 它支持任何支持.NET 6的测试框架，例如，MSTest，Nunit，Xunit等。该工具运行的每个测试都会打印其结果； 运行所有测试后，dotnet test命令将返回为0（所有测试成功）或1（至少一个测试失败）。 图3-8显示了dotnet测试的示例输出。


在屏幕截图中，您可以看到四个测试通过，而一项测试失败。 该示例项目中的测试是使用Nunit编写的； dotnet测试会自动拾取并使用正确的适配器。 如果它找不到正确的适配器，或者您想使用自定义适配器，则可以使用dotnet test命令的 - 测试适配器路径选项。 自定义适配器需要命名为 *.testadapter.dll，才能通过.NET CLI Tooling挑选它。 图3-6还显示，运行测试命令的第一步是验证是否需要恢复依赖项或是否需要编译项目。
修复了失败的单元测试后，我们获得了图3-9中显示的结果。


dotnet测试中其他经常使用的选项是：
- 配置与DotNet构建和DotNet部署相同，设置了要使用的配置。
- 收集启用数据收集，例如代码覆盖范围。
- 框架设置用于测试主机的框架。 这没有设置您的应用程序构建的框架； 这只是测试主机正在使用的框架版本。
在GitHub动作中使用CLI
如果您想知道，当您拥有完美，非常强大的IDE经验时，为什么会使用命令行函数，那么您来了。 .NET CLI主要用于CI/CD管道。 我们将在本书第7章中更深入地研究CI/CD的秘密。 现在只需记住，这是一个工具链，可以自动构建，测试和部署应用程序，例如，在每个源代码上推动特定分支上的每个源代码。 GitHub动作是开发人员可以利用的基于云的CI/CD工具链的一个例子。 其他例子是Azure Devops或Jenkins。 在此示例中，我们将使用GitHub操作。 在YAML文件中定义了制作GitHub操作构建和部署.NET 6应用程序所需的不同步骤。 如果您不知道YAML，则是一种数据语言，通常用于配置文件。 它具有最小的语法，基于凹痕而不是诸如JSON或XML之类的元素标签的括号。
如图3-10所示，可以从GitHub存储库的顶部菜单上获得GitHub操作。


列表3-19显示了github操作yaml文件的简单示例。
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
env:
  PROJECTFILE_PATH: './src/Net6Demo.Api/Net6Demo.Api.csproj'
  PROJECT_PATH: './src/Net6Demo.Api/'
  DOTNET_VERSION: '6.0'
  CONFIG: Release
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Setup .NET 6
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: ${{ env.DOTNET_VERSION }}
    - name: Install dependencies
      run: dotnet restore ${{ env.PROJECTFILE_PATH }}
    - name: Build
      run:  |
        dotnet build ${{ env.PROJECTFILE_PATH }} –c ${{ env.CONFIG }} –no-restore
        dotnet publish ${{ env.PROJECTFILE_PATH }} -c ${{ env.CONFIG }}让我们先浏览顶级块。 第一个块“名称”指定了此特定GitHub操作的名称。
“ ON”指定触发器。 在这种情况下，每当在主分支上发生新提交或创建针对主分支的拉请请求时，该操作将被触发。
“ env”登录变量可以在整个YAML文件中使用，以防止重复编码的值。
“工作”是魔术发生的地方； 在此示例中，我们有“构建”工作。 该作业将编译我们的应用程序并发布输出，准备部署作业以将其捡起并将其推到服务器。
“构建”有两个街区。 第一个“运行”指定了将用于构建的操作系统。 管道，例如GitHub动作或Azure DevOps，通常可以使用虚拟机器。 这些机器已安装了特定的操作系统，并具有称为代理的软件。 该代理将机器的状态报告给构建服务，并可以接受构建请求。 一旦请求进来，它将下载所有不同的任务并开始执行请求。 GitHub Actions代理获取YAML文件，下载所需的任务并执行它们。 GitHub动作提供了Windows，Linux和MacOS上的代理。 他们还提供了一个选择，可以在自己的机器上托管自己的代理商。
“步骤”包含编译应用程序所需的所有步骤。 这是一个简单的设置。 清单3-20显示了清单3-19中完整文件中提取的步骤。
steps:
- uses: actions/checkout@v2
- name: Setup .NET 6
  uses: actions/setup-dotnet@v1
  with:
    dotnet-version: ${{ env.DOTNET_VERSION }}
- name: Install dependencies
  run: dotnet restore ${{ env.PROJECTFILE_PATH }}
- name: Build
  run:  |
    dotnet build ${{ env.PROJECTFILE_PATH }} --c ${{ env.CONFIG }} --no-restore
    dotnet publish ${{ env.PROJECTFILE_PATH }} -c ${{ env.CONFIG }}操作的第一步仅具有“用途”语句。 “用途”指定要用于此步骤的特定任务。 在这种情况下，它指定“ Action/Checkout@V2”； 这意味着代理商将寻找该动作的名为Checkout和下载版本2的操作。 如我们当前的GitHub存储库的YAML文件，该特定特定的将对主分支执行git Checkout命令。
“设置.NET 6”步骤将下载操作/Setup-dotnet/@V1任务，并传递我们之前定义的环境变量。 然后，此任务将设置.NET SDK的指定版本，并将其安装在托管托管的计算机上。
最后两个步骤使用我们本章前面描述的.NET CLI命令。 首先，我们将使用DotNet还原恢复依赖项。 我喜欢与构建命令分开进行还原。 当任务失败时，我们可以在任务日志中搜索原因。 通过拆分还原和构建任务，我们限制了可能需要查看的日志大小。
在“构建”步骤中，我们在释放配置中使用dotnet build； 我们可以防止以来以来发生在上一步中的依赖性的依赖性。 最后，我们使用dotnet部署来创建我们的工件。
此特定操作只能构建应用程序并创建准备部署的工件。 工件的实际部署通常是单独定义的，并且非常依赖于要部署到的环境。
其他命令
本章描述了.NET CLI工具中最常见的基本命令。 还有更多命令，例如添加和删除。 添加和删除用于添加或删除Nuget软件包和项目参考。 图3-11显示了使用CLI添加实体框架Nuget软件包。


图3-12显示了使用命令行添加项目参考。


某些框架，扩展名等带有自己的基于命令行的工具； 例如，实体框架使用CLI工具运输，以创建迁移或更新数据库。 这些工具是使用dotnet工具命令管理的。 Dotnet工具可以安装工具，列出所有已安装的工具，更新或还原它们，运行它们并卸载它们。
总结
在本章中，我们介绍了.NET 6中包含的广泛CLI工具的最常见部分 。 了解功能是什么，以及如何找到不同的选项，这是重要的知识，不仅要了解Visual Studio的引擎盖下的情况，还可以定义构建和发布管道。