Library Manager (LibMan) in Visual Studio 2017 (15.7) How to restore client side libraries in ASP.NET Core projects.

UPDATE: 24-May-2018 – It looks like LibMan didn’t make it into the final release of 15.7. It’s in the preview for 15.8.x currently so we may see it when that version lands.

I recently started working on an ASP.NET Core 2.1 Preview 2 sample project. Having been mostly API focused recently, it was the first time that I’d done much with a site that actually renders views for a while. I found myself needing to re-learn my options for client side libraries.

My work on Humanitarian Toolbox is view based, however the project has grown up over a number of years and relies on a combination of NPM and gulp to bring in the required client side libraries.

For a brand new project, the templates will include a lib folder in wwwroot which has the necessary files which support the template features. However, if you’re checking into git, it’s quite normal to not include the lib folder, instead requiring the packages to be pulled on the client machine once cloned.

Full disclosure: I don’t consider myself a client side expert. I’m far more comfortable with the server side code! As such, this post is based on my own (potentially naive) approach to working with client side libraries.

Library Manager

Library Manager is a new feature included in Visual Studio 2017 (as of 15.7 preview 3) that provides new support for managing client side libraries in your projects. In this post I’m going to explore the basics of how I used this in a new project.

To add the Library Manager functionality to a project, simply right click on the project and choose the “Manage Client-Side Libraries…” option.

Manage client side libraries in Visual Studio 2017

This will add a single file to your project called libman.json. Note in the screenshot that at this point I don’t have a lib folder under wwwroot.

libman.json in solution

The libman.json file will be nearly empty when it’s first added. It includes a version and default provider. There is also an empty array of libraries defined. This is where we’ll add the packages we need for our project.

Default empty libman.json

In my example, my front end views only need bootstrap and jquery at this stage. Let’s look at how we can add those to our project. Each library is added as an object. There are a few properties we can set. The tooling offers autocomplete which makes populating this file a pretty straightforward experience. Here is an example of my final libman.json file.

Taking the boostrap entry as an example. The first value I provide is the name and version of the required library – “twitter-bootstrap@3.3.7”.

Next is the destination for the restored files relative to your project. In this case I’m including them under the wwwroot folder, in a directory called lib and then bootstrap.

Finally, in this example, I specify the individual files I want restored. This is optional. If you don’t include the array of files then all files from the library will be included. I preferred to be a little more selective about those that I needed here.

There’s also a value I’m not providing here to override the provider from which the library should be restored from. The provider options at this stage are cdnjs or filesystem.

Upon saving this file, the required libraries will be restored into your specified directory.

Restored lib folder in Visual Studio 2017

If you want to force a restore, perhaps after first cloning a project, you can do so by right clicking the libman.json file and choosing “Restore Client-Side Libraries”.

Restore client side libraries with lib man in Visual Studio 2017

Another option on this context menu is the “Enabled Restore on Build…” option. If you choose this option it will add a NuGet package to the project which will trigger the specified libraries to be restored on build. This is useful for CI / build servers for example (although I’ve not tested that at this stage). Choosing this option will present you with a dialog to confirm you wish to include the NuGet package.

Confirm adding Microsoft Library Manager build package

Once you do this a PackageReference will be added to you csproj file for “Microsoft.Web.LibraryManager.Build”.

CSPROJ after adding LibraryManager.Build

You’ll see the output from this when building your project. In this example I deleted the lib folder before triggering my build and you can see the files being restored as necessary.

Build output from libman.json (Library Manager)

That’s it for this post! I’ve not gone too deep into the tooling but so far this feels like a nice integrated way to specify and restoring client side libraries. Certainly I was able to get going with it pretty quickly and if it means I don’t need to learn about other client-side package managers and tooling, I’m pretty happy with that! I’m sure more seasoned client side developers will be better placed to judge this against the various other ways we can manage client side packages.


