如何发布属于自己的nuget包

以前在网上查过资料关于如何发布nuget包。

我也有两个自己的包：https://www.nuget.org/packages/BlurWindow

这里再做个详细的记录，一方面是供自己查阅，另一方面也是帮助后面有需要的朋友。

 

在以前.NET Framework时期，需要我们使用nuget.exe命令行工具手动一步一步去创建nuget包清单文件(.nuspec)。

在.NET Core出来以后，我们可以直接通过Visual Studio来辅助我们完成这个过程。

 

针对.NET Core/.NET 项目

这里我们以一个.NET8的类库工程和Visual Studio 2022进行演示

1、创建一个.NET 8类库 

 

2、打开工程的属性设置，找到包设置，勾选“在构建时生成Nuget包”

 

 

3、然后填写包的相关信息

 

4、如果需要支持不同.NET的版本

我们可以打开项目的.csproj文件，

1、将TargetFramework节点修改为TargetFrameworks

2、添加需要支持的不同.NET版本，并用；分隔

例如：我想同时支持.NET Framework 4.8，那就在原来的基础上使用；分隔，并加上net48。

注意：在.NET Core项目上增加.NET Framework项目的支持，需要注意兼容性。反之亦是。

如果不了解对应版本的缩写，可以参考这个链接：https://learn.microsoft.com/zh-cn/dotnet/standard/frameworks

 

5、生成工程，打开输出目录，就可以得到nuget包的文件(nupkg)

 

针对.NET Framework项目

1、首先我们创建一个.NET Framework 4.7.2的类库工程NugetPackageTestNFX，并生成

 

2、下载nuget命令行工具

https://dist.nuget.org/win-x86-commandline/latest/nuget.exe

 

3、使用neget命令行工具执行初始化命令

这里我们直接将nuget.exe复制到项目根目录下，这样就省去了配置环境变量和切换路径的时间

执行以下指令

nuget spec

 

这样我们就得到了一个同名的.nuspec文件，.nuspec 文件是包含包元数据的 XML 清单。

 

4、完善包信息

打开NugetPackageTestNFX.nuspec可以看到如下内容

 

必须项：

id：不区分大小写的包标识符 

version：版本号

authors：作者，用；分隔

description：包描述

 

可选项：

title：包的友好标题，它可在某些 UI 显示中使用。 （nuget.org 以及 Visual Studio 中的包管理器不会显示标题）

requireLicenseAcceptance：一个布尔值，用于指定客户端是否必须提示使用者接受包许可证后才可安装包。

license：包中许可证文件的 SPDX 许可证表达式或路径，它通常显示在 nuget.org 等 UI 中。

如果要根据常用许可证（如 MIT 或 BSD-2-Clause）来对包进行许可，请使用关联的 SPDX 许可证标识符。如MIT

<license type="expression">MIT</license>

如果是指定文件，可以通过下面的形式指定

<package>
  <metadata>
     ...
    <license type="file">LICENSE.txt</license>
 </metadata>
 <files>
    ...
    <file src="LICENSE.txt" target="." />    
    ...
</files>
</package>

projectUrl：包的主页 URL，通常显示在 UI 中以及 nuget.org 中。

releaseNotes：此版本包中所作更改的说明，通常代替包说明用在 UI 中，如 Visual Studio 包管理器的“更新”选项卡。

copyright：包的版权详细信息

tags：以空格分隔的标记和关键字列表，描述包并通过搜索和筛选辅助包的可发现性。

 

5、包含程序集文件

如果遵循创建包中介绍的约定，我们可以不用在 .nuspec文件中显式指定文件列表。 nuget pack命令自动选取所需的文件。

当包安装到项目中时，NuGet 自动将程序集引用添加到包的 DLL，不包括命名为 .resources.dll 的内容，因为它们被假定为本地化的附属程序集。（因此如果需要将资源文件包含在nuget包中，避免文件名中包含.resources.dll）

如果需要显式控制包中包含的文件，

我们可以在 <package> 元素下添加 <files> 元素，并使用单独的 <file> 元素标识每个文件。

例如：

<files>
    <file src="bin\Debug\*.dll" target="lib" />
    <file src="bin\Debug\*.pdb" target="lib" />
    <file src="tools\**\*.*" exclude="**\*.log" />
</files>

每个 <file> 元素有以下属性：

属性	说明
src	文件或要包含的文件位置，受 exclude 特性指定排除规则约束。 路径是相对于 .nuspec 文件的路径，除非指定了绝对路径。 允许使用通配符 *，双通配符 ** 意味着递归文件夹搜索。
target	放置源文件的包中文件夹的相对路径，必须以 lib、content、build 或 tools 开头。 请参阅从基于约定的工作目录创建 .nuspec。
exclude	要从 src 位置排除的文件或文件模式的分号分隔列表。 允许使用通配符 *，双通配符 ** 意味着递归文件夹搜索。

 

6、支持不同的.NET版本

