Publishing a NuGet / 发布 NuGet

下面这份指南讲的是：如何在你的 GitHub 仓库上配好一套工作流，用 PublishVLNuget 这个 GitHub Action 把你的插件发布到 nuget.org 或任何你想要的源。

本指南假定你已经有了 GitHub 和 nuget.org 的账号，并且能访问一个已有的 VL GitHub 仓库。

参考实例

这里讲的配置目前正被以下这些节点库使用：

尽管拿它们作为你自己节点库的起点。

GitHub Actions 简介

GitHub Action 是一些用途明确的小脚本，让你把仓库上的任务自动化。它们其实是所谓工作流的构件：你把若干 action 一个接一个串进自己的小脚本里，并决定这个工作流在什么条件下被触发（main 上有新提交、打了新标签等等）。

我们这个 action 会替你做这些事：

编译你的 Visual Studio 解决方案，如果你的插件有的话
如果你不想每次都把包图标提交进仓库，就从一个外部网址下载它
用 nuspec 或 csproj 文件把你的 NuGet 打包
把它发布到 nuget.org（或任何其他源）

一个 action 接受输入参数，以键值对的形式列出。在工作流脚本里，我们这个 action 大概长这样：

- name: Publish VL Nuget
    uses: vvvv/PublishVLNuget@1.0.43
    with:
    csproj: src\VL.MyLib.csproj
    nuspec: deployment\VL.MyLib.nuspec
    icon-src: https://foo.bar/icon.png
    icon-dst: ./deployment/nugeticon.png
    nuget-key: ${{ secrets.NUGET_KEY }}

这个 action 能处理的全部输入参数，见它的 GitHub 仓库（英文）。

关于 GitHub Actions 的更多信息，见官方文档（英文）。

若干预备说明

nuspec 文件

nuspec 文件装着你这个 NuGet 的元数据，比如版本、作者和依赖。它同时指定最终的包里该包含哪些文件。我们建议把它放在仓库根目录下的 deployment 文件夹里，不过放哪儿都行。

关于 nuspec 文件格式的更多信息，见 Microsoft 的文档（英文）。

依赖

在 nuspec 文件里，确认你把这个节点库／项目需要的 NuGet 都列在了 dependencies 一节下。

资源、二进制文件、帮助文档等等

在 nuspec 文件里，确认你把所有资源、dll、帮助文档等等都列在了 files 一节下。

版本

你的包版本应该遵循 semver 规范。

一个 NuGet 包可以有两种版本：正式版或预发布版。

预发布包意味着这个包还在开发中，东西可能从一个版本到下一个版本发生剧烈变化，功能也可能时不时失效或不稳定。

正式版包意味着这个包已经为生产环境做过充分的测试和打磨，不预期会有重大的破坏性改动，包内的稳定性应当是可靠的。

如果你想发布包的预发布版本，就得告诉 nuget.org 这确实是个预发布版本。做法是在包版本的末尾加上 -alpha 后缀。

`csproj` 文件

如果你的插件有 csproj 文件，它也可以代替 nuspec 文件来打包你的 NuGet。更多信息请参阅 NuGet 文档的这一节（英文）。

如果你打算这么用，只要把这个 GitHub Action 的 nuspec 输入省掉即可。

包图标

我们这个 GitHub Action 允许你用 icon-src 和 icon-dst 两个输入参数从外部来源指定包图标。这样你就不必把图标文件提交进仓库 —— 每次工作流运行时，这个文件都会被下载并放进你的包里。

请注意 icon-dst 输入参数必须指向仓库里一个已经存在的文件夹。我们建议你干脆下载到仓库根目录，像这样：

(...)
- name: Publish VL Nuget
    uses: vvvv/PublishVLNuget@1.0.43
    with:
    (...)
    icon-src: https://wwww.url.to/nugeticon.png
    icon-dst: ./nugeticon.png

用 `nuspec` 文件

在你的 action 里，把图标的目标位置设为仓库根目录：

(...)
- name: Publish VL Nuget
    uses: vvvv/PublishVLNuget@1.0.43
    with:
    (...)
    icon-src: https://wwww.url.to/nugeticon.png
    icon-dst: ./nugeticon.png

备注

工作流文件里的路径，相对的是仓库根目录。

然后在 file 一节里，你的 nuspec 文件必须从「action 会把它下载到的位置」引用它（src 属性），并把它放到任何你想要的地方（target 属性）—— 注意 target 要和 metadata 一节期望的位置对得上。

(...)
    <metadata>
        (...)
        <icon>icon\nugeticon.png</icon>
    </metadata>
    <files>
        (...)
        <file src="..\nugeticon.png" target="icon\">
    </files>
(...)

备注

nuspec 文件里的路径，相对的是这个文件自己所在的位置。

用 `csproj` 文件