Migrating from project.json to csproj using Visual Studio 2017 Moving a real world ASP.NET Core application using VS2015 project.json to VS2017 and csproj

This past weekend I spent a few hours working on migrating the Humanitarian Toolbox allReady project over to the new csproj based Visual Studio 2017 solution format. I’ve written a few times about the plans to retire the project.json file introduced by ASP.NET Core. If you want some background you can read those posts first (don’t worry, I’ll wait)…

The summary is that in Visual Studio 2017 and the final ASP.NET Core SDK tooling, the project.json file was removed in favour of a revised csproj file. This has left some people confused and wondering why project.json is missing in Visual Studio 2017. The decision was mostly made to support customers reliant on using MsBuild and to support migrating larger projects to .NET Core.

Moving from project.json to csproj

In this post I wanted to cover the steps I took to migrate a real ASP.NET Core application to Visual Studio 2017. I’ve recorded the steps that I took and the issues I faced, along with any solutions I was able to find.

TL;DR; It wasn’t as painful as I’d expected it might be, but it also wasn’t entirely automated. There were a few issues along the way, which required some intervention on my part to finally get everything building correctly.

My first trial attempt at this process was actually about 2 weeks ago. At that time I was using the first RTM version of VS 2017 and I started by simply opening our allReady solution file with Visual Studio 2017. 

Visual Studio presents a dialog showing that any project.json projects will be migrated.

Visual Studio 2017 project.json migration dialog

After accepting that message VS will do it’s thing. Under the covers it’s calling the dotnet migrate command which handles the conversion for you. I decided to use Visual Studio 2017 for the migration, rather than the command line as I expect that’s the approach most people will be taking.

During migration; which took only a few seconds for me, you’ll see a progress window from Visual Studio.

ASP.NET Core project.json migration progress

Once the migration is completed you are shown a migration report.

project.json to csproj migration report

This initially led me to believe that things had gone pretty well. In fact, when I tried a restore and build things were not quite so positive. I was shown a staggering 982 errors and 3 warnings. It was late and I was tired, so I decided to abandon attempt one at that point! That was a problem for my future self!

Attempt Two

This weekend I was finally in a position to have another try at the migration. I took the latest version of our code and before starting, updated Visual Studio 2017 because I’d seen that it had some updates pending.

I repeated the initial steps as before and this time, although the result was still not looking great, it was a fair amount improved on attempt 1. Lesson 1 – Always do migrations with the most updated version of the IDE! This time I was at 199 errors and 2 warnings.

project.json Migration Errors

The errors were mostly relating to dependencies so it looked to be a restore issue. I tried cleaning the solution, restarting Visual Studio and even manually deleting the bin and obj folders. Each time I was hit with a wall of red errors when trying to build.

At this point I jumped onto Google and found a suggestion to clear the local nuget cache. I navigated to %USERPROFILE%/.nuget and deleted the contents.

Upon doing that, things were starting to look a little better. The errors cleared but I now had some warnings to deal with and the site would not run.

The second warning was a little strange.

The referenced project ‘..\..\Backup\Web-App\AllReady\AllReady.csproj’ does not exist.

The unit test project was referencing the web project but using the backup folder path. The backup folder is created during migration to hold the original project.json and xproj files in case you need to get back to a prior state. That folder of course didn’t include a csproj file. I removed the reference and re-added it, pointing it to the correct folder.

I also took the chance to move the backup folder so that it was outside of my main solution structure, just in case it was causing or masking any other issues.

Attempting to build at this stage reduced my errors but I still had 29 warnings. To be sure that Visual Studio 2017 wasn’t partly to blame, I also tried using the command line dotnet restore commands directly. However, I was getting warnings there also.

Inside Visual Studio the warning looked like this:

Detected package downgrade: Microsoft.Extensions.Configuration.Abstractions from 1.1.0 to 1.0.2

Trying to run the application at this stage resulted in the following exception:

