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.

dependenciesfoldervs2017_1

dependenciesfoldervs2017_2

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 https://blogs.msdn.microsoft.com/dotnet/2016/10/19/net-core-tooling-in-visual-studio-15/ 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