.NET Core 3 for Windows Desktop

Olia Gavrysh

Olia

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:

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

91 comments

Comments are closed. Login to edit/delete your existing comments

  • Avatar
    Ian Marteens

    “We are planning to get it ready by the fourth quarter of 2020…”

    … wait. Are you telling us you need another year for completing the WinForms designer? Wow!

  • Avatar
    Dominic Shaw

    This is great, thank you.

    What are the plans in regard to deployment? We currently rely heavily on ClickOnce. MSIL is more difficult to use than ClickOnce publish and I can’t find any notes anywhere on CD pipelines for MSIL. Is there anything you can point me at? We are just publishing LOB applications so it is all internal, no need for the Store or anything like that.

    • Avatar
      Daniel JacobsonMicrosoft employee

      You have several options for deployment. You can use the Windows Application Packaging Project to create an MSIX package which supports many of the features that ClickOnce has on recent versions of Windows 10: https://docs.microsoft.com/en-us/windows/msix/desktop/desktop-to-uwp-packaging-dot-net.

      An example of this project with an end-to-end .NET Core WPF application using CI/CD is available here: https://github.com/microsoft/devops-for-windows-apps

      You can use Installer Projects to create a .NET Core MSI. You can make everything fully self contained within the .exe and distribute that way. You can also look at other third party options for packaging and distributing applications.

      None of the above require you to upload to the Store, but MSIX packaging is the one that will allow you to upload to the Store if you ever do build applications that would make sense there.

      We’d be happy to chat more about your application deployment requirements and see if we can help. If you’re interested, please contact me at dajaco at microsoft dot com.

      • Avatar
        Dominic Shaw

        Apologies that is exactly what I meant – but I don’t see any resources for that with CD either. I don’t see any way to deploy that automatically with, for instance, DevOps?

  • Avatar
    Jack Bond

    “They will still remain Windows-only technologies because there are tightly coupled dependencies to Windows APIs.”

    For the love of ******* god, stop running surveys, actually listen to your customers, and DECOUPLE THEM.

    Seriously, whoever is making some of these decisions should have been fired ages ago. Imagine a Microsoft store for MacOS and a couple Linux distros, where you could distribute your cross platform XAML / .NETCORE app. I’d gladly give up 50 cents on the dollar.

    • Avatar
      Fabien Geraud

      There is xamarin, avalonia, uno, blazor, the winform like cross plate-form project I can’t remember the name, and many small project using wasm&electron or more low level. There is already a lot of solution to do what you ask. What the ecosystem will gain to do that exept trying to simplify porting application (I’m not even sure if it will be easier)

    • Daniel Neely
      Daniel Neely

      Winforms is a thin wrapper around native win32 controls. Porting it to mac/linux would be equivalent to writing a win32 implementation for those OSes. If you want to do that just run the exe with WINE.

      • Avatar
        Jack Bond

        Notice I said XAML. Microsoft already made XAML cross platform(remember Silverlight.) It’s complete ******* ******** that WPF is any more tightly coupled to Windows than the full .NET framework was. Someone has made a decision that allowing WPF to run on MacOS and Linux would be detrimental to Windows, so why spend the money? Just look at Azure, when given the choice, A LOT of people pick Linux. Heck, given the absurd licensing costs built into Windows VMs, if deploying Service Fabric apps to Linux was as simple as selecting from a drop down in a build pipeline, the Windows usage would probably crater even further.

    • John McCourt
      John McCourt

      That’s a lot of work, with a big financial outlay which may not pay for itself in the short term. As a Linux developer I’m quite happy with the direction that Microsoft is taking. It has to be a gradual process though, and I don’t expect everything to happen overnight. A bit of patience is necessary. Expecting everything right now is a little bit ‘entitled’.

  • Avatar
    kuo liu

    “They will still remain Windows-only technologies because there are tightly coupled dependencies to Windows APIs. “, Does “They” mean .NET Core? If that, .Net Core winform couldn’t be cross platform.

    • Avatar
      Kathleen DollardMicrosoft employee

      Visual Basic is not dead. We have brought most of the Visual Basic Runtime (Microsoft.visualbasic.dll) to .NET Core. We have not yet released templates for Visual Basic because we are not yet confident in our ability to provide an adequate Visual Basic experience.

      • Avatar
        jaroslavmitrovic@hotmail.com

        Hi.

        I would like to suggest to use the help of the “Windows Template Studio” Team.
        Especially Sybille, who was the nice Person, which contributed alot of VB Support into the Project.

        Maybe the other Team from “Template 10” could help, but I think there Focus is more on C#,
        but I think they could Jump in…

        I have a Video link of a fellow Forum member, how a C# Project is converted manually to VB .NET Core 3.

        But it is in german Language.

        If it is of interest I could put a link on a Reply.
        I don´t know if it is allowed to add a Weblink to a Video Portal Webpage in here.

        Sorry for my bad english and my typos, but you can keep them, it´s free… 🙂
        c.u. and Greetings from Germany

          • Olia Gavrysh
            Olia GavryshMicrosoft employee

            Also (will add from myself) – no need to apologize for “my bad English and my typos”. It is admirable you speak another language, besides your native, and express yourself so well. I am extremely thankful for everyone who gives constructive feedback, and the fact you do it in foreign language deserves a double thank you! 🙂

          • Avatar
            jaroslavmitrovic@hotmail.com

            Thank You dear Mrs. Gavrysh for these kind Words.

            On avarage I speak 4.45532 Languages (Of HumanLanguages) , if You combine all of them. 😉

            I am looking forward, to hear from Mrs. Dollard.

            Have a nice Day.

      • David Streeter
        David Streeter

        Microsoft have abandoned the ‘co-evolution’ strategy where VB was previously the equal of C#. We’re back to the bad old days of features being added to C# first, and then maybe if we are lucky VB catches up sometime down the track: https://devblogs.microsoft.com/dotnet/the-net-language-strategy/

        I have been a BASIC programmer since QuickBasic days and I strongly recommend you switch to C# (and TypeScript). Microsoft are struggling to keep .NET/C# relevant, let alone VB.

        The self-taught programmer path is Excel VBA -> VB.NET but then the road runs out. Microsoft should ensure the path keeps going by making it easier to transition to C# and JS/TS.

        One idea would be to add an ‘autocorrect’ feature to the C# IDE, so you type in VB code and it autocorrects to C#.

        The only major VB feature missing from C# is REDIM PRESERVE, which would be a good addition to C#.

        Also missing from C# are static variables inside a method (intentionally missing feature) and ‘With Object’ property access, but they are easy to do without.

  • Avatar
    Will Woo

    “In September, we released .NET Core support for building Windows desktop applications, including WPF and Windows Forms.”

    I would call what was released in September the equivalent of a movie preview where an initial white screen was followed by random images punctuated by static: as in “completely unusable.”

    “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”

    uhhh … where is one example of such a story for a Windows Form app with a rich GUI ?

    “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”

    In other words, Win Form devs, with a substantial investment in apps making use of existing MS and 3rd. party controls (which often use the Win API) are pretty much thrown under the bus (again … the previous bus being WPF, and the so-called “Modern” UI).

    Would I like to write (no-UI) libraries using Core 3 that exploited the latest C# features ? Oh, yes ! But, I have no way, evidently, to use those libraries with a Win Form app that uses today’s GUI controls: “game over.”

    In “programmer time,” 4th. quarter 2020 might as well be “never.”

    Bill Woodruff
    CodeProject Mentor
    CodeProject MVP, 2015, 2017, 2019

    • Avatar
      Jan Nedoma

      Exactly. I would like to know what the “user story” is, users who want to convert their WinForms apps to Core and never touch the UI again?
      Waiting a whole year for the designer is deeply disappointing.

    • Avatar
      Ian Marteens

      All this reminds me of Wolfgang Pauli drawing an empty square in a note, with the text: “this is to show the world I can paint like Titian. Only technical details are missing.”

    • Avatar
      Hall, Trevor

      Will: Agreed!

      Our team, which is part of a (massive) company (>50,000 employees) put “some money and effort” into porting our Windows desktop tools to .Net core 3.x this year, having believed that this would be delivered with full WinForms and WPF support by end of 2019.

      50% of our “test harness” code for many algorithms is “WinForms”, so:
      When this was not useable at core 3.0, we deferred the project (ignored it for 2 months) to wait for 3.1.
      We are now putting it on ice for another 9 months.

      This means: we have to do “9 months of merging” from the Framework code that we need to keep maintaining, when this comes back on-line with .Net 5.
      We are unlikely to use .Net core 3.0 or 3.1 in any of our Windows projects shipping in 2020. Since .NET 5 is not until near the end of 2020, and we need months to validate projects on new frameworks, our move to “core” won’t appear in shipping projects until well into 2021.

      This doesn’t match the rapid adoption pace as suggested in the article, at least for all teams that I work with.

      On cross platform:
      We gave up hope on anyone delivering this to us, so we rolled our own.
      We have “device independent” layers for our custom controls that render in WPF, HTML5, SVG, EMF and Bitmap.
      We can get the same presentation on Windows as on an android tablet for many items.
      There is no obvious reason why that cannot be done for WPF as a whole (if it is open source) as the “input data” is XAML, which (like HTML), does not seem connected in any way that I can see to a specific implementation for “Windows”.
      WinForms is possibly a bit more tricky to isolate as it is described more like a “win32 wrapper”, but nothing is “impossible”

      There are are questions on “why you would want multiple formats of apps”. Just run a survey: Some people “want apps and data on their Windows laptop”. Some “only accept cloud data and tablets” Etc. Some prefer these different technologies based on workflows, so: We absolutely need tools that work on many platforms, including UI.

      • Avatar
        Merrie McGawMicrosoft employee

        Hi Trevor,

        As you know, the WinForms runtime is fully functional, and we’re seeing very positive feedback for how it’s working. I’d love to know more about your scenarios with the test harnesses, because the WinForms .NET Core Designer already supports the main common controls, and we’re working hard to bring you container controls to help with layout of your forms in the next preview. So if your test harnesses are not using terribly complex UI or third party controls you may find that the support is sufficient for your needs.

        We’re working hard to get new features available with every VS preview that ships. Data binding, User Controls and support for third party controls are our long lead items at the moment but they’ll be coming as soon as we can get them done. If you aren’t using those features however, your company may not need to put the project on ice for a long time. And if you are using those features, I’d love to know which ones and how you’re using them in your test environment.

        Thanks,
        ~Merrie McGaw
        Principal Dev Lead for WinForms

        • Avatar
          Will Woo

          “the WinForms .NET Core Designer already supports the main common controls”

          Are you kidding: even using the latest VS 2019 Preview update, with a Core 3 WinForm project, the simplest WinForm ToolBox controls don’t work, or behave bizarrely. See mention of 4k screen below.

          The controls you drop on the Form … once you’ve manually edited Location to get them to show up on the Form … do not write their edited properties into the Designer.cs file; they’re not saved with the file.

          At design-time, controls, including Forms are not movable or click-drag resizable.

          On a 4k Dell laptop screen, settings of AutoScaleMode make no difference, and the design-time view is rendered at about 25% of the run-time view.

          These iterations are not usable: they should not be released as previews.

          I’ve already uninstalled the latest VS 2019 preview, and have no intention of paying attention to further developments with WinForm Core until next year … unless you want to hire me as a tester 🙂

          • Avatar
            Merrie McGawMicrosoft employee

            High DPI has always been a very tricky topic in the WinForms world and I’m sorry you’re running into these issues. Our testing hasn’t indicated anything of what you’re discussing, unless you’re working on a secondary monitor or a HDPI situation. I’d really love to see the logs of what’s happening on your system, because at this stage we haven’t been seeing things like not writing edited properties into the designer.cs file. That’s a key part of what we’ve been working to make happen for these early releases. If you’re willing, it would be super helpful to us (and to the WinForms on .NET Core community) to create a VS Feedback item when it’s happening so we can collect logs and understand what exactly is getting in the way of the basic scenario of dropping and editing a control.

            As for the HDPI related stuff, we are having to tackle that a little later so that we can get base functionality working first. But if we hear enough reports that this is blocking work then we may be able to prioritize it over some other scenarios.

            Thank you for the feedback and for trying out the designer!

        • Avatar
          Hall, Trevor

          Merrie,

          Thanks for your reply. Maybe you have some “much better” internal versions?

          Unfortunately, There is no “Paste image” in the forum.
          If there was, I think you would get a laugh out of it.

          I have a simple library with 2 forms.

          One of them is basically a pile of buttons arranged in the shape of the periodic table, with element names on it.
          There is not much more. A simple data grid, which shows the known isotopes when you click on a button, and a couple of numeric “up/down” text boxes. One of those boxes has the default value “10”.

          The box takes up maybe 6 inches wide by 5 high on a laptop.

          With .NET 4.7.1: I see a periodic table.
          With core 3.1: and all latest previews: I see a square, about 1 inch by 1 inch, with several red Xs, and the number 10.

          Most of my forms are like this.

          Some may use “Data Binding”. We have many custom items, that are probably user controls and not supported yet.

          We organize items with Group Boxes (doesn’t everyone)?
          Group box is not supported.

          So: out of maybe 50 forms, I have not yet found 1 that renders correctly in the designer.

          Obviously, I cannot offer code libraries like this for other teams to consume.

          There is (sadly) currently, no compelling reason to move any of our desktop software to .NET core.
          Our team has determined that this is “not ready for prime time”.

          I know people are “working hard”. The problem is:
          You can’t live in a house if the roof is not installed yet, despite all efforts in progress by the “roofers”.

          Thanks
          Trevor

    • Avatar
      Merrie McGawMicrosoft employee

      We totally understand the frustration with not having a fully functional designer right away. It’s just as frustrating for us – we want you all to have it and be working daily in WinForms on .NET Core (WPF/XAML designer is already fully working, their designer was architected in such a way that adding support for .NET Core was relatively straight forward).

      WinForms Designer was one of the original main components of Visual Studio back in 2000/2001. Our Classic Designer was architected before many of the current coding standards and best practices were created. In fact, I’d say the majority of the code we’re working with is 15-20 years old! We’re essentially having to crack open Visual Studio and insert a new window layer in it’s own new process that displays the .NET Core Form as you would see it at runtime. Then we have to create a way for the Core process to communicate with Visual Studio and vice versa. That is for ever single action the designer could perform (resize, change property, change locatiOn, etc). It turns out this is no small feat and every time we start working in a new area of the designer there are new and interesting challenges to get it to light up.

      In the meantime, the Core Designer that we’re previewing is functional for certain scenarios and the runtime is fully functional. Migrating existing code can be started now and we will continue to add functionality in every VS release. As @Olia mentioned we’re looking to have a stable and nearly complete release in the 2nd quarter of 2020, spending the summer and early fall polishing up . We are working closely with the various control vendors to ensure they’re prepared to support their control libraries as they’ll have to do some of the same rearchitecting we do.

      We’d love as many people to kick the tires on this early Preview and tell us how it’s going. When you encounter something that doesn’t work as it should, we’re asking folks to file VS Feedback so we know what things we need to focus on for each preview we ship. We’d also love to know what pieces of the Designer experience our customers are missing most so we prioritize those scenarios.

      We thank you all for your patience, and are super excited by the energy the community is showing around WinForms and the WinForms designer!

      ~Merrie McGaw
      Principal Dev Lead for WinForms

      • Avatar
        Jan Nedoma

        “When you encounter something that doesn’t work as it should” – how do we know what should work? Is there any list of supported/unsupported features? Know issues? Changed/added features for each release?
        I checked the initial (standalone) release and it didn’t even load my forms, because apparently it doesn’t support inherited classes at all. Is that intended? How should I know?
        Also, why is the preview tied to VS Preview now? Why not update the standalone release? I’m not sure I’m willing to install (and maintain) another instance of VS just to test the designer early, early, early preview.

        • Olia Gavrysh
          Olia GavryshMicrosoft employee

          yes, here is the Known Issues and the
          Release Notes for the Designer Preview 1 and we will publish the blogpost for the Preview 2 very shortly (after all the Ignite announcements).

          As for shipping with VS Preview – we received many asks from the users to be in-box so that they don’t have to do extra work of finding, installing and updating the designer separately. The goal is to have the same designer experience as it was for .NET Framework applications. I personally prefer to have 2 VSs on my box, because with the VS Preview I get the latest updates on all the components that are in preview including .NET Core, etc. That way I get the latest goodness of everything :).

          We really appreciate everyone who is testing the designer and leaving the feedback via VS feedback channel, it helps us a lot to find bugs and prioritize our work. I’m sorry the experience is not great for some of you, we, more than anyone, want to get the designer to the stable mature state as fast as possible, and the community has been a great help! Thank you!

          • Avatar
            Jan Nedoma

            Thank you. If I were to vote, please prioritize support for inherited forms and user controls. Without that the designer is pretty much unusable for me (and I imagine for a large percentage of real-world projects).

      • Avatar
        Will Woo

        “the Core Designer that we’re previewing is functional for certain scenarios”

        I believe you are well-intentioned, and, indeed, working hard on a difficult task; however, I must reply to a claim like this as I have replied to Olia’s claims:

        “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”

        on this thread: show me a working example.

        I suggest you get together with management-whoever, and make a decision to stop the release of previews that are so dysfunctional they are a waste of developers’ time.

        Right now, I have to regard the claims made about these updates as “propaganda.”

        cheers, Bill