System.IO.FileLoadException: ‘Could not load file or assembly ‘Microsoft.Extensions.Configuration.Abstractions, Version … The located assembly’s manifest definition does not match the assembly reference.

For some reason the migration had chosen version 1.1.0 for the Microsoft.VisualStudio.Web.BrowserLink dependency when it created the csproj file.

<PackageReference Include="Microsoft.VisualStudio.Web.BrowserLink" Version="1.1.0" />

The solution was to change it to 1.0.1 since allReady is targeting the LTS stream of ASP.NET Core currently. All of the other dependencies were registered with their LTS versions. This rouge 1.1.x dependency was therefore causing version conflicts.

<PackageReference Include="Microsoft.VisualStudio.Web.BrowserLink" Version="1.0.1" />

At this point, building the solution was getting a bit further. I now had a single warning left for the web project. This warning stated that AddUserSecrets(IConfigurationBuilder) is now an obsolete method.

‘ConfigurationExtensions.AddUserSecrets(IConfigurationBuilder)’ is obselete. ‘This method is obsolete and will be removed in a future version. The recommended alternative is .AddUserSecrets(string userSercretsId) or .AddUserSecrets<TStartup>()..’

The warning explains that we were now expected to pass in the user secrets key as a string to the method or use .AddUserSecrets<TStartup> which is syntactic sugar over AddUserSecrets(this IConfigurationBuilder configuration, Assembly assembly). Previously the storage location for the user secrets ID was the project.json file. It’s now moved to an assembly attribute. The previous overload is not guaranteed to return the correct Assembly so this could produce issues. You can read a fuller explanation from the team on the GitHub repo.

In our case I changed the appropriate line in Startup.cs from




Test Project Changes

At this point the web project was building but there were issues inside the test project:

Test project warning after project.json migration

Found conflicts between different versions of the same dependent assembly that could not be resolved. These reference conflicts are listed in the build log when log verbosity is set to detailed.

Some of the dependencies we had been using had newer versions so I took a guess that perhaps I needed to update the Xunit / test related ones. I changed these three dependencies:

<PackageReference Include="Microsoft.NET.Test.Sdk" Version="15.0.0-preview-20170106-08" />
<PackageReference Include="xunit.runner.visualstudio" Version="2.2.0-beta5-build1225" />
<PackageReference Include="xunit" Version="2.2.0-beta5-build3474" />


<PackageReference Include="Microsoft.NET.Test.Sdk" Version="15.0.0" />
<PackageReference Include="xunit.runner.visualstudio" Version="2.2.0" />
<PackageReference Include="xunit" Version="2.2.0" />

Finally the entire solution was building, tests were running and I could start the website locally.

Initial thoughts on csproj and Visual Studio 2017

Generally, everything seems to work once inside Visual Studio 2017. The migration process was a little more effort than I would have liked though.

No auto complete

In Visual Studio 2015 we had version auto complete for the dependencies from NuGet when editing project.json. We’ve lost this in Visual Studio 2017 which is a shame. It now pretty much forces me into the NuGet Package Manager which I find slower. I understand that autocomplete might come back at some point, but it’s a shame we’re lacking it upon release. 

Less easy to scan

Personally, I still prefer the project.json format for readability. There’s still a little more noise in the XML than we had inside the JSON version. That said, the work done to the revised csproj format is great and it’s a vast improvement on the csproj of the past.

Summing Up

Overall the process wasn’t too harrowing. Visual Studio and dotnet migrate handled most of the work for me. It was a shame that I had to resort on a few occasions to Google for manual solutions to solve problems that I’m sure should have been addressed by the tooling. The restore of the dependencies not working without clearing the cache was an unexpected problem.

But with the work of migration behind me I’m ready to move on. I’ve reached the acceptance stage on my project.json grieving process!

Anyone new to ASP.NET Core, using it for the first time in Visual Studio 2017 will probably look at older blog posts and wonder what we were all moaning about. The csproj is a great improvement on what we had in the past, so if you’ve never seen project.json, there’s nothing to miss and only improvements to enjoy.

