Microsoft provides two different .NET runtimes: .NET Framework and .NET Core. Both implement the .NET Standard and code between each is fairly cross-compatible, but .NET Framework only works on Windows. We’ll discuss the differences between the two runtimes.

The Short Answer: Cross-Platform Compatibility

The quick answer is that .NET Core runs on Linux and macOS, while .NET Framework only runs on Windows. You’d use .NET Core when you need cross-platform compatibility, and you’d use .NET Framework when you need Windows-specific services and NuGet packages that have not been ported to .NET Core.

.NET Core is the successor to .NET Framework, so it’s definitely what you want to choose going forward. It leaves behind some Windows-only features, but many of these can still be supported with the Windows Compatibility Pack extension.

Overall Core and Framework are pretty much the same, but in practice they do have some slight differences. Both .NET Core and .NET Framework use the same API, called the .NET Standard, but Core is open-source, while Framework is Microsoft’s Windows-only implementation.

In general, Core is a bit more lightweight than Framework, as it’s designed for and commonly used with Docker in microservices-based backends. On top of being able to use Linux in the first place (necessary for Docker), the resulting image will be a bit smaller with .NET Core.

Beyond that, most of the differences lie in NuGet package differences. For example, Entity Framework Core is a bit different from Entity Framework 6, which runs on .NET Framework. ASP.NET Core is very different from ASP.NET 4, as they’ve redesigned a lot of it for .NET Core.

When to Use .NET Core

You should use .NET Core over .NET Framework when:

You need cross-platform compatibility. This includes the use of Docker and microservices architectures. You’re starting a new project and just need to pick one. (. NET Core is newer. ) You aren’t using any Windows-specific tools, libraries, or NuGet packages that depend on . NET Framework. You want the best performance possible. Microsoft recommends . NET Core with ASP. NET over . NET Framework. You want to run multiple versions of . NET Core alongside each other. Framework doesn’t support this. You want CLI access on Linux, or run your CI/CD build server on Linux.

When to Use .NET Framework

You should use .NET Framework over .NET Core when:

You’re only targeting Windows deployments. You make heavy use of Windows packages and libraries, such as Windows Forms, WPF, ASP. NET Web Forms/Pages, and Windows Workflow Foundation. The technologies you’re using aren’t added by the Windows Compatibility Pack for . NET Core. You’re already using it, and migration would be too much effort.

.NET 5 Is Coming Soon

Planned for release in November 2020, the .NET 5 runtime brings a number of improvements, but most importantly, promises to bring unity to the two separate runtimes. It has neither the “Core” or “Framework” moniker, as Microsoft is focused on consolidating the best of both runtimes into one package.

WPF and Windows Forms are supported in .NET 5, as well as numerous other compatibility fixes. Though it isn’t a drop in replacement for .NET Framework, it should be good enough to work great on both platforms. Microsoft isn’t dropping support for .NET Framework yet, but going forward, it’s likely to be phased out gradually.

How to Switch to .NET Core

Usually, this will be “how do you switch from Framework -> Core,” because any existing functioning project on .NET Core likely won’t need to switch back to the older .NET Framework.

If you’re using anything Windows-specific, you can’t. You’re stuck on .NET Framework until the components you’re using get Core versions, and for some things that won’t be happening like with ASP.NET WebForms.

The simplest solution would be to make a new Solution and project based on .NET Core, and transfer your code over. If you have have a simple app, this is likely the easiest solution.

Otherwise, you can use dotnet try-convert, or follow Microsoft’s porting guide.

For large complicated projects, you can use the .NET Portability Analyzer. This is a tool from Microsoft that will scan your project, tell you how hard a conversion might be, and show you what your next steps should be. It can also create a directed graph of your dependencies, which can help you see what else needs analysis. Some projects will be harder to port than others, and if you’re using something not available in Core, you might not be able to port at all without a workaround.