C#NuGet包开发与私有仓库搭建指南

C# NuGet 包开发基础

1. 创建类库项目

在 Visual Studio 中创建一个新的类库项目，这将是我们 NuGet 包的代码载体。

打开 Visual Studio，选择“创建新项目”。
在搜索框中输入“类库”，选择“类库（.NET Standard）”模板（如果使用的是.NET 5 及以上版本，也可选择“类库（.NET）”）。
为项目命名，比如“MyNuGetLibrary”，然后点击“创建”。

2. 编写代码

在类库项目中编写你想要封装到 NuGet 包中的代码。例如，创建一个简单的数学计算类：

namespace MyNuGetLibrary
{
    public class MathHelper
    {
        public static int Add(int a, int b)
        {
            return a + b;
        }

        public static int Subtract(int a, int b)
        {
            return a - b;
        }
    }
}

这段代码定义了一个MathHelper类，包含两个静态方法Add和Subtract，用于简单的加法和减法运算。

3. 配置项目属性

右键点击项目，选择“属性”。在“应用程序”选项卡中，确保程序集名称和默认命名空间与你的项目需求一致。在“生成”选项卡中，可以设置输出路径等生成相关的配置。此外，还可以在“签名”选项卡中选择为程序集签名，如果你的 NuGet 包需要强名称验证的话。

4. 版本控制

在项目的PropertyGroup中设置版本号。打开项目的.csproj文件，添加或修改Version属性，例如：

<PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <Version>1.0.0</Version>
</PropertyGroup>

版本号遵循语义化版本控制规范MAJOR.MINOR.PATCH。MAJOR版本号在有不兼容的 API 修改时递增；MINOR版本号在有向后兼容的新功能添加时递增；PATCH版本号在有向后兼容的 bug 修复时递增。

创建 NuGet 包

1. 使用 NuGet 命令行工具

首先，需要安装 NuGet 命令行工具。可以从NuGet 官方网站下载最新版本的 NuGet.exe。将 NuGet.exe 所在路径添加到系统环境变量PATH中，以便可以在任意位置执行 NuGet 命令。生成 NuGet 包的命令如下：

nuget pack <path_to_csproj> -Properties Configuration=Release

假设你的项目路径为C:\Projects\MyNuGetLibrary\MyNuGetLibrary.csproj，则执行命令：

nuget pack C:\Projects\MyNuGetLibrary\MyNuGetLibrary.csproj -Properties Configuration=Release

该命令会在项目目录下生成一个.nupkg文件，这就是我们的 NuGet 包。例如，生成的包可能名为MyNuGetLibrary.1.0.0.nupkg，其中1.0.0是我们在项目中设置的版本号。

2. 使用 Visual Studio 内置功能

在 Visual Studio 中，也可以直接生成 NuGet 包。

右键点击项目，选择“打包”。
Visual Studio 会在后台执行类似 NuGet 命令行工具的操作，并在“输出”窗口中显示生成过程的日志。生成完成后，会提示包的保存位置，通常在项目的bin\Release目录下。

3. 包元数据

NuGet 包需要包含一些元数据，如作者、描述、项目 URL 等信息。这些信息可以在.csproj文件中配置。例如：

<PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <Version>1.0.0</Version>
    <Authors>Your Name</Authors>
    <Company>Your Company</Company>
    <Description>This is a simple NuGet package for basic math operations.</Description>
    <PackageProjectUrl>https://github.com/yourusername/MyNuGetLibrary</PackageProjectUrl>
    <PackageIconUrl>https://example.com/icon.png</PackageIconUrl>
</PropertyGroup>

Authors：包的作者名称。
Company：公司或组织名称。
Description：包的详细描述，帮助其他开发者了解包的功能。
PackageProjectUrl：项目的源代码仓库地址或官方网站。
PackageIconUrl：包的图标 URL，在 NuGet 客户端中展示。

测试 NuGet 包

1. 使用本地文件系统作为源

在测试 NuGet 包时，可以将本地文件系统作为 NuGet 源。