Visual Studio 2017 is Released Reflecting on the loss of project.json and looking ahead to the new VS 2017 experience

Visual Studio 2017 is released today and I thought it was a good time to reflect on my thoughts about one of the main changes it brings for ASP.NET Core developers. This won’t be a detailed features post, as I’ve only tried the RC a few limited times. Due to some bugs and issues I experienced, I ended up removing the release candidate from my PC and only recently installed the latest more stable version. I plan to begin working with Visual Studio 2017 as soon as possible so I can start to explore the benefits it offers. A few of the new features and tooling enhancements have caught my eye and I’m keen to experience them first hand.

The big change for anyone who has worked on ASP.NET Core projects to date, is the the loss of the project.json format and the move back to a revised and improved csproj format. It’s a decision which caused a lot of reaction when it was first announced and since then has been a common topic of conversation for ASP.NET developers. I’m a fan of project.json format. I found it easy to use, simple to work with and a nice step forward. Personally I would prefer we weren’t loosing it entirely and that the tooling had been developed in a way that could support both formats. Pragmatically I can understand some of the reasons behind the change. Large customers, with heavy reliance on and experience of MsBuild for example, I’m sure would have avoided any use of ASP.NET Core without this compromise being made. Ultimately I am accepting of anything which can allow ASP.NET Core to gain more traction and become the framework of choice for C# based web developers. I do however, find myself a little concerned with the way the news of the change has impacted the first impressions of some people about ASP.NET Core. In a introduction to ASP.NET Core talk I’ve recently presented, it was odd having to avoid too much detail on project.json because I knew it would soon be a thing of the past. Explaining to people that they need to know this now, but don’t get too invested in it as it’s soon obsolete was hard. It was especially confusing for people to be shown the newest version of ASP.NET that already due quite a radical change.

In part due to it’s open development and partly due to this latest change, some people I’ve talked to are left a bit afraid of taking on ASP.NET Core right now. They have the impression it’s not finished, hard work, changing too frequently and ultimately not a safe choice for new projects at the moment. I don’t share these views myself; but I think that it’s partly because that I’ve worked with ASP.NET Core from around the beta 8 time frame. I’ve used it a lot during that time and even have a production system nearly ready for launch which is based around ASP.NET Core API microservices. I’ve seen firsthand the ease of use and enhancements it offers, so I am able to see how those benefits outweigh the bumps along the way. But if new developers are left apprehensive by the strong opinions being shared and the breaking changes, that does worry me a little. I truly hope this is the last of the big forced changes we should expect to the fundamentals of the technology and we can move forward, embracing the future of ASP.NET Core. I certainly wouldn’t and haven’t for the last few weeks promoted starting a new ASP.NET Core project in VS 2015 but at least with today’s launch, we finally have the RTM tooling to be able to move forward with ASP.NET Core and csproj. For any concerned developers reading this post, I think with VS 2017 we should be in the right place to really start making ASP.NET Core the first choice for new projects.

An important fact to state here is that the tooling for ASP.NET Core has always remained in preview. Despite .NET Core and ASP.NET Core being released back in June last year, under full support, we’ve been told that tooling would RTM at a later date. Many of the early adopters to ASP.NET Core would have experienced some pain and glitches with the earlier versions of the preview tooling, although in the latest versions, I’ve had a much more stable experience. My assumption, and I think that of many other developers was that by investing in ASP.NET Core on Visual Studio 2015 early on, we would eventually get some form of RTM tooling in that IDE. However, at the end end of January I picked up on a comment from Damian Edwards during the ASP.NET Community Standup. What I thought I’d heard was that we would never get final supported tooling for Visual Studio 2015.

