Ai2Csproj.Tool 1.0.0

AssemblyInfo 到 csproj

AssemblyInfo 到 csproj (ai2csproj) 是一个工具，可用于将 AssemblyInfo.cs 文件中定义的所有 AssemblyAttributes 迁移到 csproj 文件。主要用例是将 C# 代码库从 .NET Framework 迁移到 .NET Core 或更高版本。

安装

这可以作为 dotnet 工具安装。要为您的用户全局安装，请运行 dotnet tool install -g ai2csproj.tool。

用法

要将 Assembly Attributes 迁移到 .csproj，只需在 .csproj 相同目录下运行 ai2csproj。默认情况下，它将尝试查找与目录名称相同的 .csproj，并在工作目录的 Properties 文件夹中搜索 AssemblyInfo.cs 文件。如果您的项目没有这种布局，您必须指定适当的 --project_path 和 --assembly_info_path 命令行参数。

支持与不支持类型

ai2csproj 有一些可以直接处理的 AssemblyAttributes。这些被认为是“支持”类型。要获取支持类型的列表并退出，请传递 --list_supported_types 命令行参数。

支持类型的好处在于，您可以指定 ai2csproj 如何处理每种属性类型。这可以通过“行为”标志来控制（传递 --help 以查看行为标志列表）。可以传递三个值来修改 ai2csproj 如何处理每个支持的属性。

• migrate - 将此属性类型从 AssemblyInfo 文件移动到 csproj。如果不指定行为参数，则为默认行为。
• delete - 从 AssemblyInfo 文件中删除此属性类型，并且 不 移动到 csproj（换句话说，从程序集中完全删除属性）。
• leave - 不要将属性迁移到 csproj 文件，并将其保留在 AssemblyInfo.cs 中。

不支持的类型仍可迁移，但默认情况下它们会被保留。只需在命令行中传递 --migrate_unsupported_types 来迁移 所有 不支持的类型（要么全部迁移，要么什么也不做）。这应谨慎使用，因为此工具可能会迁移属性，但最终结果可能是一个无法编译的项目。

版本源

新的 SDK-Style .csproj 格式包含一个 <Version> 属性。根据微软文档，如果指定了此属性，但 <AssemblyVersion>、<FileVersion> 和/或 <InformationalVersion> 没有指定，则这三个值将默认为 <Version> 标记中包含的任何值（从 <Version> 中去除 AssemblyVersion 和 FileVersion 的任何后缀）。

<Version> 属性并不直接绑定到程序集属性。因此，该工具需要知道从哪里获取版本信息。这是通过 --version_source 参数完成的。默认情况下不会生成 <Version> 属性。然而，如果指定了参数，有以下可选项：

• exclude_version - 不在 .csproj 文件中添加 <Version> 属性。这是未指定 --version_source 参数时的默认行为。
• use_assembly_version - 将 AssemblyVersion 的值复制到 csproj 的 Version 元素中。
• use_file_version - 将 AssemblyFileVersion 的值复制到 csproj 的 Version 元素中。
• use_informational_version - 将 AssemblyInformationalVersion 的值复制到 csproj 的 Version 元素中。

注意，如果指定了 --version_source，则默认情况下还会复制从中复制的属性。因此，例如，如果传递了 --version_source=use_assembly_version，则 csproj 将包含一个 <Version> 和一个 <AssemblyVersion> 标记。如果要完全迁移远离 <AssemblyVersion>（或其他任何版本属性）并使 csproj 只包含 <Version>，请附加适当的删除行为参数集，例如 --assembly_version_behavior=delete。

其他标志

• --dry_run - 打印到 STDOUT ai2csproj 将执行的操作而不实际执行。csproj 和 AssemblyInfo 文件的最终内容也将打印到 STDOUT。
• --no_backup - 默认情况下，会备份 csproj 和 AssemblyInfo.cs 文件，方法是将它们复制到相同的目录并将 ".old" 添加到文件名末尾。
• --delete_old_assembly_info - 尝试删除旧的 AssemblyInfo 文件。如果文件中只剩下非全局命名空间或注释，则将其删除。如果 AssemblyInfo 文件包含其他内容，则保持不变。
• --define - 添加预处理器定义。如果您使用 #if 语句将属性设置为不同的值，并且想要指定要迁移的哪一个，则很有用。注意，任何排除在预处理器定义之外的属性都将 删除（请参阅限制部分）。

限制

• 写入修改后的 csproj 或 AssemblyInfo 文件时，代码格式化和空白无法保证。虽然文件内容应该保持不变，但迁移后空白可能会看起来不同。
• 解析 AssemblyInfo 时，如果您有一个与支持的程序集属性名称相同的自定义程序集属性，则该属性将被删除并迁移到 csproj。要使工具不执行此操作，请为该属性传递相应的 "leave" 参数，以便工具保留该程序集属性。
• AssemblyInfo 中的注释不会迁移到 .csproj。
• 如果您的 AssemblyInfo.cs 文件有语法错误，ai2csproj 可能无法正常工作。在运行 ai2csproj 之前确保项目可以编译。
• 当使用从 AssemblyVersion 或 FileVersion 复制的版本源时，属性值会 精确地 复制，即使该值对 <Version> 属性无效也是如此。
• 此工具与预处理定义配合使用效果不佳。从预处理中排除的任何属性，在工具运行时将完全被移除。将来可能会有重建.csproj中预处理逻辑的方法，但目前不支持。
• 如果您的自定义程序集属性包含一个枚举参数，它将被迁移到.csproj，但最终结果可能导致项目无法编译。如果您的自定义程序集属性包含枚举作为输入，建议将--migrate_unsupported_types设置为false（这是默认选项）。