Where can I find some actual getting started examples?


I am just in the process of releasing an open source project that makes using cryptography very easy. The code all runs on Windows under .NET 4.6. Source is available at:


How do I get started running the code on Linux or OSX? All I can find are the ‘ten minutes’ examples on dotnet.github.io.

Now please don’t take this the wrong way but I have been a computer professional over 35 years now. I am very active in IETF, I was one of the contributors to the original HTTP specification. I have been using .NET since the earliest release. And those examples don’t mean a damn thing to me. Absolutely nothing. Yes, bootstrap makes them look good but I have no idea what the context is. Am I supposed to type them into the command line? If so it didn’t work. Is Visual Studio Code involved? There is no hint.

And no, the examples do not run. Not even close. I have no idea what is going on.

What I am looking for is a guide that tells me how to configure an OSX or Linux box so that it will run code that passes the portability analyzer in Visual Studio 2015 Community Edition.


@Phill_Hallam_Baker sorry that you’ve had trouble finding what you need. Docs and samples are still very much a work-in-progress at this time. We will eventually have an article which covers how to port existing libraries to .NET Core, but for the time being hopefully I can help you out here.

It sounds like you’re interested in targeting both .NET Framework and .NET Core (therefore supporting Linux and OS X). If so, here’s a quick rundown of what you’ll need to do:

  1. Run the API Port tool to determine portability of the current project
  2. Analyze the generated report to see if you can provide any workarounds for incompatible APIs used (if any)
  3. Move any tests over to either Xunit or Nunit (MSTest doesn’t support .NET Core)
  4. Choose a project type (csproj or xproj) for any projects in the library
  5. Port code over to the new projects and run tests, one project at a time

Taking a brief look at your code, none of the client projects will be able to work because .NET Core doesn’t support Windows GUI frameworks. You’ll also have to move away from MSTest and over to either Xunit or Nunit. If that doesn’t inhibit you, I’d say it’s worth using the API Port tool to see what’s compatible.

Here’s a more detailed breakdown of what you’ll need to do if you want to try moving forward:

  1. Use API Port to determine any API incompatibilities. This will allow you to decide if you can target .NET Core at this time by giving you a breakdown of each assembly generated when you build your project.

    • Download the tool here and extract somewhere. Open a command line (I used PowerShell) in the extracted location.
    • Instructions here will be helpful. When I used this to port a service, I used the following command to output the report as HTML, which I read in a browser.
      PS> .\ApiPort.exe analyze -f <path_to_\bin\Debug_of_project> -t ".NET Core, Version=5.0" -t ".NET Framework" -r HTML
  2. If you’ve determined that you can target .NET Core with your library, you’ll need to decide how to approach your project structure. You’ll need to pick one of the following.

    • modified csproj-based project(s) with support for project.json, documented [here].(https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/getting-started-core.md).

    • xproj-based library projects (known as Class Library (package) in Visual Studio).

    • Note that you must commit to one or the other fully. You cannot reference a csproj assembly from an xproj or vice/versa. When I ported a service, I went with xproj over the modified csproj, but you may find it easier to go with the modified csproj.

  3. Define an order in which you’ll port projects and begin porting each one. This will also require modifying the project.json file.

This example project.json supports .NET Framework 4.5.2, 4.6, and .NET Core:

      "net452":{   <--- Braces can be left empty for simple projects, but generally you'll need to specify framework assemblies
            "System.Net.Http":""   <--- Example of an API you need to specify here
      "dotnet54":{   <--- .NET Core Dependencies listed under here, as NuGet Packages
               "System.Threading.Tasks":"4.0.0-rc1-*"   <--- Example version number, VS will pick the right one for you

You may also have a dnxcore451 attribute in your project.json generated by Visual Studio - I’d suggest deleting it and simply using the net46/net45/etc attribute(s) to represent each target platform you wish your library to target.

There’s some more detail in this article that’s near completion. Hopefully there’s info in there you find helpful. Although it focuses on command line tooling, information about how the project.json files should look holds true for using Visual Studio as well.

Marc Gravell also has an excellent blog post about migrating an existing library of his over to .NET Core with DNX tooling.

Hopefully this is helpful! I’m happy to answer further questions you may have.

.NET Foundation Website | Blog | Projects | Code of Conduct