Puzzled and unsure of my interpretation of his statement, I reached out to Damian on Twitter. Here is the start of the Twitter thread. In summary, I learned that the decision being made was apparently clear. VS 2015 tooling and project.json would never formally RTM and be supported. Anyone with a project.json project would need to upgrade to Visual Studio 2017 at release or use VS code in order to access the supported RTM tooling for ASP.NET Core running on csproj. As Damian explained it, the csproj changes required core IDE changes in Visual Studio 2017 to be possible. These changes would not / could not be brought back into VS 2015. This is where I start to feel a little left out in the cold by Microsoft. Fair enough, the tooling was preview, but we’ve backed the new and supported ASP.NET Core early, with the direct assumption we had a path forwards on the existing IDE version. Would I have started so early with a production system using ASP.NET Core if we had known our team will need to plan and handle a move to VS 2017 to gain tooling support? Perhaps not. I’m still a huge supporter of the new framework and we’re able to run our services inside Docker, on Linux, which has some great advantages for us. The deployment possibilities this has opened up to us is a key advantage of ASP.NET Core and one I hope to explore on this blog soon. Perhaps it’s just me that missed the point until quite late that the csproj change essentially made ASP.NET Core a VS 2017 product only.

A good demonstration of how the change effects early adopters is with open source projects such as the Humanitarian Toolbox allReady project, to which I contribute regularly. Here we have a real-world ASP.NET Core application which started it’s development way back in the early days of ASP.NET Core. allReady has moved through the various beta, release candidate and finally RTM versions of ASP.NET Core. A journey which has been complicated and painful at times due to some breaking changes. It was an accepted journey, given we were working with software still under development, and while I don’t think anyone expected quite so many twists and turns, the team ducked and weaved through them. The issue of the demise of project.json along with the Visual Studio 2017 release, does pose some logistical issues for the project team though. We’re actively discussing in an issue how and when we want to make the switch by migrating to csproj. We’re slightly stuck between a rock and a hard place. On one hand, we’re on unsupported tooling and also run the risk of new contributors opening the solution in VS 2017 and being migrated too early – leaving them unable to commit back to the project. On the other hand, if we migrate now, do we risk loosing contributors who aren’t in a position to, or willing to, upgrade to Visual Studio 2017 at this time? Agreed, they can still use VS Code or a community edition of Visual Studio 2017 if the concern is around licensing, but this still puts constraints on the ease of entry which we very much try to avoid. With allReady we’ll have to migrate fairly soon to avoid contributors who move to VS 2017 and don’t keep VS 2015 installed side-by-side from finding themselves unable to contribute any further. 

I feel slightly aggrieved that despite using the LTS supported version, we’re forced into a full IDE version upgrade in order to continue using that version. It slightly blurs the lines of how I feel a supported product should work. Microsoft have chosen the safer and arguably easier road for themselves which is to avoid putting even a basic and time limited project.json tooling experience into the wild under some form of support. This would have provided greater time for teams to embrace and migrate to csproj at their own speed. The project.json format is a really key part of the structure of ASP.NET Core projects built to date. Simply pulling that piece out from under the earlier adopters doesn’t sit quite right with me. I’m sure many discussions were had, compromises agreed, management decisions made that led to the final agreement to in effect, force the rapid death of project.json. Putting my Microsoft hat on, I can see why this makes things a lot easier for them in the long run. I’ve been fairly accepting of the churn we saw during the final phases leading up to RTM for ASP.NET Core, appreciating that in the end it was to give us a more suitable final product. This has been the one issue that I find myself less able to accept without a little annoyance clouding my thoughts. It’ll be nice to just get it behind us now and move forward without having to consider an impending change around the corner.

One key thing I’m conscious of loosing with the new csproj format is the simplicity of debugging into the ASP.NET source code. Currently a simple addition to the global.json file allows us to include the source into a solution, instead of using the Nuget supplied package. This has been something I’ve taken advantage of many times to learn more about the internal workings of MVC for example or to understand why my application is behaving in a certain way. I believe some level of support is being looked at to keep this functionality and an open and current discussion is ongoing on GitHub to continue to enable a source debugging experience. Initially this doesn’t sound quite a simple and painless as the solution I’ve been able to use to date. I hope we can get to a point where debugging the source is similar to the experience that the current json based format supports.