在前面介绍<file>元素时，介绍过src属性，我们可以通过下面的方式来指定lib文件夹下的所有文件。

  <file src="lib\**" target="lib" />

 

此时，如果我要同时支持.NET Framework4.5和.NET Core 3.1

那么就需要在然后再在lib文件夹下，创建放置不同.NET版本dll的文件夹，如下图所示

说明：对应版本的缩写，可以访问这个链接查看：https://learn.microsoft.com/zh-cn/dotnet/standard/frameworks

然后在<metadata>元素下，添加一个<dependencies>元素，并指定对应.NET的版本

<?xml version="1.0"?>
<package>
  <metadata>
        ...    
         <dependencies>
            <group targetFramework=".NETFramework4.5"></group>   
            <group targetFramework=".NETCoreApp3.1"></group>
         </dependencies>
        ...
 </metadata>
</package>

说明：对应的targetFramework名称，可以访问这个链接查看：https://learn.microsoft.com/zh-cn/nuget/reference/target-frameworks

 

7、处理依赖

我们在Visual Studio中安装包时，经常会看到如下的依赖项

 

如果我们自己的包里，也依赖了其它包，应该如何处理呢？

在<dependencies>元素添加对应的<dependency>元素即可

例如，以下行指示 PackageA 版本 1.1.0 或更高版本，以及 PackageB 版本 1.x 的依赖项。

<dependencies>
    <dependency id="PackageA" version="1.1.0" />
    <dependency id="PackageB" version="[1,2)" />
</dependencies>

 

此外，在前面指定.NET版本依赖的基础下，我们还可以单独指定对应的包依赖

例如，以下行指定，

1、依赖RouteMagic包1.1.0及以上版本（全.NET版本）

2、支持net472，当使用net472时，依赖jQuery 1.6.2和WebActivator1.4.4及以上版本

3、支持.NET Core 3.1，当使用.NET Core 3.1时，无依赖项

<dependencies>
    <group>
        <dependency id="RouteMagic" version="1.1.0" />
    </group>

    <group targetFramework=".NETFramework4.7.2">
        <dependency id="jQuery" version="1.6.2" />
        <dependency id="WebActivator" version="1.4.4" />
    </group>

    <group targetFramework="netcoreapp3.1">
    </group>
</dependencies>

 

 

关于.nuspec文件的详细介绍，可以参考下面的链接：

https://learn.microsoft.com/zh-cn/nuget/reference/nuspec

 

一个完整的.nuspec文件示例

下面是我自己发布的包使用的.nuspec文件

<?xml version="1.0"?>
<package>
  <metadata>
    <id>BlurWindow</id>
    <title>BlurWindow</title>
    <version>7.0.1</version>
    <authors>ZTI</authors>
    <projectUrl>https://github.com/TianXiaTech/BlurWindow</projectUrl>
    <icon>icon.png</icon>
    <license type="file">LICENSE.txt</license>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>
    WPF aero glass window lib
    
Features:
    - blur window
    - custom title foreground
    - controlBox visibility
    - icon visibility
    - title visibility
    - enable/disable context menu 
    - control box visibility
    - content span
    - blur background
    
What's Changed:
    - support Windows 11(version >= 22H2)
    - stability improvement
    </description>
    <releaseNotes>support Windows 11(version >= 22H2)</releaseNotes>
    <copyright>Copyright ©2024 ZTI</copyright>
    <tags>WPF .NET Aero Transparent Blur Window XAML</tags>    
    <dependencies>
        <group targetFramework=".NETFramework4.5"></group>   
        <group targetFramework=".NETCoreApp3.1"></group>
    </dependencies>
    <readme>README.md</readme>
 </metadata>
 <files>
    <file src="lib\**" target="lib" />
    <file src="icon.png" target="." /> 
    <file src="LICENSE.txt" target="." />    
    <file src="README.md" target="."/>
</files>
</package>

文件目录结构

根目录

 lib目录

它在nuget网页上显示的效果

 

在Visual Studio包管理器中显示的效果

 

通过.nuspec文件生成nuget包文件

使用nuget命令行工具，执行以下指令

nuget pack NugetPackageTestNFX.nuspec

就可以得到nuget包的文件(nupkg)

说明：可以直接输入nuget pack

 

如何发布nuget包

前面的示例中，我们演示了针对.NET Core项目和.NET Framework的项目。

此时我们已经拥有了nupkg文件，如何发布到nuget的网站呢？

 

1、打开nuget.org，注册微软账号并登录

对于已有微软账号的，可以直接登录 

 

2、上传nupkg文件

切换到upload页，并选择前面生成的nupkg文件

 

 

此时我们可以在下面看到包的详细信息，确认无误后，选择commit提交即可

 

等nuget.org索引完成，就可以在Visual Studio的包管理器中搜索到你刚刚发布的包。

 

 

参考资料：

https://learn.microsoft.com/en-us/nuget/