如何将C#项目迁移到.NET Core

将传统的.NET Framework下的C#项目迁移到.NET Core，是很多开发团队升级技术栈的重要工作，迁移后可以支持跨平台部署，同时获得更好的性能表现和更长的官方支持周期。

迁移前的准备工作

在正式开始迁移之前，需要先完成以下几项准备工作，降低迁移过程中的风险：

• 梳理项目当前使用的所有第三方依赖，确认这些依赖是否有对应的.NET Core版本，或者是否有可替代的兼容库。
• 检查项目中是否使用了.NET Framework特有的API，这些API在.NET Core中可能不存在或者行为有差异，需要提前做好适配方案。
• 备份当前完整的项目代码和相关的配置文件，避免迁移过程中出现不可逆的代码丢失问题。
• 搭建独立的迁移测试环境，不要直接在原有生产环境的项目上进行修改。

基础类库项目迁移步骤

如果是没有依赖Web相关组件的纯C#类库项目，迁移流程相对简单，按照以下步骤操作即可：

1. 修改项目文件格式

.NET Core使用的项目文件是SDK风格的格式，和旧版.NET Framework的项目文件结构差异较大，首先需要将原有项目文件替换为新的格式。新的项目文件内容示例如下：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <OutputType>Library</OutputType>
    <AssemblyName>DemoClassLibrary</AssemblyName>
    <RootNamespace>DemoClassLibrary</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
    <!-- 原有项目依赖的第三方包，需要替换为对应的.NET Core版本 -->
    <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
  </ItemGroup>
</Project>

2. 处理不兼容的代码

修改完项目文件后，编译项目查看报错信息，针对提示的不兼容API进行调整。比如旧版中使用的System.AppDomain部分方法在.NET Core中不可用，需要替换为System.Reflection.Assembly相关的实现。示例适配代码如下：

// 旧版.NET Framework获取程序集路径的代码
// string path = AppDomain.CurrentDomain.SetupInformation.ApplicationBase;

// 适配.NET Core后的代码
using System.IO;
using System.Reflection;

string path = Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location);

ASP.NET项目迁移步骤

如果是ASP.NET Web Forms或者ASP.NET MVC项目，迁移到ASP.NET Core的流程会更复杂，因为ASP.NET Core的管道模型和旧版完全不同。

1. 创建新的ASP.NET Core项目

首先新建一个对应类型的ASP.NET Core空项目，然后将原有项目的控制器、模型、视图等业务代码逐步迁移到新项目中。

2. 迁移配置文件

旧版项目中的Web.config配置文件需要替换为appsettings.json，同时将配置读取逻辑调整为IConfiguration的方式。示例配置和读取代码如下：

// appsettings.json内容
{
  "ConnectionStrings": {
    "DefaultDb": "Server=localhost;Database=test;Uid=root;Pwd=123456;"
  },
  "AppSettings": {
    "MaxUploadSize": 10485760
  }
}

// 读取配置的代码
using Microsoft.Extensions.Configuration;

public class ConfigService
{
    private readonly IConfiguration _configuration;

    public ConfigService(IConfiguration configuration)
    {
        _configuration = configuration;
    }

    public string GetDbConnection()
    {
        return _configuration.GetConnectionString("DefaultDb");
    }

    public int GetMaxUploadSize()
    {
        return _configuration.GetValue<int>("AppSettings:MaxUploadSize");
    }
}

3. 迁移中间件和管道配置

旧版项目中的HTTP模块和处理程序需要替换为ASP.NET Core的中间件，在Program.cs中配置请求管道。示例代码如下：

var builder = WebApplication.CreateBuilder(args);

// 添加控制器服务
builder.Services.AddControllersWithViews();

var app = builder.Build();

// 配置中间件管道
if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}
else
{
    app.UseExceptionHandler("/Home/Error");
}

app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.Run();

迁移后的验证工作

完成代码迁移后，需要进行全面的验证，确保项目功能正常：

• 编译项目，确保没有语法错误和引用缺失的问题。
• 运行所有单元测试用例，验证核心业务逻辑的正确性。
• 在Windows、Linux等不同操作系统上部署运行，确认跨平台功能正常。
• 进行性能测试，对比迁移前后的响应速度和资源占用情况。

常见迁移问题排查

迁移过程中可能会遇到各类问题，以下是几个常见问题的解决方法：

C#NET_Core项目迁移ASP.NET_Core修改时间：2026-06-26 17:03:33