So, there you have it, my thoughts around project.json laid bare for (probably) a final time as the much loved project.json file moves closer to being a short lived part of .NET history. Visual Studio 2017 is pretty much the final and definitive nail in its coffin. While I have a slightly bitter taste in my mouth, don’t get me wrong, I’m still massively excited by ASP.NET Core in general and thankful that Microsoft are putting great effort into building an open platform for the future. I’m already excited about version 2.0 and I’m also keen to start working with Visual Studio 2017 both at home and at work. I expect to start doing so over the coming weeks and something I’ll be experiencing is how a real-world migration to csproj works.

Looking to end on a more positive note – besides the csproj issue – I am looking forward to VS 2017. Here are just a couple of initial features that I like the look of in Visual Studio 2017 from the information I’ve seen so far.

  1. The new, more rapid installation process does sound nice. Granted, once installed I don’t find myself doing installs too often, but it does seem to simplify the removal footprint as well.
  2. Various other performance related improvements and new configuration options promise to make working with solutions faster and easier than ever before. It’ll be interesting to see if those are noticeable or not.
  3. The new Git integrations within VS 2017 look nice. Any time I can save by not having to switch out of Visual Studio is very welcome.
  4. Live unit testing is a feature which I would like to take advantage of. Limited to the Enterprise license though, this may not be seen by everyone. It offers the continuous running of unit tests in the background, giving instant feedback on breaking changes as code is written. This sounds like it will improve productivity and generally make working on complex projects an easier experience.
  5. Finally I like the concept of the Code Style feature, which looks to allow a project level specification of coding standards that should be applied. Any deviance from the standards will result in compiler warnings to help developers quickly remain consistent. This feels like a nice enhancement to keep teams using a common structure in their code which can only help readability between team members. It’ll be interesting if this can assist with open-source projects like allReady as well.

Over the coming weeks I’ll be trying out the features that are available to me, and hopefully reaping the benefits they bring. After reading this post you could be forgiven for thinking I’m against VS 2017 or raining on it’s parade, but that’s not the case. I am always excited about new versions of products like this, and Visual Studio 2017 is no different. It promises to bring some great new features to developers everywhere. For me, my excitement is only slightly reduced by the gripes I have with the ASP.NET Core tooling but I’m hoping this is the final large piece of pain developers can expect on the early ASP.NET Core adoption path. I guess to end this post I’ll simply say – thank you project.json, you’ve been great!

R.I.P project.json – Out with the new, in with the old An early look at the VS 2017 csproj changes

Okay; the title of the post is a bit tongue in cheek! Since it was first announced that the new project.json format (developed by the ASP.NET Core team) was going to be retired in favour of the more traditional csproj file, the .NET community have had some very strong opinions. These have been shared on Twitter, in blog posts, on GitHub and via any other channels people could find. I will admit that when I heard about the change, I initially had some of the same views and concerns. Why would Microsoft take away my beloved project.json? However, I decided to wait it out and see what Microsoft actually produced before passing judgement.

A little bit of history

Let me take a step back here and try to explain a little bit of the history as I have understood it. In the early beta timeframe for ASP.NET Core (then called ASP.NET 5) the ASP.NET and .NET teams were working independently of one another. The .NET team were working heavily on the API surface for .NET Core, whilst the ASP.NET team were working on the ASP.NET Core application platform on top of the API the .NET team were making. The tooling to work with ASP.NET Core was in an early preview and at the time we had DNVM and DNU commands. These have since been consolidated and morphed to form the dotnet CLI.

