首页 > 编程语言 >如何使用csproj构建C#源代码组件NuGet包？

如何使用csproj构建C#源代码组件NuGet包？

时间：2024-06-19 11:22:53浏览次数：25  
标签：文件 C# csproj AllenCai BuildingBlocks cs 源代码 targets

一般我们构建传统的NuGet包，都是打包和分发dll程序集文件。

至于打包和分发C#源代码文件的做法，比较少见。

那么这种打包源代码文件的做法，有什么优点和缺点呢？

优点：

  1. 方便阅读源代码。
  2. 方便断点调试。
  3. 减少 Assembly 程序集模块加载个数。
  4. 更利于发布期间的剪裁（PublishTrimmed 选项）。
  5. 更利于混淆和保护代码（Internal 级别的源代码）。

缺点：

  1. 容易外泄原始的源代码文件。
  2. 随着引入源代码组件越多，越容易引发命名空间和类型名称重复冲突。

经验：

  1. 不建议也不推荐分发 public 级别的源代码。
  2. 尽可能严格规范命名类型名称。
  3. 向目标项目写入源代码组件 version 和 git commit sha-1，方便出问题时排查版本问题。
  4. 每次改动源代码文件时，尽可能做到向下兼容。

正文：

接下来，我们一起看看如何制作仅打包C#源代码文件，不打包dll程序集文件的C#源代码组件NuGet包。

首先是创建 AllenCai.BuildingBlocks 项目，目录结构如下：

.
├── build
└── src
    ├── AllenCai.BuildingBlocks
    │   ├── AllenCai.BuildingBlocks.csproj
    │   ├── Properties
    │   │   ├── PackageInfo.cs
    │   ├── Assets
    │   │   ├── build
    │   │   │   └── AllenCai.BuildingBlocks.targets
    │   │   └── buildMultiTargeting
    │   │       └── AllenCai.BuildingBlocks.targets
    │   ├── Collections
    │   │   ├── ArrayBuilder.cs
    │   │   ├── other...
    │   ├── Functional
    │   │   ├── Result.cs
    │   │   ├── other...
    │   ├── ObjectPooling
    │   │   ├── DictionaryPool.cs
    │   │   ├── other...
    │   ├── Text
    │   │   ├── StringBuffer.cs
    │   │   ├── other...
    │   ├── Threading
    │   │   ├── ValueTaskEx.cs
    │   │   ├── other...
    │   ├── bin
    │   │   ├── Release
    │   │   │   └── other...
    │   │   ├── Debug
    │   │   │   └── other...
    │   └── obj
    │   │   ├── other...
    │   ├── icon.png
    │   ├── other...
    ├── AllenCai.BuildingBlocks.sln
    └── Directory.Build.targets
├── .gitattributes
├── .gitignore
├── README.md

其中 Directory.Build.targets 文件，用来生成描述源代码组件包版本信息的C#源代码文件，输出文件路径为：Properties\PackageInfo.cs。

之所以输出到 Properties 目录，是因为 PackageInfo.cs 的作用其实和以前 .NET Framework 时代每个项目都会包含的 AssemblyInfo.cs 相同。

那么，为什么需要生成这个 PackageInfo.cs 文件呢？

  1. 因为不再是编译和发布dll，而是直接打包和提供源代码文件，原本被内嵌到dll程序集的版本信息是丢失的。
  2. 懒，也不希望每次手工维护写入 Version 和 git commit sha-1。

Directory.Build.targets 文件代码如下所示：

<Project>
  <!--
    将代码版本信息输出到C#文件中，使用者在项目中引入本组件源码，能够看到版本信息。
    且在使用者项目编译为程序集文件后，也能够保留本组件版本信息。
  -->
  <Target Name="GeneratePackageInfoToFile" BeforeTargets="PreBuildEvent" Condition="'$(Configuration)' == 'Release'">
    <PropertyGroup>
      <SharedPackageInfoFile>$(ProjectDir)Properties\PackageInfo.cs</SharedPackageInfoFile>
    </PropertyGroup>