你可以在 Visual Studio 里给项目配好图标。注意你得指定一个还不存在的文件路径，因为这个 action 稍后才会去下载它。这感觉可能有点怪，因为 Visual Studio 的界面给了你一个 Browse 按钮让你去挑文件 —— 直接手写路径，让它与工作流文件里的 icon-src 对得上就行。

举例来说，你的工作流文件会长这样：

(...)
- name: Publish VL Nuget
    uses: vvvv/PublishVLNuget@1.0.28
    with:
    csproj: src\Whatever\Whatever.csproj
    icon-src: https://wwww.url.to/nugeticon.png
    icon-dst: ./deployment/nugeticon.png
    nuget-key: ${{ secrets.NUGET_KEY }}

而你的 Visual Studio 配置长这样：

Visual Studio

使用这个 Action

取得 nuget.org 的 API key

下面这几步带你走完 nuget.org 的配置。开始之前，请确认你有一个可用的账号并已登录 nuget.org。

点右上角你的用户名
在弹出的菜单里点 API Keys
点 + Create
在 Key Name 下填你的仓库名或项目名 —— 当全世界的人敲 nuget install <你的包名> 时，这就是这个包的正式名字
在 Package owner 下按你的情况选对选项：如果这个包该归属于你所在的某个组织而不是你个人，现在就选那个组织
在 Glob Pattern 下填：*
点 Create

注意

这时你应该会看到刚创建的包出现在列表里，并带一条黄色警告提醒你复制你的 key。这一步至关重要，因为这是你唯一一次能复制到这个值的机会。

点包描述下面的 Copy，把它加进你仓库的 secrets。做法请参阅 GitHub 文档的这一页（英文）。记住你这个 secret 的名字，下一步创建工作流文件时会用到。我们建议就叫它 NUGET_KEY。

创建工作流文件

在你仓库的 .github/workflows 目录里新建一个 main.yml 文件。你的仓库结构应该长这样：

├── .github
│   └── workflows
│       └── main.yml
├── deployment
│   ├── VL.MyLib.nuspec
├── help
│   └── Basics
│       ├── HowTo Foo.vl
│       └── HowTo Bar.vl
├── src
│   └── MyLib
│       ├── Baz.cs
│       ├── MyLib.csproj
│       └── MyLib.sln
├── README.md
└── VL.Whatever.vl

在用 PublishVLNuget 之前，你需要先加上几个它依赖的、已有的其他 action。所以在你的 main.yml 文件里粘贴以下内容：

name: push_nuget

# on push on main
on:
  push:
    branches:
      - main
    paths-ignore:
      - README.md

jobs:
  build:
    runs-on: windows-latest
    steps:
    - name: Git Checkout
      uses: actions/checkout@master
    
    - name: Setup MSBuild.exe
      uses: microsoft/setup-msbuild@v2

    - name: Setup Nuget.exe
      uses: nuget/setup-nuget@v2.0.0

on 一节描述这个工作流在什么条件下被触发。这里我们指定：当 main 上有新提交时触发，除非改的是 README.md。

接着，在我们的 job 里加三个 action：

actions/checkout 确保用的是最新版的 git checkout action
microsoft/setup-msbuild 确保我们的 action 能用 msbuild.exe 来编译你的解决方案
- 因此，如果你的插件没有 Visual Studio 解决方案，这一条可以省掉
nuget/setup-nuget 安装 nuget.exe。我们的 action 需要它来打包并把你的插件推到 nuget.org

现在一切就绪，可以把我们的 action 加上并填好它的参数了。

- name: Publish VL Nuget
    uses: vvvv/PublishVLNuget@1.0.43
    with:
    csproj: src\VL.MyLib.csproj
    nuspec: deployment\VL.MyLib.nuspec
    icon-src: https://foo.bar/nugeticon.png
    icon-dst: ./nugeticon.png
    nuget-key: ${{ secrets.NUGET_KEY }}

备注

工作流文件里的路径，相对的是你仓库的根目录！

想知道 {{ secrets.NUGET_KEY }} 是什么？见取得 nuget.org 的 API key。

推送！

现在你可以推到 main 分支，触发一次插件的新部署了。记得在 nuspec 或 csproj 文件里把插件的版本号往上抬 —— 否则 nuget.org（或你用的任何源）会拒收你的插件。

到你仓库的 Action 一栏可以实时监看工作流的运行。工作流运行期间若有错误，会显示在这里。

工作流运行报告

给包归类

想让你在 nuget.org 上公开的包出现在包浏览器里，请确认：

你的包带一个 “VL” 标签
你把自己的包加进了精选节点库清单—— 这份清单定义了浏览器里用的分类。注意：一个 NuGet 可以出现在多个分类里！

参考实例​

GitHub Actions 简介​

若干预备说明​

nuspec 文件​

依赖​

资源、二进制文件、帮助文档等等​

版本​

csproj 文件​

包图标​

用 nuspec 文件​

用 csproj 文件​

使用这个 Action​

取得 nuget.org 的 API key​

创建工作流文件​

推送！​

给包归类​