.NET Core 3 for Windows Desktop
Intro
In September, we released .NET Core support for building Windows desktop applications, including WPF and Windows Forms. Since then, we have been delighted to see so many developers share their stories of migrating desktop applications (and controls libraries) to .NET Core. We constantly hear stories of .NET Windows desktop developers powering their business with WPF and Windows Forms, especially in scenarios where the desktop shines, including:
- UI-dense forms over data (FOD) applications
- Responsive low-latency UI
- Applications that need to run offline/disconnected
- Applications with dependencies on custom device drivers
This is just the beginning for Windows application development on .NET Core. Read on to learn more about the benefits of .NET Core for building Windows applications.
Why Windows desktop on .NET Core?
.NET Core (and in the future .NET 5 that is built on top of .NET Core) will be the future of .NET. We are committed to support .NET Framework for years to come, however it will not be receiving any new features, those will only be added to .NET Core (and eventually .NET 5). To improve Windows desktop stacks and enable .NET desktop developers to benefit from all the updates of the future, we brought Windows Forms and WPF to .NET Core. They will still remain Windows-only technologies because there are tightly coupled dependencies to Windows APIs. But .NET Core, besides being cross-platform, has many other features that can enhance desktop applications.
First of all, all the runtime improvements and language features will be added only to .NET Core and in the future to .NET 5. A good example here is C# 8 that became available in .NET Core 3.0. Besides, the .NET Core versions of Windows Forms and WPF will become a part of the .NET 5 platform. So, by porting your application to .NET Core today you are preparing them for .NET 5.
Also, .NET Core brings deployment flexibility for your applications with new options that are not available in .NET Framework, such as:
- Side-by-side deployment. Now you can have multiple .NET Core versions on the same machine and can choose which version each of your apps should target.
- Self-contained deployment. You can deploy the .NET Core platform with your applications and become completely independent of your end users environment – your app has everything it needs to run on any Windows machine.
- Smaller app sizes. In .NET Core 3 we introduced a new feature called linker (also sometimes referred to as trimmer), that will analyze your code and include in your self-contained deployment only those assemblies from .NET Core that are needed for your application. That way all platform parts that are not used for your case will be trimmed out.
- Single .exe files. You can package your app and the .NET Core platform all in one .exe file.
- Improved runtime performance. .NET Core has many performance optimizations compared to .NET Framework. When you think about the history of .NET Core, built initially for web and server workloads, it helps to understand if your application may see noticeable benefits from the runtime optimizations. Specifically, desktop applications with heavy dependencies on File I/O, networking, and database operations will likely see improvements to performance for those scenarios. Some areas where you may not notice much change are in UI rendering performance or application startup performance.
By setting the properties <PublishSingleFile>, <RuntimeIdentifier> and <PublishTrimmed> in the publishing profile you’ll be able to deploy a trimmed self-contained application as a single .exe file as it is shown in the example below.
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>netcoreapp3.0</TargetFramework>
<PublishSingleFile>true</PublishSingleFile>
<RuntimeIdentifier>win-x64</RuntimeIdentifier>
<PublishTrimmed>true</PublishTrimmed>
</PropertyGroup>
Differences between .NET Framework desktop and .NET Core desktop
While developing desktop applications, you won’t notice much difference between .NET Framework and .NET Core versions of WPF and Windows Forms. A part of our effort was to provide a functional parity between these platforms in the desktop area and enhance the .NET Core experience in the future. WPF applications are fully supported on .NET Core and ready for you to use, while we are working on minor updates and improvements. For Windows Forms the runtime part is fully ported to .NET Core and the team is working on the Windows Forms Designer. We are planning to get it ready by the fourth quarter of 2020 and for now you can check out the Preview version of the designer in Visual Studio 16.4 Preview 3 or later. Don’t forget to set the checkbox in the Tools->Options->Preview Features->Use the Preview of Windows Forms designer for .NET Core apps and restart the Visual Studio. Please keep in mind that the experience is limited for now since the work on it is in progress.
Breaking changes
There are a few breaking changes between .NET Framework and .NET Core but most of the code related to Windows Forms and WPF areas was ported to Core as-is. If you were using such components as WCF Client, Code Access Security, App Domains, Interop and Remoting, you will need to refactor your code if you want to switch to .NET Core.
Another thing to keep in mind – the default output paths on .NET Core is different from on .NET Framework, so if you have some assumptions in your code about file/folder structure of the running app then it’ll probably fail at runtime.
Also, there are changes in how you configure the .NET features. .NET Core instead of machine.config file uses <something>.runtimeconfig.json file that comes with an application and has the same general purpose and similar information. Some configurations such as system.diagnostics, system.net, or system.servicemodel are not supported, so an app config file will fail to load if it contains any of these sections. This change affects System.Diagnostics tracing and WCF client scenarios which were commonly configured using XML configuration previously. In .NET Core you’ll need to configure them in code instead. To change behaviors without recompiling, consider setting up tracing and WCF types using values loaded from a Microsoft.Extensions.Configuration source or from appSettings.
You can find more information on differences between .NET Core and .NET Framework in the documentation.
Getting Started
Check out these short video tutorials:
- Getting started with WPF on .NET Core
- Getting started with Windows Forms on .NET Core
- Differences between .NET Core and .Net Framework and what to choose for your application
Porting from .NET Framework to .NET Core
First of all, run the Portability Analyzer and if needed, update your code to get a 100% compatibility with .NET Core. Here are instructions on using the Portability Analyzer. We recommend to use a source control or to backup your code before you make any changes to your application in case the refactoring would not go the way you want, and you decide to go back to your initial state.
When your application is fully compatible with .NET Core, you are ready to port it. As a starting point, you can try out a tool we created to help automate converting your .NET Framework project(s) to .NET Core – try-convert.
It’s important to remember that this tool is just a starting point in your journey to .NET Core. It is also not a supported Microsoft product. Although it can help you with some of the mechanical aspects of migration, it will not handle all scenarios or project types. If your solution has projects that the tool rejects or fails to convert, you’ll have to port by hand. No worries, we have plenty of tutorials on how to do it (in the end of this section).
The try-convert tool will attempt to migrate your old-style project files to the new SDK-style and retarget applicable projects to .NET Core. For your libraries we leave it up to you to make a call regarding the platform: weather you’d like to target .NET Core or .NET Standard. You can specify it in your project file by updating the value for <TargetFramework>. Libraries without .NET Core-specific dependencies like WPF or Windows Forms may benefit from targeting .NET Standard:
<TargetFramework>netstandard2.1</TargetFramework>
so that they can be used by callers targeting many different .NET Platforms. On the other hand, if a library uses a feature that requires .NET Core (like Windows desktop UI APIs), it’s fine for the library to target .NET Core:
<TargetFramework>netcoreapp3.0</TargetFramework>
try-convert is a global tool that you can install on your machine, then you can call from CLI:
C:\> try-convert -p <path to your project>
or
C:\> try-convert -w <path to your solution>
As previously mentioned, if the try-convert tool did not work for you, here are materials on how to port your application by hand.
Videos
Documentation
- Simple porting case
- Advanced porting case (Part 1, Part 2)
- Overview of the porting process
Light
Dark
91 comments
I had to leave a comment on this article since I want any of MS developers in charge of this framework could see those opinions.
What is the very irreplaceable values of this .NET Core? Why MS made this .Net Core with spending their resources?
Sorry if I’m wrong, but I think it’s to make framework which can be used regardless of operating system.
For example, will developers who makes GUI program based on WinForms or WPF use .Net Core? I don’t think so. There’s no reason for them to leave .NET Framework to use this “new” “Core” something. There’s already “mature framework” to use WinForm, WPF, UWP on Windows.
Yes I’ve seen a number of reason why .NET Core team is not going to implement WinForm and WPF for non-Windows out of DirectX, WinAPI issue. But then “they shouldn’t” implement those GUI framework on .NET Core because those reason directly comes to conflict with why .NET Core exists.
Everyone regards .NET Core as cross-platform framework based on C#. If it isn’t, there’s no benefit to use this “newborn” environment and it’s huge loss of Man/Month for MS and open source community. So it would be nice of MS development team to reconsider this issue with care.
Thank you.
You already can make gui application regardless of the os. What bringing wpf will bring except spending Money and divide the community.
One of the goal off. Net core was to unify the community. So making wpf or winform cross plate-form is against the idea of dotnet core. But one thinks important is dotnet core was made in the beginning for asp. Net…
Thank you for the comment! You are right if you think of .NET Core as just a cross-platform alternative for .NET Framework. And that was true in the past but our vision of .NET Core has changed. Now .NET Core is the platform that will move forward unlike .NET Framework that will stay where it is (with version 4.8). So if we did not bring desktop stacks to .NET Core, desktop developers would never be able to use anything new that will come in the language, runtime and so on. That is including C#8 and further, performance improvements, deployment flexibility, etc.
Besides desktop is available as a separate workload that you install only if you need it, there are no reasons to worry about desktop making .NET Core “heavier” for non-desktop applications.
What I still don’t understand though is why exactly Windows Forms can’t work cross-platform. I understand in theory that it’s very close to the way Windows manages forms, but I understand in practice that I have a couple Raspberry Pis in my household displaying .NET Windows Forms running on Mono.
Mono did the work to build up a framework that can render the WinForms components on whatever window manager/display server Linux is using on your Pis. For WinForms/WPF to be cross-platform beyond Windows, Microsoft would need to create (and support) a similar framework for each window manager on Linux (or at least the most popular ones) and MacOS.
And possibly Android and iOS. Which brings me to Xamarin already existing and serving part of this need, and other community projects (shoutout to Avalonia, which is a bit more WPF-like than Xamarin). Why put in the huuge amounts of time and effort to build WinForms/WPF from scratch for those other platforms when there are already good, stable, and in-use equivalents that can be fostered instead?
Don’t waste your time trying to use these releases:
installed VS 2019 preview 16.4.29430.225
install does not create a desktop shortcut: the exe is hidden away in “C:\Program Files (x86)\Microsoft Visual Studio\2019\Preview\Common7\IDE\devenv.exe”
created a new WinForm App using Core 3
enabled the option in VS to use Core Preview WF designer: required restart.
re-started VS 2019 preview
15 minutes later, VS 2019 preview is still loading, Task Manager is showing a
ServiceHub.ThreadedWaitDialog process eating a lot of cycles.
We are sorry that you ran into this problem. We are working on Perf issues that we are aware of and we have several fixes going in for next release.
It will be really helpful, if you could report this problem using Visual Studio Feedback with more details so that appropriate team can look into this issue.
Thank you.
Maybe it’s just me, but all your renaming juggling act is just a mess of confusion.
I’m working for a company that uses .NET on the server and another which uses it on the client and with the transition to .NET 5 they are scared shtless. We are telling them that is a simple matter of switching to .NET Standard and that both .NET Core 3 and .NET Framework 4. adhere to it, but they tell us that they have looked into the APIs and see some serious missing pieces.
With all the change to .NET 5, they are even more confused, since they don’t know why there’s no .NET Core 4 or .NET Framework 5.
So we are just waiting for you to create .NET 5S and .NET 5X, just to be in line with all the madness inside MSFT.
Carlos, I can totally see how this can be confusing! 🙂
In 2020 we will merge all platforms in one with the name “.NET”. It will have the version number 5 to emphasize it is the latest among all the existing platforms: .NET Core (latest version 3.1), .NET Framework (latest version 4.8), … . In terms of porting to it, you can think of .NET 5 as the next version of .NET Core, it will be built on top of Core 3.1 with some additions of new features. There still might be some breaking changes. Hope this helps and happy to give more details or answer any questions on it.
Great comprehensive post, thank you. I will be referring my colleagues to this as a jumping off point.
Thank you 🙂
@Olia – It would be nice if you could post some examples on how to get PublishSingleFile / PublishTrimmed to work with the Desktop Bridge. We have a WPF app that we converted to dot net core (which is doing great btw! 😀 ) but the MSIX still contains a lot of assemblies that it doesn’t need, which causes delivery bloat. 🙁 We tried using the examples Orin posted on his Github but they don’t seem to work. It’s not a deal breaker by any means, but we’d like to be able to reduce the file size if possible.
Good blog post but the strategy is really confusing. So you want everyone to move to .NET Core because its cross platform BUT
I can’t take a WPF or Windows Form App and run it on Linux or Mac so I would have to build an entirely new UI
I can’t use CLI to take my native C++ code and reference it on Linux or Mac
I can’t update a Windows Form app because the designer won’t be ready for a year
I can’t really use Visual Basic with a visual designer or with ASP.NET Core or with mobile apps as an introductory program for new developers, so why does Visual Basic still exist?
-.NET Core is missing pieces of .NET framework so its actually a step back to develop a Windows app on the Core
UWP has a questionable path forward
Which leads one to question how you should even develop a C++ program with a UI on Windows these days if you don’t use QT?
So why wouldn’t I just use Java, Python, or C++ w/ 3rd party UI library for cross platform apps?
VS Code is written in node.js
I think that tells you everything you need to know about Microsoft’s desktop strategy. They don’t eat their own dogfood any more.
That’s revealing, indeed.
So you want everyone to move to .NET Core because its cross platform
No. First of all, we don’t want you to move if you are happy where you are. .NET Framework will be supported. The goal of this blogpost was to provide the information about the current and future development of the technologies so you can better plan your activities and choose what is best for your applications.
Also this “because its cross platform” is not at all what I was referring in the post:
“But .NET Core, besides being cross-platform, has many other features that can enhance desktop applications. …” and the full section bellow, where I give reasons one may choose .NET Core for their Windows-only applications.
Since we already responded to most of your points in the previous comments, just a few here:
– designer not available – the Preview is already out, some scenarios will already work, we are releasing updates every month and looking for supporting most of the scenarios by May 202
– .NET Core is a step back cause it’s missing pieces – .NET Core does not have parts that we consider outdated and has new technologies and APIs, so by all means it is a step forward. But if you want to use APIs available only in .NET Framework – you can stay on Framework, we will support it.
But I can see that you are probably looking for developing a new cross-platform application instead of supporting and enhancing existing WPF or WinForms app. This blog was mostly focused on WPF and WinForms on .NET Core. I’ll be happy to learn about your scenario and see if I can suggest something and definitely learn from your feedback for our future plans. If you’ll be up for a phone interview, please reach out to me on olia.gavrysh@microsoft.com
Olia wrote: “No. First of all, we don’t want you to move if you are happy where you are. ”
If you implement compelling, useful, new C# language features/facilities, but devs can’t use them unless they change to .NET Core (already happened, happening) … and, we are stuck with previews (that are fragile) for a year … do you think we will be “happy” ?
Provide a way to make a non-GUI Core project using C# 8 Core features, and then, reference, and use, the dll in a FrameWork WinForm or WPF, project ? Is that as impossible as it sounds ?
cheers, Bill
Hi, the problem we have is, the core is “published/announced” as cross-platform programmers like me (hobbiest) was hyped for writing “one code” for different platforms. e.g. VB.Net WinForms Applications running on Linux. Maybe it was a wording from MS but for the most of us have understand it that way. After you (Microsoft) changed your vision about cross-platform, as you said above, community are more tied because the left hand already not know that winforms is only for windows.
Will and Ismail make exactly my point. You can’t stay on .NET Framework because all the new feature development is on .NET core and the entire promise of .NET core is to be able to write one code and deploy anywhere. If Sun/Oracle/QT can have a common UI what can’t .NET?
Who knows on .NET Core either? Over the course of the almost 20 years I have coded on the Microsoft platform there have been so many go down this direction and it will be the future, only to find it completely abandoned a few years later. Examples include Silverlight, C++ Amp, J#, LINQ to SQL, Visual Studio R Tools, UWP, and now possibly VB entirely (if that is not the case I would challenge you to post a blog with a roadmap that allows it to stay relevant on modern platforms web/mobile). That is a list that makes it hard to sell others on the Microsoft platform.
I actually have a couple of WPF and Winforms apps that I maintain but what I would really like to do is run those on Windows and Mac. Ideally that would mean allowing .NET Core to have a common UI and allow CLI C++ to compile on other platforms.
Hi Olia, is the WinForms designer for .NET Core built into VS 2019 16.4 Preview 3 now? I’ve still got the “(Pre-release) .NET Core WinForms Designer” plugin installed from previous builds – do we still need to keep that installed, or is it no longer required?
HI Daniel, that is no longer required. You may uninstall it and instead use the Preview feature you find in Tools->Options.
Thanks Merrie 🙂
I have a question. I’ve installed preview 1 of the forms designer and I like it. If a preview 2 gets released will my IDE (VS 2019) automatically update to it or will I need to manually do the upgrade? I’m asking this because I’m afraid I might forget to check for an update.
You will get automatic updates with Visual Studio, no manual upgrades needed! 🙂 Just keep in mind that you need to be on Visual Studio Preview for the WinForms designer, since it is in the preview too. And don’t forget to enable the designer in Tools->Options->Preview Features->Use the Preview of Windows Forms designer for .NET Core apps and restart the Visual Studio.
Thanks for your prompt answer. I have submitted some feature requests using the feedback tool and am going to try submitting some minor ui bugs that I’ve been experiencing when placing items on my forms and moving them around. Also copying and pasting buttons doesn’t seem to work. When you double click for the new (pasted) button it takes you into the function for the old button (even if you’ve changed the name of the new button). Adding a new void in manually for the new button doesn’t work either. I ended up deleting my new button and just created it from scratch instead of using copy and paste. By the time you read this I will already have submitted this as a bug.
Will there be a control like the ASP FileUpload in the Windows Forms App (.Net Framework) and the file path reference will be like ~/folder ?