​
    <ItemGroup>
      <AssemblyAttributes Include="AssemblyMetadata">
        <_Parameter1>PackageVersion</_Parameter1>
        <_Parameter2>$(Version)</_Parameter2>
      </AssemblyAttributes>
      <AssemblyAttributes Include="AssemblyMetadata">
        <_Parameter1>PackageBuildDate</_Parameter1>
        <_Parameter2>$([System.DateTime]::Now.ToString("yyyy-MM-dd HH:mm:ss"))</_Parameter2>
      </AssemblyAttributes>
      <AssemblyAttributes Include="AssemblyMetadata" Condition="'$(SourceRevisionId)' != ''">
        <_Parameter1>PackageSourceRevisionId</_Parameter1>
        <_Parameter2>$(SourceRevisionId)</_Parameter2>
      </AssemblyAttributes>
    </ItemGroup>
​
    <MakeDir Directories="$(ProjectDir)Properties"/>
    <WriteCodeFragment Language="C#" OutputFile="$(SharedPackageInfoFile)" AssemblyAttributes="@(AssemblyAttributes)" />
    <Message Importance="high" Text="SharedPackageInfoFile --> $(SharedPackageInfoFile)" />
​
    <ItemGroup>
      <Compile Include="$(SharedPackageInfoFile)" Pack="true" BuildAction="Compile" />
    </ItemGroup>
  </Target>
</Project>

而 AllenCai.BuildingBlocks.targets 文件，将会被打包到NuGet包。

当这个包被添加引用到目标项目中，MsBuild 将会自动调用它，执行一系列由你定义的动作。

那么，又为什么需要这个 AllenCai.BuildingBlocks.targets 文件呢？

它其实是非必须的，根据项目实际情况而定，没有这个 targets 文件也是可以的。

但这样的话，可能引用这个源代码组件包的开发者会在刚引入时遇到一系列问题，导致这个源代码组件包对开发者不友好。

比如源代码文件中使用了不安全代码，而目标项目的<AllowUnsafeBlocks>属性值是 false，那么目标项目在编译时就会报错。

因此需要这个 targets 文件来检查和自动设置为 true。

如以下示例代码(build\AllenCai.BuildingBlocks.targets)：

<Project>
  <Target Name="UpdateLangVersionAndAllowUnsafeBlocks" BeforeTargets="BeforeCompile">
    <PropertyGroup>
      <OldAllowUnsafeBlocks>$(AllowUnsafeBlocks)</OldAllowUnsafeBlocks>
      <AllowUnsafeBlocks Condition=" '$(AllowUnsafeBlocks)' == '' or $([System.String]::Equals('$(AllowUnsafeBlocks)','false','StringComparison.InvariantCultureIgnoreCase')) ">True</AllowUnsafeBlocks>
    </PropertyGroup>
​
    <!--当属性项被修改时，在Build控制台输出提示-->
    <Message Importance="high" Condition=" '$(AllowUnsafeBlocks)' != '$(OldAllowUnsafeBlocks)' " Text="Update AllowUnsafeBlocks to $(AllowUnsafeBlocks)" />
  </Target>
</Project>
以及 buildMultiTargeting\AllenCai.BuildingBlocks.targets 文件代码如下所示：
<Project>
  <Import Project="..\build\AllenCai.BuildingBlocks.targets" />
</Project>

需要注意的是，这个 targets 文件需要与 ProjectName 或 PackageId 保持一致。

最后 AllenCai.BuildingBlocks.csproj 文件代码如下所示：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>net5.0;net6.0;net7.0;net8.0</TargetFrameworks>
    <LangVersion>default</LangVersion>
    <Nullable>enable</Nullable>
    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
    <ImplicitUsings>disable</ImplicitUsings>
    <ProduceReferenceAssembly>false</ProduceReferenceAssembly>
    <GenerateDocumentationFile>false</GenerateDocumentationFile>
    <Version>0.0.1</Version>
  </PropertyGroup>