打开 Visual Studio，点击“工具” -> “NuGet 包管理器” -> “程序包管理器设置”。
在“NuGet 包管理器” -> “包源”中，点击“添加”。
输入一个名称，如“Local NuGet Packages”，并将源路径设置为你生成的 NuGet 包所在的目录（例如C:\Projects\MyNuGetLibrary\bin\Release）。点击“更新”保存设置。

2. 创建测试项目

创建一个新的控制台应用程序项目，用于测试我们的 NuGet 包。

在 Visual Studio 中，选择“创建新项目”，搜索“控制台应用”，选择“控制台应用（.NET）”或“控制台应用（.NET Core）”模板，根据你的目标框架选择。
为项目命名，如“MyNuGetPackageTest”，然后点击“创建”。

3. 安装本地 NuGet 包

在测试项目中安装刚刚生成的 NuGet 包。

右键点击测试项目，选择“管理 NuGet 程序包”。
在“程序包管理器”窗口中，选择“浏览”选项卡，在右上角的“包源”下拉框中选择我们刚刚添加的本地包源“Local NuGet Packages”。
搜索并安装我们的 NuGet 包，例如“MyNuGetLibrary”。

4. 编写测试代码

在测试项目的Program.cs文件中编写代码来使用 NuGet 包中的功能。例如：

using MyNuGetLibrary;

namespace MyNuGetPackageTest
{
    class Program
    {
        static void Main(string[] args)
        {
            int result1 = MathHelper.Add(5, 3);
            int result2 = MathHelper.Subtract(10, 7);
            Console.WriteLine($"Add result: {result1}");
            Console.WriteLine($"Subtract result: {result2}");
        }
    }
}

运行测试项目，确保 NuGet 包中的功能正常工作。如果输出结果为“Add result: 8”和“Subtract result: 3”，则说明 NuGet 包功能正常。

搭建私有 NuGet 仓库

1. 使用 NuGet.Server

NuGet.Server 是一个简单的基于 ASP.NET 的 NuGet 服务器实现，可以快速搭建一个私有 NuGet 仓库。

首先，创建一个新的 ASP.NET Web 应用程序项目。在 Visual Studio 中，选择“创建新项目”，搜索“ASP.NET Web 应用程序”，选择合适的模板（如“ASP.NET Core Web 应用程序”）。
在项目创建过程中，选择“空”模板，并确保选中“启用 Docker 支持”（如果需要容器化部署）。
安装NuGet.Server包。右键点击项目，选择“管理 NuGet 程序包”，搜索并安装NuGet.Server包。

2. 配置 NuGet.Server

安装完成后，需要对 NuGet.Server 进行一些配置。

在项目的appsettings.json文件中添加 NuGet.Server 的配置，例如：

{
  "NuGetServer": {
    "PackagesPath": "~/App_Data/Packages",
    "ApiKey": "your_secret_api_key"
  }
}

PackagesPath：指定 NuGet 包的存储路径，这里设置为~/App_Data/Packages，表示在项目的App_Data目录下创建Packages文件夹来存储 NuGet 包。
ApiKey：设置一个用于推送 NuGet 包的 API 密钥，需要妥善保管。

3. 注册 NuGet.Server 路由

在Startup.cs文件中，配置路由以启用 NuGet.Server 的 API。在Configure方法中添加以下代码：

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using NuGet.Server;

namespace MyNuGetServer
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddNuGetServer();
        }

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            app.UseNuGetServer();
        }
    }
}

这段代码通过services.AddNuGetServer()和app.UseNuGetServer()方法注册了 NuGet.Server 的服务和中间件。

4. 部署 NuGet.Server

可以将 NuGet.Server 部署到 IIS、Azure 等 Web 服务器上。

如果部署到 IIS，需要确保服务器安装了.NET Core 运行时（如果使用的是 ASP.NET Core 项目）。将项目发布到 IIS 站点目录，配置好应用程序池等设置。
如果部署到 Azure，可以通过 Visual Studio 的“发布”功能，选择 Azure Web 应用等目标进行部署。

5. 使用私有 NuGet 仓库

将私有 NuGet 仓库添加为 NuGet 源。

