Documentation/workflow/UsingDotNetCli.md

   1
   2 # Using your .NET Core Runtime Build with dotnet cli
   3
   4 This walkthrough explains how to run against your local CoreCLR build using `dotnet cli` only.
   5
   6 For other walkthroughs see:
   7
   8 - [Using Your Build - Update CoreCLR from raw binary output](UsingYourBuild.md)
   9 - [Using CoreRun To Run .NET Core Application](UsingCoreRun.md)
  10 - [Dogfooding .NET Core SDK](https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/dogfooding.md).
  11
  12 ## Prerequisites
  13
  14 1. Successfully built CoreCLR repository and thus have files of the form shown below. From now on we call this folder NuGet package folder.
  15
  16 ```
  17     bin\Product\<OS>.<arch>.<flavor>\.nuget\pkg\runtime.<OS>-<arch>.Microsoft.NETCore.Runtime.CoreCLR.<version>.nupkg
  18 ```
  19
  20 2. Acquired the latest nightly .NET Core SDK from [here](https://github.com/dotnet/cli/blob/master/README.md#installers-and-binaries) and added it's root folder to your [path](../building/windows-instructions.md#adding-to-the-default-path-variable)
  21
  22 ## First Run
  23
  24 ### 1. Create new folder for the app
  25
  26 `mkdir helloWorld`
  27
  28 From now on all instructions relate to this folder as "app folder".
  29
  30 ### 2. Create NuGet.Config file
  31
  32 The build script creates NuGet packages and puts them to `bin\Product\<OS>.<arch>.<flavor>\.nuget\pkg\`. dotnet cli has no idea about its existence and we need to tell it where to search for the packages.
  33
  34 Please run `dotnet new nugetconfig` in the app folder and update the created `NuGet.Config` file:
  35
  36 * **set path to local CoreCLR NuGet folder!!**
  37 * add address to dotnet core tools NuGet feed
  38
  39
  40 ```xml
  41 <?xml version="1.0" encoding="utf-8"?>
  42 <configuration>
  43   <packageSources>
  44     <!--To inherit the global NuGet package sources remove the <clear/> line below -->
  45     <clear />
  46
  47     <add key="local CoreCLR" value="C:\coreclr\bin\Product\Windows_NT.x64.Debug\.nuget\pkg" /> <!-- CHANGE THIS PATH to your local output path -->
  48     <add key="dotnet-core" value="https://dotnet.myget.org/F/dotnet-core/api/v3/index.json" /> <!-- link to corefx NuGet feed -->
  49   </packageSources>
  50 </configuration>
  51
  52 ```
  53
  54 ### 3. Create and update the Project file
  55
  56 Please run `dotnet new console` in the app folder and update the created `.csproj` file:
  57
  58 ```xml
  59 <Project Sdk="Microsoft.NET.Sdk">
  60
  61   <PropertyGroup>
  62     <OutputType>Exe</OutputType>
  63     <TargetFramework>netcoreapp2.1</TargetFramework>
  64     <RuntimeIdentifier>win-x64</RuntimeIdentifier>
  65     <RuntimeFrameworkVersion>2.1.0-preview1-26210-0</RuntimeFrameworkVersion>
  66   </PropertyGroup>
  67
  68   <ItemGroup>
  69     <PackageReference Include="runtime.win-x64.Microsoft.NETCore.Runtime.CoreCLR" Version="2.1.0-preview1-26210-0" />
  70     <PackageReference Include="runtime.win-x64.Microsoft.NETCore.Jit" Version="2.1.0-preview1-26210-0" />
  71   </ItemGroup>
  72
  73 </Project>
  74 ```
  75
  76 **You have to set the correct values for `RuntimeIdentifier` (RI), `RuntimeFrameworkVersion` and versions of both packages.**
  77
  78 You can generally figure that out by looking at the packages you found in your output.
  79 In our example you will see there is a package with the name `runtime.win-x64.Microsoft.NETCore.Runtime.CoreCLR.2.1.0-preview1-26210-0.nupkg`
  80
  81 ```
  82 runtime.win-x64.Microsoft.NETCore.Runtime.CoreCLR.2.1.0-preview1-26210-0.nupkg
  83        ^--RI---^                                 ^--------version-------^
  84 ```
  85
  86 ### 4. Change Program.cs
  87
  88 To make sure that you run against your local coreclr build please change your `Main` method in `Program.cs` file to:
  89
  90 ```cs
  91 static void Main(string[] args)
  92 {
  93         var coreAssemblyInfo = System.Diagnostics.FileVersionInfo.GetVersionInfo(typeof(object).Assembly.Location);
  94         Console.WriteLine($"Hello World from Core {coreAssemblyInfo.ProductVersion}");
  95         Console.WriteLine($"The location is {typeof(object).Assembly.Location}");
  96 }
  97 ```
  98
  99 ### 5. Publish
 100
 101 Now is the time to publish. The publish step will trigger restore and build. You can iterate on build by calling `dotnet build` as
 102 needed.
 103
 104 ```bat
 105 dotnet publish
 106 ```
 107
 108 Make sure that restoring done by `dotnet publish` installed the explicit version of the Runtime that you have specified:
 109
 110 ```
 111 PS C:\coreclr\helloWorld> dotnet publish
 112   Restoring packages for C:\coreclr\helloWorld\helloWorld.csproj...
 113   Installing runtime.win-x64.Microsoft.NETCore.Runtime.CoreCLR 2.1.0-preview1-26210-
 114 ```
 115
 116 If you see something like the message below it means that it has failed to restore your local runtime packages. In such case double check your `NuGet.config` file and paths used in it.
 117
 118 ```
 119 C:\coreclr\helloWorld\helloWorld.csproj : warning NU1603: helloWorld depends on runtime.win-x64.Microsoft.NETCore.Runtime.CoreCLR (>= 2.1.0-preview1-26210-0) but runtime.win-x64.Microsoft.NETCore.Runtime.CoreCLR 2.1.0-preview1-26210-0 was not found. An approximate best match of runtime.win-x64.Microsoft.NETCore.Runtime.CoreCLR 2.1.0-preview2-25501-02 was resolved.
 120 ```
 121
 122 ### 6. Run the app
 123
 124 After you publish you will find you all the binaries needed to run your application under `bin\Debug\netcoreapp2.1\win-x64\publish\`.
 125 To run the application simply run the EXE that is in this publish directory (it is the name of the app, or specified in the project file).
 126
 127 ```
 128 .\bin\Debug\netcoreapp2.1\win-x64\publish\HelloWorld.exe
 129 ```
 130
 131 Running the app should tell you the version and which user and machine build the assembly as well as the commit hash of the code
 132 at the time of building:
 133
 134 ```
 135 Hello World from Core 4.6.26210.0 @BuiltBy: adsitnik-MININT-O513E3V @SrcCode: https://github.com/dotnet/coreclr/tree/3d6da797d1f7dc47d5934189787a4e8006ab3a04
 136 The location is C:\coreclr\helloWorld\bin\Debug\netcoreapp2.1\win-x64\publish\System.Private.CoreLib.dll
 137 ```
 138
 139 **Congratulations! You have just run your first app against local CoreCLR build!**
 140
 141 ## Update CoreCLR using runtime nuget package
 142
 143 Updating CoreCLR from raw binary output is easier for quick one-off testing but using the nuget package is better
 144 for referencing your CoreCLR build in your actual application because of it does not require manual copying of files
 145 around each time the application is built and plugs into the rest of the tool chain. This set of instructions will cover
 146 the further steps needed to consume the runtime nuget package.
 147
 148 #### 1. Update BuildNumberMinor Environment Variable
 149
 150 One possible problem with this technique is that Nuget assumes that distinct builds have distinct version numbers.
 151 Thus if you modify the source and create a new NuGet package you must it a new version number and use that in your
 152 application's project. Otherwise the dotnet.exe tool will assume that the existing version is fine and you
 153 won't get the updated bits. This is what the Minor Build number is all about. By default it is 0, but you can
 154 give it a value by setting the BuildNumberMinor environment variable.
 155 ```bat
 156     set BuildNumberMinor=3
 157 ```
 158 before packaging. You should see this number show up in the version number (e.g. 2.1.0-preview1-26210-03).
 159
 160 As an alternative you can delete the existing copy of the package from the Nuget cache.   For example on
 161 windows (on Linux substitute ~/ for %HOMEPATH%) you could delete
 162 ```bat
 163      %HOMEPATH%\.nuget\packages\runtime.win-x64.Microsoft.NETCore.Runtime.CoreCLR\2.1.0-preview1-26210-0
 164 ```
 165 which should make things work (but is fragile, confirm file timestamps that you are getting the version you expect)
 166
 167 #### 2. Get the Version number of the CoreCLR package you built.
 168
 169 Get this by simply listing the name of the `runtime.win-x64.Microsoft.NETCore.Runtime.CoreCLR` you built.
 170
 171 ```bat
 172     dir bin\Product\Windows_NT.x64.Release\.nuget\pkg
 173 ```
 174
 175 and you will get name of the which looks something like this
 176
 177 ```
 178     runtime.win-x64.Microsoft.NETCore.Runtime.CoreCLR.2.1.0-preview1-26210-3.nupkg
 179 ```
 180
 181 This gets us the version number, in the above case it is 2.1.0-preview1-26210-3. We will
 182 use this in the next step.
 183
 184 #### 3. Update the references to your runtime package
 185
 186 Edit your `.csproj` file and change the versions:
 187
 188 ```
 189 <PropertyGroup>
 190     <RuntimeFrameworkVersion>2.1.0-preview1-26210-3</RuntimeFrameworkVersion>
 191 </PropertyGroup>
 192
 193 <ItemGroup>
 194   <PackageReference Include="runtime.win-x64.Microsoft.NETCore.Runtime.CoreCLR" Version="2.1.0-preview1-26210-3" />
 195   <PackageReference Include="runtime.win-x64.Microsoft.NETCore.Jit" Version="2.1.0-preview1-26210-3" />
 196 </ItemGroup>
 197 ```
 198
 199 #### 4. Restore and publish
 200
 201 Once have made these modifications you will need to rerun the restore and publish as such.
 202
 203 ```
 204 dotnet restore
 205 dotnet publish
 206 ```
 207
 208 Now your publication directory should contain your local built CoreCLR builds.