Analyze your dependencies to port code to .NET Core
To port your code to .NET Core or .NET Standard, you must understand your dependencies. External dependencies are the NuGet packages or DLLs you reference in your project, but that you don't build. Evaluate each dependency and develop a contingency plan for the ones that aren't compatible with .NET Core. Here's how to determine if a dependency is compatible with .NET Core.
Analyze referenced NuGet packages in your projects
If you reference NuGet packages in your project, you need to verify if they're compatible with .NET Core. There are two ways to accomplish that:
After analyzing the packages, if they're not compatible with .NET Core and only target .NET Framework, you can check if the .NET Framework compatibility mode can help with your porting process.
Analyze NuGet packages using NuGet Package Explorer
A NuGet package is itself a set of folders that contain platform-specific assemblies. So you need to check if there's a folder that contains a compatible assembly inside the package.
The easiest way to inspect NuGet Package folders is to use the NuGet Package Explorer tool. After installing it, use the following steps to see the folder names:
- Open the NuGet Package Explorer.
- Click Open package from online feed.
- Search for the name of the package.
- Select the package name from the search results and click open.
- Expand the lib folder on the right-hand side and look at folder names.
Look for a folder with any of the following names:
netstandard1.0 netstandard1.1 netstandard1.2 netstandard1.3 netstandard1.4 netstandard1.5 netstandard1.6 netstandard2.0 netcoreapp1.0 netcoreapp1.1 netcoreapp2.0 netcoreapp2.1 netcoreapp2.2 portable-net45-win8 portable-win8-wpa8 portable-net451-win81 portable-net45-win8-wpa8-wpa81
When looking at the TFMs that a package supports, note that
netcoreapp*, while compatible, is for .NET Core projects only and not for .NET Standard projects.
A library that only targets
netcoreapp* and not
netstandard* can only be consumed by other .NET Core apps.
Analyze NuGet packages using nuget.org
Alternatively, you can see the TFMs that each package supports on nuget.org under the Dependencies section of the package page.
Although using the site is an easier method to verify the compatibility, Dependencies information is not available on the site for all packages.
.NET Framework compatibility mode
After analyzing the NuGet packages, you might find that they only target the .NET Framework, as most NuGet packages do.
Starting with .NET Standard 2.0, the .NET Framework compatibility mode was introduced. This compatibility mode allows .NET Standard and .NET Core projects to reference .NET Framework libraries. Referencing .NET Framework libraries doesn't work for all projects, such as if the library uses Windows Presentation Foundation (WPF) APIs, but it does unblock many porting scenarios.
NU1701: Package ‘Huitian.PowerCollections 1.0.0’ was restored using ‘.NETFramework,Version=v4.6.1’ instead of the project target framework ‘.NETStandard,Version=v2.0’. This package may not be fully compatible with your project.
That warning is displayed when you add the package and every time you build to make sure you test that package with your project. If your project is working as expected, you can suppress that warning by editing the package properties in Visual Studio or by manually editing the project file in your favorite code editor.
To suppress the warning by editing the project file, find the
PackageReference entry for the package you want to suppress the warning for and add the
NoWarn attribute. The
NoWarn attribute accepts a comma-separated list of all the warning IDs. The following example shows how to suppress the
NU1701 warning for the
Huitian.PowerCollections package by editing your project file manually:
<ItemGroup> <PackageReference Include="Huitian.PowerCollections" Version="1.0.0" NoWarn="NU1701" /> </ItemGroup>
For more information on how to suppress compiler warnings in Visual Studio, see Suppressing warnings for NuGet packages.
Port your packages to
You can learn more at Migrate from packages.config to PackageReference.
What to do when your NuGet package dependency doesn't run on .NET Core
There are a few things you can do if a NuGet package you depend on doesn't run on .NET Core:
- If the project is open source and hosted somewhere like GitHub, you can engage the developers directly.
- You can contact the author directly on nuget.org. Search for the package and click Contact Owners on the left-hand side of the package's page.
- You can search for another package that runs on .NET Core that accomplishes the same task as the package you were using.
- You can attempt to write the code the package was doing yourself.
- You could eliminate the dependency on the package by changing the functionality of your app, at least until a compatible version of the package becomes available.
Remember that open-source project maintainers and NuGet package publishers are often volunteers. They contribute because they care about a given domain, do it for free, and often have a different daytime job. So be mindful of that when contacting them to ask for .NET Core support.
If you can't resolve your issue with any of the above, you may have to port to .NET Core at a later date.
The .NET Team would like to know which libraries are the most important to support with .NET Core. You can send an email to email@example.com about the libraries you'd like to use.
Analyze dependencies that aren't NuGet packages
You may have a dependency that isn't a NuGet package, such as a DLL in the file system. The only way to determine the portability of that dependency is to run the .NET Portability Analyzer tool. The tool can analyze assemblies that target the .NET Framework and identify APIs that aren't portable to other .NET platforms such as .NET Core. You can run the tool as a console application or as a Visual Studio extension.
If you're porting a library, check out Porting your Libraries.