​
  <!--一些与NuGet包相关的属性项-->
  <PropertyGroup>
    <Title>AllenCai BuildingBlocks</Title>
    <Description>提供一组最常用的通用软件模块,以文件链接的方式被包含到引用项目中。</Description>
    <Authors>Allen.Cai</Authors>
    <Copyright>Copyright © Allen.Cai 2015-$([System.DateTime]::Now.Year) All Rights Reserved</Copyright>
    <ContentTargetFolders>contentFiles\cs\any\AllenCai.BuildingBlocks;content\cs\any\AllenCai.BuildingBlocks</ContentTargetFolders>
    <!--该属性项声明了仅在开发期间依赖，并且不传递其自身的依赖项，这将导致目标项目需要主动引入间接依赖项-->
    <DevelopmentDependency>true</DevelopmentDependency>
    <!--打包时不包含编译输出的文件-->
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <!--该属性项仅用于源生成器(SourceGenerator)项目，从 Visual Studio 2022 v16.10及以上版本开始支持-->
    <!--<IsRoslynComponent>true</IsRoslynComponent>-->
    <!--跳过包分析-->
    <NoPackageAnalysis>true</NoPackageAnalysis>
    <PackageProjectUrl>http://192.168.1.88:5555/allen/allencai.buildingblocks/</PackageProjectUrl>
    <PackageReadmeFile>README.md</PackageReadmeFile>
    <RepositoryUrl>http://192.168.1.88:5555/allen/allencai.buildingblocks.git</RepositoryUrl>
    <RepositoryType>git</RepositoryType>
    <PackageIcon>icon.png</PackageIcon>
  </PropertyGroup>
​
  <ItemGroup>
    <!-- <PackageReference Include="System.Reactive" Version="5.0.0" /> -->
    <None Include="icon.png" Pack="true" PackagePath="\" />
    <None Include="..\..\README.md" Link="README.md" Pack="true" PackagePath="\" />
    <Content Include="**\*.cs" Exclude="obj\**\*.cs" Pack="true" BuildAction="Compile" />
  </ItemGroup>
</Project>

其中三个属性比较重要，DevelopmentDependency 和 IncludeBuildOutput 以及 ContentTargetFolders。

  1. 将 DevelopmentDependency 设置为 true，表示这个 NuGet 包仅在开发期间依赖​。
  2. 将 IncludeBuildOutput 设置为 false，表示打包时不包含编译输出的 dll​ 文件。
  3. 重写 ContentTargetFolders，将会改变这些源代码文件在目标项目中的虚拟​文件系统布局。

如有不明白，欢迎留言，互相探讨。

截止本文，我刚搜到有 MVP大佬-吕毅 也写了类似教程，​大家也可以参考：从零开始制作 NuGet 源代码包（全面支持 .NET Core / .NET Framework / WPF 项目） - walterlv

标签：文件,C#,csproj,AllenCai,BuildingBlocks,cs,源代码,targets
From： https://www.cnblogs.com/VAllen/p/18255504/how-to-use-csproj-to-build-the-csharp-source-cod