打开 Visual Studio，点击“工具” -> “NuGet 包管理器” -> “程序包管理器设置”。
在“NuGet 包管理器” -> “包源”中，点击“添加”。
输入私有 NuGet 仓库的 URL（例如http://yourserver/NuGet），并设置一个名称，如“Private NuGet Repository”。点击“更新”保存设置。
推送 NuGet 包到私有仓库。使用 NuGet 命令行工具，执行以下命令：

nuget push <path_to_nupkg> <api_key> -Source <private_repo_url>

例如：

nuget push C:\Projects\MyNuGetLibrary\bin\Release\MyNuGetLibrary.1.0.0.nupkg your_secret_api_key -Source http://yourserver/NuGet

在其他项目中安装私有 NuGet 包。在项目的“管理 NuGet 程序包”窗口中，选择“浏览”选项卡，在“包源”下拉框中选择我们添加的私有 NuGet 仓库，然后搜索并安装所需的 NuGet 包。

使用 Nexus 搭建企业级私有 NuGet 仓库

1. 安装 Nexus

Nexus 是一个流行的仓库管理系统，支持多种类型的仓库，包括 NuGet。

从Sonatype 官方网站下载 Nexus OSS（开源版本）或 Nexus Pro（专业版本）。
解压下载的文件到指定目录，例如C:\Nexus。
启动 Nexus。在命令行中进入C:\Nexus\bin目录，执行nexus.exe start（Windows 系统）或./nexus start（Linux 系统）。默认情况下，Nexus 会在http://localhost:8081启动。

2. 配置 Nexus 中的 NuGet 仓库

打开浏览器，访问http://localhost:8081，使用默认用户名admin和密码admin123登录 Nexus（首次登录会提示修改密码）。
在左侧菜单中选择“仓库” -> “仓库”。
点击“创建仓库”，选择“nuget (hosted)”类型，用于托管我们自己的 NuGet 包。
配置仓库参数：
- 名称：输入一个有意义的名称，如“private-nuget-repo”。
- 在线：确保勾选，表示该仓库可对外提供服务。
- 存储：设置 NuGet 包的存储路径，默认会在 Nexus 的数据目录下创建相应的存储位置。
- 其他设置：可以根据需要设置下载策略等其他参数。
点击“创建”完成 NuGet 仓库的创建。

3. 配置 NuGet 客户端与 Nexus 交互

生成 NuGet API 密钥。在 Nexus 中，点击右上角用户头像，选择“个人资料”，在“API 密钥”部分点击“生成密钥”，记录生成的密钥。
配置 NuGet 客户端。在NuGet.Config文件（通常位于%AppData%\NuGet\NuGet.Config）中添加以下内容：

<configuration>
  <packageSources>
    <add key="private-nuget-repo" value="http://localhost:8081/repository/private-nuget-repo/" />
  </packageSources>
  <packageSourceCredentials>
    <private-nuget-repo>
      <add key="Username" value="admin" />
      <add key="ClearTextPassword" value="your_api_key" />
    </private-nuget-repo>
  </packageSourceCredentials>
</configuration>

这里将private-nuget-repo作为包源名称，对应的 URL 是 Nexus 中创建的 NuGet 仓库地址。Username为 Nexus 的管理员用户名，ClearTextPassword为生成的 API 密钥。

4. 推送和使用 NuGet 包

推送 NuGet 包到 Nexus 仓库。使用 NuGet 命令行工具，执行以下命令：

nuget push <path_to_nupkg> <api_key> -Source http://localhost:8081/repository/private-nuget-repo/

例如：

nuget push C:\Projects\MyNuGetLibrary\bin\Release\MyNuGetLibrary.1.0.0.nupkg your_api_key -Source http://localhost:8081/repository/private-nuget-repo/

在项目中安装 Nexus 仓库中的 NuGet 包。在 Visual Studio 的“管理 NuGet 程序包”窗口中，选择“浏览”选项卡，在“包源”下拉框中选择我们添加的private-nuget-repo，然后搜索并安装所需的 NuGet 包。

管理 NuGet 包版本和依赖

1. 版本管理最佳实践

