diff options
| author | Daniel Plaisted <dsplaisted@gmail.com> | 2016-07-01 01:11:52 +0300 |
|---|---|---|
| committer | Stephen Toub <stoub@microsoft.com> | 2016-07-01 01:11:52 +0300 |
| commit | 79a7c578cce7cf82eb4c2bf6d0b0fb5dba2cb895 (patch) | |
| tree | ad6c095bf036bc1e99682022df739df07488841f /Documentation | |
| parent | 0f671aef0a82415b322e0ecfb639dcb959c670af (diff) | |
Add instructions for targeting .NET Core with MSBuild projects (#9403)
* Add step by step instructions for using MSBuild to target .NET Core
* Rearrange and edit instructions for targeting .NET Core with MSBuild
* Link to updated NuGet extension for VS, add instructions allowing PCL/dnxcore50 packages to be referenced
* Reformatting
* Update existing getting started instructions
* Change prerequisite to VS 2015 Update 3, which fixes error that AnyCPU isn't supported
* Add comments for MSBuild properties
* Recommend project.json for new projects
* Add CoreApp as another recommendation to start with
* Start with Console app template instead of portable library, use Microsoft.NETCore.App package
* Fix indentation
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/project-docs/getting-started-core.md | 85 | ||||
| -rw-r--r-- | Documentation/project-docs/pcl-targets-dialog-net46-aspnetcore10.png | bin | 0 -> 35612 bytes | |||
| -rw-r--r-- | Documentation/project-docs/target-dotnetcore-with-msbuild.md | 118 |
3 files changed, 120 insertions, 83 deletions
diff --git a/Documentation/project-docs/getting-started-core.md b/Documentation/project-docs/getting-started-core.md index 34bb33ddb8..4ee2817cd0 100644 --- a/Documentation/project-docs/getting-started-core.md +++ b/Documentation/project-docs/getting-started-core.md @@ -1,87 +1,6 @@ Getting Started Writing a .NET Core app and Class Library ========================================================= -These instructions are basic and a work in progress. They will be improving a lot over time. These instructions are current for Visual Studio 2015 Update 1. +For general instructions on how to get started with .NET Core, see the [.NET Core Documentation](https://dotnet.github.io/docs/) site. -Once you've followed the steps in this document, use the following sample to see the changes you need to make to your project: https://github.com/dotnet/corefxlab/tree/master/samples/NetCoreSample. - -Installing the tools -==================== - -1. Install Visual Studio 2015 - [https://www.visualstudio.com/downloads/download-visual-studio-vs](https://www.visualstudio.com/downloads/download-visual-studio-vs) -<br>Ensure you're running Visual Studio 2015 Update 1 (in Help->About in Visual Studio, you should see version 14.0.24020.00 or higher. If not, update in Tools->Extensions and Updates.) -2. Check "Universal Windows App Development Tools" in the initial install or modify the install to include it. - - - -Create a New Class Library -========================== - -1. File > New - - - -2. Select ".NET Framework 4.6" and "ASP.NET Core 5.0" - - - -3. At this point the project should compile - -Add support for the Platform Standard ---------------------------- - -Currently to enable leveraging packages that target the Platform Standard you need do to some manual steps - -1. Manually edit your csproj file by right clicking on the project and select unload and then right click and select edit. Remove this line: -``` - <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" /> -``` -And replace it with this: -``` - <Import Project="$(MSBuildExtensionsPath32)\Microsoft\Portable\$(TargetFrameworkVersion)\Microsoft.Portable.CSharp.targets" /> -``` -Add this at the end of the file, before the closing Project tag: -``` - <PropertyGroup> - <NuGetTargetMoniker>.NETPlatform,Version=v5.4</NuGetTargetMoniker> - </PropertyGroup> -``` - -2. Save and close your project file and then reload it. - -3. Open project.json file and change "dotnet" to "dotnet5.4". - - - -4. Save it. -5. At this point your project should be in a buildable state and targeting generation 5.4. - -Update your packages to the latest ----------------------------------- -To update to the RC1 packages, adjust your project.json as follows: - ``` - "dependencies": { - "Microsoft.NETCore": "5.0.1-beta-23516", - "Microsoft.NETCore.Portable.Compatibility": "1.0.1-beta-23516" - }, - ``` -To trigger the update to the latest version of the meta-packages right click on references and chose "Manage Nuget Packages": - 1. Click "Updates" tab - 2. Check the "Include prerelease" check-box - 3. Click the checkboxes for the packages, and click "Update" - - - - -Advanced: Updating and using nuget.exe -====================================== - -Future changes to the CoreCLR/CoreFX packages may require newer versions of Nuget than are currently in Visual Studio. In that case, you will need to follow these directions: - -1. Download the latest nuget.exe commandline client. This is required until a new NuGet Visual Studio extension is available. Browse to https://www.myget.org/gallery/nugetbuild and download the `NuGet.Commandline` package. Rename the extension from `.nupkg` to `.zip` and extract nuget.exe from the tools folder. -2. Disable NuGet's built-in package restore since that won't be using the latest nuget.exe we just downloaded. Goto Tools | NuGet Package Manager | Package Manager Settings | General. - -3. Setup ".NET Core Dev Feed" package source -> "http://myget.org/F/dotnet-core". Goto Tools | NuGet Package Manager | Package Manager Settings | Package Sources. - -4. In the Nuget Package Manager, above, follow the same steps, choosing '.NET Core Dev Feed' instead of the normal Nuget.org feed. -5. Run 'nuget.exe restore project.lock.json' +There are also instructions available for [targeting .NET Core with MSBuild](target-dotnetcore-with-msbuild.md).
\ No newline at end of file diff --git a/Documentation/project-docs/pcl-targets-dialog-net46-aspnetcore10.png b/Documentation/project-docs/pcl-targets-dialog-net46-aspnetcore10.png Binary files differnew file mode 100644 index 0000000000..f3685911c4 --- /dev/null +++ b/Documentation/project-docs/pcl-targets-dialog-net46-aspnetcore10.png diff --git a/Documentation/project-docs/target-dotnetcore-with-msbuild.md b/Documentation/project-docs/target-dotnetcore-with-msbuild.md new file mode 100644 index 0000000000..73da0878b7 --- /dev/null +++ b/Documentation/project-docs/target-dotnetcore-with-msbuild.md @@ -0,0 +1,118 @@ +Using MSBuild to build .NET Core projects +========================================= + +The .NET Core tooling is going to [move from project.json to MSBuild based projects](https://blogs.msdn.microsoft.com/dotnet/2016/05/23/changes-to-project-json/). +We expect the first version of the .NET Core tools that use MSBuild to ship along with Visual Studio "15". However, it is possible to use MSBuild for .NET Core +projects today, and this page shows how. + +We recommend that most people targeting .NET Core with *new* projects today use the default tooling experience with project.json. This is because we haven't yet added +support to MSBuild for a lot of the benefits that project.json has, because a lot of the ASP.NET based tooling will not work with MSBuild today, and because when we +do release .NET Core tooling which uses MSBuild, it will be able to automatically convert from project.json to MSBuild based projects. + +You may want to use MSBuild to target .NET Core for existing projects that already use MSBuild that you want to port to .NET Core, or if you are using +MSBuild's extensibility in your build for scenarios that are not well supported for project.json projects. + +Prerequisites +============= + +- [Visual Studio 2015 Update 3 RC](https://www.visualstudio.com/downloads/visual-studio-prerelease-downloads#sec1) or higher +- [.NET Core tools for Visual Studio](https://www.visualstudio.com/downloads/download-visual-studio-vs) +- NuGet Visual Studio extension [v3.5.0-beta](https://dist.nuget.org/visualstudio-2015-vsix/v3.5.0-beta/NuGet.Tools.vsix) or later + +Creating a library targeting .NET Core +====================================== + +- File > New > Project > Class Library (Portable) + +  + +- Select ".NET Framework 4.6" and "ASP.NET Core 1.0" + +  + +- In the "Library" tab of the project properties, click on the "Target .NET Platform Standard" link, and click "Yes" in the dialog that is shown +- In the `project.json` file: + - Change the version number of the `NETStandard.Library` package to `1.5.0-rc2-24027` (this is the .NET Core RC2 version of the package). + - Add the below `imports` definition inside the `netstandard1.5` framework definition. This will allow your project to reference .NET Core compatible + NuGet packages that haven't been updated to target .NET Standard + + ```json + "netstandard1.5": { + "imports": [ "dnxcore50", "portable-net452" ] + } + ``` + +Creating a .NET Core console application +======================================== +Building a console application for .NET Core requires some customization of the MSBuild build process. A sample project for a .NET Core console application +is [CoreApp](https://github.com/dotnet/corefxlab/tree/master/samples/NetCoreSample/CoreApp) in the [corefxlab](https://github.com/dotnet/corefxlab) repo. +Another good option is to start with [coretemplate](https://github.com/mellinoe/coretemplate), which uses separate MSBuild targets files to target .NET Core +instead of putting the the changes directly in the project file. + +It is also possible to start by creating a project in Visual Studio and modify it to target .NET Core. The instructions below show the minimal steps to get this working. +In contrast to CoreApp or coretemplate, a project created this way won't include configurations for targeting Linux and Mac OS. + +Creating a .NET Core console application from Visual Studio +=========================================================== + +- File > New > Project > Console Application +- In "Build" tab of the project properties, select "All Configurations" and change the "Platform Target" to "x64" +- Delete the `app.config` file from the project +- Add the following project.json file to the project: + + ```json + { + "dependencies": { + "Microsoft.NETCore.App": "1.0.0-rc2-3002702" + }, + "runtimes": { + "win7-x64": { }, + "ubuntu.14.04-x64": { }, + "osx.10.10-x64": { } + }, + "frameworks": { + "netcoreapp1.0": { + "imports": [ "dnxcore50", "portable-net452" ] + } + } + } + ``` + +- Open the project's XML for editing (in Visual Studio, right click on the project -> Unload Project, right click again -> Edit MyProj.csproj) + - Remove all the default `Reference` items (to `System`, `System.Core`, etc.) + - Add the following properties to the first `PropertyGroup` in the project: + + ```xml + <TargetFrameworkIdentifier>.NETCoreApp</TargetFrameworkIdentifier> + <TargetFrameworkVersion>v1.0</TargetFrameworkVersion> + <BaseNuGetRuntimeIdentifier>win7</BaseNuGetRuntimeIdentifier> + <NoStdLib>true</NoStdLib> + <NoWarn>$(NoWarn);1701</NoWarn> + ``` + + - Add the following at the end of the file (after the import of `Microsoft.Portable.CSharp.Targets`: + + ```xml + <PropertyGroup> + <!-- We don't use any of MSBuild's resolution logic for resolving the framework, so just set these two + properties to any folder that exists to skip the GetReferenceAssemblyPaths task (not target) and + to prevent it from outputting a warning (MSB3644). + --> + <_TargetFrameworkDirectories>$(MSBuildThisFileDirectory)</_TargetFrameworkDirectories> + <_FullFrameworkReferenceAssemblyPaths>$(MSBuildThisFileDirectory)</_FullFrameworkReferenceAssemblyPaths> + + <!-- MSBuild thinks all EXEs need binding redirects, not so for CoreCLR! --> + <AutoUnifyAssemblyReferences>true</AutoUnifyAssemblyReferences> + <AutoGenerateBindingRedirects>false</AutoGenerateBindingRedirects> + + <!-- Set up debug options to run with host, and to use the CoreCLR debug engine --> + <StartAction>Program</StartAction> + <StartProgram>$(TargetDir)dotnet.exe</StartProgram> + <StartArguments>$(TargetPath)</StartArguments> + <DebugEngines>{2E36F1D4-B23C-435D-AB41-18E608940038}</DebugEngines> + </PropertyGroup> + ``` + + - Close the .csproj file, and reload the project in Visual Studio + +- You should be able to run your program with F5 in Visual Studio, or from the command line in the output folder with `dotnet MyApp.exe`
\ No newline at end of file |