相关文章

  • 如何使用csproj构建C#源代码组件NuGet包？
    一般我们构建传统的NuGet包，都是打包和分发dll程序集文件。至于打包和分发C#源代码文件的做法，比较少见。那么这种打包源代码文件的做法，有什么优点和缺点呢？优点：方便阅读源代码。方便断点调试。减少Assembly程序集模块加载个数。更利于发布期间的剪裁（PublishTrimmed选项）。......
  • 【CS.SE】从源码到实践：探索日常对话的生成性语音模型ChatTTS
    文章目录1项目介绍1.1功能与特色2技术分析2.1模型架构3项目实践3.1快速上手4项目总结ReferencesGitcode上有许多优秀的开源项目，今天我们要介绍的是一个令人耳目一新的项目——ChatTTS。ChatTTS是一个基于深度学习的文本转语音（TTS）系统，它的目标是通过先进......
  • .NET C# 八股文 代码阅读（一）
    .NETC#八股文代码阅读（一）目录.NETC#八股文代码阅读（一）1两种获10000个数的方式，哪种效率更高？为什么？2请说出以下代码AB谁先打印，AB打印的值分别为多少？3关于值类型与引用类型、装箱与拆箱，以下代码会输出什么？4关于变量作用域，以下代码会输出什么？1两种获10000个数......
  • 如何使用csproj构建C#源代码组件NuGet包？
    一般我们构建传统的NuGet包，都是打包和分发dll程序集文件。至于打包和分发C#源代码文件的做法，比较少见。那么这种打包源代码文件的做法，有什么优点和缺点呢？优点：方便阅读源代码。方便断点调试。减少Assembly程序集模块加载个数。更利于发布期间的剪裁（PublishTrimmed选项）。......
  • 如何使用csproj构建C#源代码组件NuGet包？
    一般我们构建传统的NuGet包，都是打包和分发dll程序集文件。至于打包和分发C#源代码文件的做法，比较少见。那么这种打包源代码文件的做法，有什么优点和缺点呢？优点：方便阅读源代码。方便断点调试。减少Assembly程序集模块加载个数。更利于发布期间的剪裁（PublishTrimmed选项）。......
  • 如何使用csproj构建C#源代码组件NuGet包？
    一般我们构建传统的NuGet包，都是打包和分发dll程序集文件。至于打包和分发C#源代码文件的做法，比较少见。那么这种打包源代码文件的做法，有什么优点和缺点呢？优点：方便阅读源代码。方便断点调试。减少Assembly程序集模块加载个数。更利于发布期间的剪裁（PublishTrimmed选项）。......
  • 【信息学奥赛】CSP-J/S初赛03 计算机网络与编程语言分类
    第1节计算机网络基础1.1网络的定义所谓计算机网络，就是利用通信线路和设备，把分布在不同地理位置上的多台计算机连接起来。计算机网络是现代通信技术与计算机技术相结合的产物。网络中计算机与计算机之间的通信依靠协议进行。协议是计算机收、发数据的规则。TCP/IP：用于......
  • 如何使用csproj构建C#源代码组件NuGet包？
    一般我们构建传统的NuGet包，都是打包和分发dll程序集文件。至于打包和分发C#源代码文件的做法，比较少见。那么这种打包源代码文件的做法，有什么优点和缺点呢？优点：方便阅读源代码。方便断点调试。减少Assembly程序集模块加载个数。更利于发布期间的剪裁（PublishTrimmed选项）。......
  • 如何使用csproj构建C#源代码组件NuGet包？
    一般我们构建传统的NuGet包，都是打包和分发dll程序集文件。至于打包和分发C#源代码文件的做法，比较少见。那么这种打包源代码文件的做法，有什么优点和缺点呢？优点：方便阅读源代码。方便断点调试。减少Assembly程序集模块加载个数。更利于发布期间的剪裁（PublishTrimmed选项）。......
  • C语言开发日志，问题记录（长期更新版本）
    一、程序存储与占用1.编译后内存分配编译后的Code(代码),RO-data(只读,譬如const)，RW-data(读写,初始化非0的全局变量),存储在ROM(flash)中,ZI-data(初始化为0或者未初始化的变量),运行时ROM占用是Code+RO-data+RW-data运行时RAM占用是RO-data+RW-data+ZI-data;RW和ZI会被......

赞助商

阅读排行

网站主页关于我们联系我们网站地图

本网站内容转载自其他媒体，侵权联系[admin##ips99.com]。

Copyright © 2020-2023 IPS99 版权所有 IPS99