遵循语义化版本控制：如前文所述，严格按照MAJOR.MINOR.PATCH规范更新版本号。当进行不兼容的 API 修改时，递增MAJOR版本号；添加新功能且保持向后兼容时，递增MINOR版本号；修复 bug 时，递增PATCH版本号。
预发布版本：在开发过程中，可以使用预发布版本号。例如，1.0.0-alpha.1表示1.0.0版本的第一个 alpha 测试版本。预发布版本号使用点号（.）分隔，在版本号后添加预发布标识，如alpha、beta、rc（Release Candidate）等。
版本标签：在代码仓库中，可以使用版本标签来标记特定版本的代码。例如，在 Git 中，可以使用git tag -a v1.0.0 -m "Release 1.0.0"命令创建一个版本标签。

2. 处理 NuGet 包依赖

直接依赖：当你的 NuGet 包依赖其他 NuGet 包时，在项目中安装这些依赖包，NuGet 会自动将依赖信息添加到.nuspec文件（如果使用nuget pack命令生成包）或.csproj文件（如果使用 Visual Studio 打包功能）中。例如，如果你的MyNuGetLibrary项目依赖Newtonsoft.Json包，安装该包后，.csproj文件中会添加如下依赖信息：

<ItemGroup>
    <PackageReference Include="Newtonsoft.Json" Version="13.0.1" />
</ItemGroup>

传递依赖：当一个项目安装了你的 NuGet 包，它也会自动获取你的包所依赖的其他包，这就是传递依赖。例如，如果MyNuGetPackageTest项目安装了MyNuGetLibrary，并且MyNuGetLibrary依赖Newtonsoft.Json，那么MyNuGetPackageTest项目在运行时也可以使用Newtonsoft.Json的功能，无需额外安装。
依赖版本冲突：在复杂的项目中，可能会出现依赖版本冲突的情况。例如，项目 A 依赖包 X 的 1.0.0 版本，而项目 B 依赖包 X 的 2.0.0 版本。NuGet 会尝试解决这种冲突，通常会选择最高版本的依赖包。但如果存在不兼容问题，可能需要手动调整依赖版本。可以通过在.csproj文件中使用<PackageVersion>元素来强制指定依赖包的版本，例如：

<ItemGroup>
    <PackageReference Include="PackageX" Version="1.0.0" />
</ItemGroup>

或者使用 NuGet 命令行工具的-Version参数来安装特定版本的包：

nuget install PackageX -Version 1.0.0

安全与权限管理

1. NuGet 包的安全问题

代码安全：在开发 NuGet 包时，要确保代码没有安全漏洞，如 SQL 注入、跨站脚本攻击（XSS）等。对输入数据进行严格的验证和过滤，避免使用不安全的 API。
依赖安全：关注所依赖的 NuGet 包的安全性。定期更新依赖包，以获取安全补丁。可以使用工具如dotnet list package --vulnerable来检查项目中依赖包的安全漏洞。

2. 私有 NuGet 仓库的权限管理

NuGet.Server 权限管理：在 NuGet.Server 中，可以通过配置文件或代码来实现简单的权限管理。例如，可以基于 API 密钥来限制对 NuGet 仓库的访问。只有拥有正确 API 密钥的用户才能推送和下载 NuGet 包。
Nexus 权限管理：Nexus 提供了更强大的权限管理功能。可以创建不同的用户角色，如“管理员”、“开发者”、“普通用户”等，并为每个角色分配不同的权限，如创建、删除、推送、下载 NuGet 包等。在 Nexus 中，通过“安全” -> “角色”和“安全” -> “用户”菜单来进行权限和用户管理。
身份验证集成：对于企业级应用，可以将私有 NuGet 仓库与企业的身份验证系统（如 Active Directory、Azure Active Directory 等）集成。这样，用户可以使用企业的现有账号登录和访问 NuGet 仓库，提高安全性和用户体验。

通过以上详细的步骤和方法，你可以全面掌握 C# NuGet 包的开发以及私有仓库的搭建，为团队开发和项目管理提供高效、安全的包管理解决方案。无论是小型项目还是大型企业级应用，这些技术都能帮助你更好地组织和复用代码，提升开发效率。