Microsoft.UpgradeAssistant.Mappings 1.0.7

升级助手

此存储库现在是 Visual Studio 升级助手 和其 CLI 替代品的第三方扩展的家园。

状态

	构建（调试）	构建（发布）
ci
官方

概述

此项目旨在将可扩展性引入 dotnet 升级助手工具。其中之一是映射，例如 包映射 和 API 映射，允许第三方供应商提供所需信息，以便将项目从旧版本 .NET 和/或旧供应商 API 升级到较新版本。

支持的项目类型和语言

目前，该工具支持以下项目类型

• ASP.NET MVC
• Windows 表单
• Windows 表达现实 (WPF)
• 控制台应用程序
• 库
• UWP 到 Windows App SDK (WinUI)
• Xamarin.Forms 到 .NET MAUI

该工具支持 C# 和 Visual Basic 项目。

可扩展性

映射扩展

目录结构

在 src/UpgradeAssistant.Mappings/mappings 目录中，每个供应商 应当 创建自己的子目录。每个供应商 可以 决定根据产品名称或其他任何符合其需求的准则来进一步细分其供应商特定子目录。

这些子目录中包含了3种类型的文件：metadata.json、packagemap.json和apimap.json。

metadata.json

无论您是想提供NuGet包升级或API更改的映射，都需要一个metadata.json文件。

metadata.json文件应该看起来像这样

{
  "traits": "<some traits go here>",
  "order": 1000
}

metadata.json文件中的traits和order元数据将自动继承同一目录或任何子目录（无论子目录深度如何）中存在的任何packagemap.json和apimap.json文件。

"traits"属性

traits属性是一个字符串，用于定义在哪些情况下升级助手应该应用包映射和/或API映射。

例如，如果供应商想升级Xamarin.Forms项目的NuGet包引用，他们可能会使用traits字符串为Xamarin或(Xamarin | Maui)。

有关特质的更多信息，请点击此处。

"order"属性

order属性是一个用于排序包映射更改和API映射更改应用顺序的整数值。

我们建议为供应商特定的映射从1000开始。

包映射

包映射定义了如何在项目中升级NuGet包引用，以引用替代的NuGet包，或相同NuGet包的新版本。

以下是一个包含注释的packagemap.json文件示例，解释了一些不同的可能性

{
  "packages": [
    {
      "name": "Vendor.ProductName",
      "frameworks": {
        ".NETCoreApp,Version=v5.0": [
          // An empty array will remove the package from projects with the specified target framework.
        ],
        ".NETCoreApp,Version=v6.0": [
          {
            // An empty package definition will upgrade the package to the latest available version of the same package name.
            // When the "name" property is null or unspecified, it will automatically default to the original package name.
            // When the "version" is null or unspecified, it will default to the latest version available.
            // Thus, if neither are specified, it will default to the latest version of the original package.
          }
        ],
        ".NETCoreApp,Version=v7.0": [
          {
            // Specifying a "name" and "version" will upgrade the package to an exact package.
            "name": "Vendor.NewProductName",
            "version": "7.0.11"
          }
        ],
        ".NETCoreApp,Version=v8.0": [
          {
            // Specifying a "name" and a wildcard "version" will upgrade the package to the latest version that matches the wildcard version.
            "name": "Vendor.ProductName.Abstractions",
            "version": "8.*",

            // Specifying "prerelease": true will tell the UpgradeAssistant that it can match against prerelease versions.
            "prerelease": true
          },
          {
            "name": "Vendor.ProductName.Core",
            "version": "8.*",
            "prerelease": true
          }
        ]
      }
    }
  ]
}

值得注意的是，在上面的示例中，当升级助手将项目升级到.NET 8.0时，它将升级到Vendor.ProductName的引用到Vendor.ProductName.Abstractions和Vendor.ProductName.Core。这在将包拆分为多个包的场景中非常有用。

API映射

API映射定义了升级助手在升级项目时应如何转换用户代码中的命名空间、类型名、方法名和属性名。

apimap.json文件由一组API映射组成。一个仅包含1个映射的apimap.json文件示例可能如下所示

{
  "Windows.UI.WindowManagement.AppWindow.TryCreateAsync": {
    "value": "Microsoft.UI.Windowing.AppWindow.Create", // new value to replace old one with, if empty if state is not Replaced
    "kind": "method", // method|property|namespace|type
    "state": "Replaced", // Replaced|Removed|NotImplemented
    "isStatic": true,
    "needsManualUpgrade": false, // if true, only comment is added, no other code modifications happening
    "documentationUrl": "some url", // link to documentation URL,
    "needsTodoInComment": true, // if true TODO is added to the comment if comment is being added
    "isAsync": false,
    "messageId": "resource id", // in case custom comment needs to be added, this resource id will be looked up in the ResourceManager,
    "MessageParams": [ "", "" ] // parameters to be passed into string format for custom message
  }
}

上述示例将把用户代码中所有出现Windows.UI.WindowManagement.AppWindow.TryCreateAsync()的地方转换成Microsoft.UI.Windowing.AppWindow.Create。

由于升级助手使用Roslyn解析和操作用户代码，即使调用AppWindow.TryCreate()的用户代码也会被升级。

对于XAML升级，需要额外的映射。以下是一个示例

{
  "http://xamarin.com/schemas/2020/toolkit": {
    "value": "http://schemas.microsoft.com/dotnet/2022/maui/toolkit",
    "kind": "xmlnamespace",
    "state": "Replaced",
    "properties": [
      "Xamarin.CommunityToolkit.Behaviors",
      "Xamarin.CommunityToolkit.Converters",
      "Xamarin.CommunityToolkit.UI.Views"
    ]
  }
}

升级助手将更新XML命名空间，如xmlns:toolkit="http://xamarin.com/schemas/2020/toolkit"到xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"。参数包含来自旧SDK的模块级XmlnsDefinitionAttribute的值。这些值将用于更新参数值，如xmlns:tk='clr-namespace:Xamarin.CommunityToolkit.Behaviors; assembly=...'到xmlns:tk='clr-namespace:Microsoft.Maui.Behaviors; assembly=...'。

参与、贡献和反馈

一些最好的贡献方式是使用工具将应用程序升级到.NET（STS、LTS或preview）最新版本，提交关于功能请求或错误的报告，加入设计对话，以及创建pull请求。

有关记录问题、开始讨论、Pull请求流程等详细信息，请查看贡献页面。

祝您愉快地升级到.NET（STS、LTS或preview）最新版本！