How to upgrade csproj files with VS2017

Question

VS2017 has so far correctly converted several project.json/.xproj based projects to the new .csproj format.

I would also like to use the new .csproj format with older .csproj projects that previously targeted only .NET Framework (i.e. they didn't work with dnx/dotnet CLI).

It seems that even if a project would still only target .NET Framework, the benefits of <PackageReference> and an easily editable .csproj file seem worth the (hopefully not too great) trouble.

Is this possible to do with Visual Studio 2017 directly?

If not, what manual steps would be required?

Handout

Possible duplicate of How to convert a non-core csproj to VS2017 format – Immeasurable

Seems that using the new .csproj for non-Core projects is possible, with restrictions, as shown here – Damales

Yes using the new csproj file for non-Core projects is possible but not necessary. See my answer below. – Jud

Answer 1

I'm editing my answer to make it clear that you don't need to upgrade your .csproj file. As Drew commented below there are benefits to doing so. However, VS2017 will continue to work with the classic csproj file just fine. In addition there is nothing in VS2017 that will perform the upgrade for you. If you do wish to take advantage of the new format the walk through below should help.

Upgrading the .csproj file to the new Visual Studio 2017 format is easy for simple class libraries or console projects.

If you're not using version control, before you begin be sure to backup your csproj file, and both Properties/AssemblyInfo.cs, and packages.config. The new csproj file is great. In many projects I've replaced hundreds of lines of code with a dozen or so. However, as Visual Studio 2017 continues to support the previous csproj files this may be a case of premature optimization. If you have a solution that contains dozens of projects, many NuGet packages, and any customization to csproj you are likely undertaking an unnecessary make work project.

Replace the entire contents of your .csproj file with the appropriate code as follows.

Class Library

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net462</TargetFramework>
  </PropertyGroup>
</Project>

Console Application

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net462</TargetFramework>
  </PropertyGroup>
</Project>

Change the <TargetFramework>attribute to the .NET version you require such as net452, net46, net461 etc.

By default all code within your project folder will be picked up by the compiler. If you have code outside your project folder you must explicitly reference it the same way you do in previous versions of Visual Studio and csproj.

After making the above changes load your solution in Visual Studio 2017. At this point the most basic projects should build. If not you likely need to add missing assembly or project references. Adding references is very similar to doing so in previous versions of Visual Studio. Select your project in the Solution Explorer, right click on Dependencies, and select Add Reference. Add any Framework or Project references that you're missing.

Attempt to build your solution/project again. You may receive errors about duplicate attributes. This error is because attributes previously defined in AssemblyInfo.cs have been moved to the csproj file. Deleting the AssemblyInfo.cs file, found under the Properties folder, should resolve these errors. Before deleting the AssemblyInfo.cs you should move any data you have defined. Most attributes can be entered in the package information section of your project file. Right click on your project name, select the Package page, and enter any data that was previously defined in your AssemblyInfo.cs file. This includes items such as the assembly version, author, copyright etc.

Below is a screen shot that shows the previous step.

If you are using any NuGet packages in your project you need to move those to the new format as well. Previous to Visual Studio 2017 NuGet relied on a file named Packages.config in the root of your project in addition to references in csproj. To migrate your NuGet package references right click on your solution and load the Nuget Package Manager. Once loaded in the upper-right hand corner, click the cog, and the NuGet Package Manager Options will load. Select General. Under Package Management change the option Default package management format to PackageReference. At this point you'll have to manually add all your NuGet packages back to your solution. You can find all the packages in the packages.config file in the project's root folder. Once you have added all the packages back you can delete the packages.config file.

Jud

Thanks very much for this. Some benefits of the new project that might motivate an upgrade: 1) simpler management of NuGet dependencies (no more packages file, and no requirement to use the package manager console or VS's manage NuGet packages), 2) the ability to define a NuGet package in the project file directly, 3) the ability to edit the .csproj file without unloading/reloading – Handout

@DrewNoakes and also a .csproj file that is far easier to manage with version control and can be edited by hand during merges. I've used @thekip's tool on several projects with much success. – Snath

Answer 2

I have created a tool for this that works with csproj files: https://github.com/hvanbakel/CsprojToVs2017

You can just run it on a csproj and it'll convert the file and create a backup of the old.

Raffin

This is great, thanks! We converted a couple of projects seamlessly with your tool. Too bad it doesn't work with Entity Framework-using projects. What prevents this from working? Would there be a way to let the tool perform the conversion as much as it can, knowing that some manual fixes would be required afterwards? – Bracing

Answer 3

One may use .NET Upgrade Assistant for that.

Installation (replace version with the latest one, check on NuGet.org):

  dotnet tool install --global upgrade-assistant --version 0.4.355802

Start the interactive process, and exit after step 2 "Convert project file to SDK style":

  upgrade-assistant upgrade <project>.csproj

Milena

Answer 4

Update: The tool link below is dead, but as of VS2017 15.7, this functionality is built-in to Visual Studio.

Note: This only updates the NuGet reference mechanism. It does not change to the new csproj type.

---

There's an amazing tool that automatically converts projects that are using packages.config or project.json to PackageReference.

https://marketplace.visualstudio.com/items?itemName=TaylorSouthwickMSFT.NuGetPackagetoProjectjsonConverter

1. Install it to your Visual Studio

2. After you install the extension, open your solution and right click the solution in Solution Explorer and click Upgrade to Package References

3. After selecting that, the project will be transformed as shown below. It is highly recommended that you perform this on a source-control enabled directory so you can easily undo if something goes wrong.

Sanjay

This looks very useful, thanks. Note that it doesn't actually upgrade the csproj format to the newer .NET Core / dotnet SDK style, but rather converts old style packages.config references to <PackageReference> elements in your existing csproj files. This might actually be desirable for many projects that don't need to target .NET Core. – Handout

Answer 5

There is a great tool out there that automatically converts the csproj to the new SDK format for you:

https://github.com/hvanbakel/CsprojToVs2017

Of course it won't convert an ASP.NET project because these ones don't support the new SDK format. All other project work like a charm.

Hardunn

Answer 6

There's a try-convert tool built by Microsoft (though unsupported) that may be useful:

It's a .NET Global Tool which can be installed with:

dotnet tool install -g try-convert

Once installed, run try-convert for instructions. At it's simplest, use:

try-convert -p MyProject.csproj

Again, note that this is an unsupported tool and may not work reliably. From the docs on porting from .NET Framework to .NET Core:

Additionally, you can attempt to port smaller solutions or individual projects in one operation to the .NET Core project file format with the dotnet try-convert tool. dotnet try-convert is not guaranteed to work for all your projects, and it may cause subtle changes in behavior that you depended on. Use it as a starting point that automates the basic things that can be automated. It isn't a guaranteed solution to migrating a project.

It's an open source project, available on GitHub:

https://github.com/dotnet/try-convert

Handout