In order to support development of ASP.NET projects, the team decided to take the opportunity to develop a brand new project file format. One which would be simpler and address many of the issues the community had experienced when working with csproj based projects. At the time, nothing existed specifically for .NET Core projects and it was felt that since ASP.NET Core represented a new beginning for the platform, it was as good a time as any to make changes. During the betas and release candidates people started to get their hands on the new project.json and xproj based solutions when building their web applications. The response was indeed very positive. project.json provided autocomplete of dependencies, ease of reading and a much simpler overall structure.

Personally, I was very pleased when project.json was born. I could easily understand it and it became a regular reference point to review my dependencies and manage my projects.

However, it was during the release candidate period that decisions started to get made around a wider .NET project format for the other application types. Customers were starting to share their concerns around project.json and the fact that it was not supported within MSBuild. What would this mean for large monolith projects, how would they even begin to migrate them to .NET Core? And, being fair, these were valid concerns. Starting with greenfield ASP.NET Core projects was fantastic. There was no need to concern ourselves with the past and the new new project.json was easy to get to grips with. But, working with an existing project would not necessarily be a simple conversion without some degree of work. So the announcements started to be made that project.json would be retired in favour of a more backwards compatible MSBuild ready, csproj format. It was too late in the day for this work to be completed before the RTM of ASP.NET Core 1.0 but we were warned that it would be worked on for release alongside Visual Studio 2017.

And that brings us to today, with the announcement of the release candidate for Visual Studio 2017 we can now get our hands on projects using the new (or should I say old) csproj project format. I’ve taken an early peek at the file to see what has changed.

Comparing project.json (VS 2015) with csproj (VS 2017 RC)

Microsoft have assured us while working on the change that they expected to port many of the improvements that the project.json file gave developers over to the improved csproj format.

Comparing project.json and the new csproj

In the screenshot above (hard to see due to the size) I’ve opened a default new Web Application project in VS 2015 (left) and VS 2017 (right). Side-by-side the obvious difference in that project.json is JSON and the csproj is XML. You will notice that the line length of the files is not too different. project.json comes in at 65 lines and csproj comes in at 77 lines. Already that is a significant reduction in lines from a traditional csproj file.

Here are the complete files:

The other thing which stands out to me is the readability. Despite the work Microsoft have done to reduce noise in the csproj file, I still find it much harder to scan than the project.json. The XML tags draw my eye away from the detail that I actually want to consume.

At the time of writing I’m still very new to working inside VS 2017 and indeed on my computer it’s proofing quite buggy. For example, a solution that I created inside VS 2017 and which had been working fine (1 web application and 1 test class library) no longer re-opens after I saved and closed it. Suffice to say, I won’t be using Visual Studio 2017 for production work at this time and may even remove it entirely as it seems to be affecting my experience inside VS 2015 too.

Once nice advantage of the csproj file over the project.json is that we can now include references to full (non-core) .NET projects as well. Previously the integration was not available.

Something I do miss however (unless it’s just not working for me) is proper autocomplete of the packages and versions. With the project.json I could start typing the name of a dependency and Visual Studio would show me potential autocomplete options. I could also choose from the available versions. This seems to be absent in the csproj file. Personally I only saw basic intellisense for some, but not all, of the xml tags.

Migrating from project.json

Migration from project.json can be achieved in one of two ways. These easiest is to open the existing xproj/project.json project inside Visual Studio 2017. The IDE will detect the project format and prompt for a migration. The other option is to run the dotnet migrate command directly in the command line. This should result in the same conversion.

Migration from project.json

In a quick test for me, the VS migration seemed to work quite well, although that was a single default web application project with basic dependencies. In theory it should work just as well for larger projects. Perhaps when we come to migrate the allReady project which I contribute to, we’ll see if there’s more to it.

Having done this with the project.json solution created in VS 2015 (as appeared above) we get the following csproj output.

Inside the project.json we have our main dependencies section and inside that we define the package and version. This is pretty clear and easy to read. Inside the csproj each package reference is added inside an ItemGroup element. It’s more verbose than the project.json.

Much of the content is similar and when you compare the files you can generally find where each part has been migrated. However you’ll need to remember the more complex XML schema in order to edit the file manually. Indeed, Microsoft seem to be pushing us away from this in favour of IDE tooling and the command line. I fear though, that those are never going to be as quick to work with as we’ve been used to with a quick edit of the project.json file.

Differences between the original csproj and the new csproj

There are some other notable changes between what we see in a traditional csproj file when compared to the newer csproj file. Firstly they have gotten rid of the use of GUIDS within the file, so that it is much more human readable. That’s a good change and one I’m happy to see.

We are no longer required to include all of the files within the csproj file in order for them to be considered part of the project. project.json gave us a much more favourable, include by default, behaviour and this has now been made available inside csproj. It’s ever so slightly different as we must use a wildcard style include line to tell the project to behave this way. New projects created inside VS 2017 have this by default. When working with teams of developers, the csproj file was a common area of merge conflicts. We should no longer have so many issues since the project file will not change simply because we’ve added new files to the project.

Package references are now integrated into csproj so this single file also includes any libraries our project is dependent on and any projects we reference. It’s nice to have everything in one place as we’ve become used to with the project.json format.

Another important change is that we can now edit the csproj file whilst the project is loaded. This was not previously possible and meant that any manual changes were slow to make as we had to first unload the project. Granted, it was rare that I wanted to manually edit the file in the full .NET framework days. To edit the csproj file we can simply right click on the project without unloading it first.

Edit csproj inside VS 2017

One gripe at this point that I experienced is a warning for inconsistent line endings every time I edit the csproj file.

Inconsistent line endings

Other project differences in VS 2017

As well as the direct differences inside the file, there’s a few initial tooling differences I wanted to highlight between VS 2015 and VS 2017 that I’ve noticed.

The main one I’ve seen so far is the consolidated dependencies folder. Before, we had a “References” folder which included any dependent libraries we added via Nuget and any project references. We then had a “Dependencies” folder which included Bower dependencies. Inside Visual Studio 2017 these have been placed together inside a single “Dependencies” container. Project references have their own sub-container to separate them from the Nuget dependencies.



Initial Impressions

I definitely don’t find the XML as readable as the JSON for reviewing the configuration of my project. This will improve with time as I get used to it, but there’s still too much noise in the file for my liking. It’s certainly a big improvement on the traditional csproj format though and the wildcard include of files is an important enhancement.

Personally, I still much prefer the project.json format and whilst I understand the business case the led Microsoft to their change of course, I feel it’s a shame the MSBuild system couldn’t have moved with the times, rather than dropping back to the xml based project file.

The lack of autocomplete for dependencies bothers me too. This was really handy and I could quickly build up my dependencies without having to open up the Nuget package manager each time. It feels like we’re now being forced down that route which proves to be a bit slower and less efficient.

It’s still very early days and I need to spend more time with the new version of csproj in a final stable version of VS 2017 before passing a final judgement. We also have to remember that the .NET SDK tooling is not quite fully baked yet either. At this early point I’m running into quite a few issues running VS 2017 so it’s hard to fully appreciate the final experience.

The Microsoft statements suggest that in reality the tooling and command line interface should negate the need to spend much, if any, time editing the csproj manually. Once everything is complete we will be in a better place to judge for ourselves. I can’t help but assume things will end up being slower overall and that I’ll end up missing the ease of the project.json file.

Update 23rd Nov 2016

After reviewing I can see that the format for the new csproj that I have experienced in VS 2017 RC doesn’t match the example of what I presume is the end goal. So it’s entirely possible that the structure will evolve even more before release. The example in the MSDN blog does look cleaner and much less cluttered so I will watch this space with interest.

Update 7th March 2017

Further reflection on the changes and the way it has been handled in my post – Visual Studio 2017 is Released – Reflecting on the loss of project.json and looking ahead to the new VS 2017 experience