.NET Core, ASP.NET Core Course, Session 2

.NET Core + ASP.NET Core Training Course
Session 2

.NET Core
What we learned?
Session 1 Overview
• The history of .NET Framework
• .NET Framework position among it’s competitors
• Why .NET Core?
• .NET Core Components (CoreFX, CLR)
• .NET CLI
• .NET Core Deployment Models (Portable Apps, Self-contained Apps)
• .NET Core project structure
• .NET Core Comparison with .NET Framework

.NET Core
What we’ll learn today?
Session 2 Agenda
• Introducing .NET Standard
• Managing Package Dependency Versions
• .NET Portability Analyzer
• .NET Core Tools
• Telemetry
• Overview on Extensibility Model
• Dotnet-new
• Dotnet-restore
• Dotnet-run
• Dotnet-build
• Dotnet-test
• Dotnet-pack
• dotnet-publish
• dotnet-install-script
• project.json
• global.json

.NET Core
Introducing .NET Standard
Introducing .NET Standard
The .NET Standard Library is a formal
specification of .NET APIs that are intended to
be available on all .NET runtimes. The
motivation behind the Standard Library is
establishing greater uniformity in the .NET
ecosystem.
The .NET Standard Library enables the following key scenarios:
• Defines uniform set of BCL APIs for all .NET platforms to
implement, independent of workload.
• Enables developers to produce portable libraries that are
usable across .NET runtimes, using this same set of APIs.
• Reduces and hopefully eliminates conditional
compilation of shared source due to .NET APIs, only for
OS APIs.

.NET Core
Managing Package Dependency Versions
Glossary
Fix - Fixing dependencies means you are using the same "family" of packages released on NuGet for .NET Core 1.0.
Metapackage - A NuGet package that represents a set of NuGet packages.
Trimming - The act of removing the packages you do not depend on from a metapackage. This is something
relevant for NuGet package authors.

.NET Core
Fix your dependencies to .NET Core 1.0
To reliably restore packages and write reliable code, it's important that you fix your dependencies to the versions of
packages shipping alongside .NET Core 1.0. This means every package should have a single version with no additional
qualifiers.
Examples of packages fixed to 1.0
• "System.Collections":"4.0.11"
• "NETStandard.Library":"1.6.0"
• "Microsoft.NETCore.App":"1.0.0"
Examples of packages that are NOT fixed to 1.0
• "Microsoft.NETCore.App":"1.0.0-rc4-00454-00"
• "System.Net.Http":"4.1.0-*"
• "System.Text.RegularExpressions":"4.0.10-rc3-24021-00"
Packages and Version Numbers organized by Metapackage
List of all .NET Standard library packages and their versions for 1.0.
List of all runtime packages and their versions for 1.0.
List of all .NET Core application packages and their versions for 1.0.

.NET Core
.NET Portability Analyzer
The goal of these tools is to help identify possible problem areas in an assembly and help direct
targeted testing, by identifying APIs that:
• Are not portable to specific platforms
• Have breaking changes between 4.x versions
Usage:
ApiPort.exe analyze <options>
-f, --file=VALUE [Required] Path to assembly file or directory of assemblies.
-o, --out=VALUE Output file name
-d, --description=VALUE Description of the submission
-t, --target=VALUE The target you want to check against.
-r, --resultFormat=VALUE The report output format
-p, --showNonPortableApis Calculate non-portable APIs
-b, --showBreakingChanges Calculate breaking changes on full .NET Framework
-u, --showRetargettingIssues Include the retargetting issues in the reports
--noDefaultIgnoreFile Do not use the standard assembly ignore list when analyzing breaking changes. The default ignore list can be found at KnownSafeBreaks.json

.NET Core
Portability Service
APIPort VS Extenstion
ApiPort.exe analyze -f foo.dll -t ".NET CORE, Version=5.0" -t ".NET Framework" -r HTML
ApiPort.exe listTargets
ApiPort.exe listOutputFormats
See the data being transmitted
Run the tool in an offline mode
using System;
using System.Runtime.Serialization;
namespace Application
{
#if DESKTOP
[Serializable]
#endif
public class SomeCustomException : Exception
{
public SomeCustomException() { }
#if DESKTOP
protected SomeCustomException(SerializationInfo info, StreamingContext context)
: base(info, context)
{ }
#endif
}
}

.NET Core
Telemetry
.NET Core Tools Telemetry
The .NET Core tools include a telemetry feature so that the .NET Team can collect
usage information about the .NET Core Tools. Telemetry is only in the tools and
does not affect any app.
• The telemetry feature is on by default
• The data collected is anonymous in nature
• The data will be published in an aggregated form
• Microsoft and community engineers receive data under a Creative Commons license
• opt-out with environment variable: DOTNET_CLI_TELEMETRY_OPTOUT

.NET Core
Telemetry
.NET Core Tools Telemetry
The feature collects the following pieces of data:
• The command being used (for example, “build”, “restore”)
• Arguments passed to the command
• The ExitCode of the command
• For test projects, the test runner being used
• The timestamp of invocation
• The framework used
• Whether runtime IDs are present in the “runtimes” node
• The CLI version being used
The feature will not collect any personal data, such as usernames or emails
It’s based on End User License Agreement (EULA)

.NET Core
.NET Core CLI extensibility model
How to extend CLI tools?
The CLI tools can be extended in two main ways (one or both):
• Via NuGet packages on a per-project basis
• Via the system's PATH
Per-project tools are portable console applications that are distributed as NuGet packages. Tools are only
available in the context of the project that references them and for which they are restored; invocation
outside of the context of the project (for example, outside of the directory that contains the project) will fail
as the command will not be able to be found. EF, Web, etc.
Consuming these tools requires you to add a tools node to your project.json.

.NET Core
PATH-based extensibility
is usually used for development machines where you need a tool that
conceptually covers more than a single project.
dotnet driver can run any command that is named after the dotnet
<command> convention. The default resolution logic will first probe several
locations and will finally fall to the system PATH. If the requested command
exists in the system PATH and is a binary that can be invoked, dotnet driver
will invoke it.
dotnet-clean /usr/local/bin/

.NET Core
dotnet-new
.NET Core Tools dotnet-new
dotnet-new -- Creates a new .NET Core project
• SYNOPSIS: dotnet new [--type] [--lang]
• Invoked in the context of a directory
1. A Program.cs (or Program.fs) file that contains a sample "Hello World" program.
2. A valid project.json file.
• Options: -l, --lang [C#|F#] Defaults to C#. csharp (fsharp) or cs (fs) are also valid options.
• Options: -t, --type Valid values are console, web, lib and xunittest
dotnet new
dotnet new --lang f#
dotnet new --lang c#
dotnet new -t web

.NET Core
dotnet-restore
.NET Core Tools dotnet-restore
dotnet-restore - Restores the dependencies and tools of a project
• SYNOPSIS: dotnet restore [--source] [--packages] [--disable-parallel] [--fallbacksource] [--
configfile] [--verbosity] [<root>]
• Uses NuGet to restore dependencies as well as project-specific tools that are specified in the project.json
• By default, the restoration of dependencies and tools are done in parallel
• NuGet needs the feeds where the packages are located, location is in NuGet.config
• Uses specific NuGet.config file should be in the project directory
• For dependencies, use the --packages argument, if not specified, the default NuGet package cache is used.
It is found in the .nuget/packages directory in the user's home directory on all operating systems (for example, /home/user1 on
Linux or C:Usersuser1 on Windows)

.NET Core
dotnet-restore
OPTIONS:
• [root]
A list of projects or project folders to restore. The list can contain either a path to a project.json file, or a path to global.json file or folder.
The restore operation runs recursively for all subdirectories and restores for each given project.json file it finds.
• -s, --source [SOURCE]
Specifies a source to use during the restore operation. This overrides all of the sources specified in the NuGet.config file(s).
• --packages [DIR]
Specifies the directory to place the restored packages in.
• --disable-parallel
Disables restoring multiple projects in parallel.
• -f, --fallbacksource [FEED]
Specifies a fallback source that will be used in the restore operation if all other sources fail. All valid feed formats are allowed.

.NET Core
dotnet-restore
OPTIONS:
• --configfile [FILE]
Configuration file (NuGet.config) to use for the restore operation.
• --verbosity [LEVEL]
The verbosity of logging to use. Allowed values: Debug, Verbose, Information, Minimal, Warning, or Error.
dotnet restore
dotnet restore ~/projects/app1/project.json
dotnet restore --f c:packagesmypackages
dotnet restore --verbosity Error

.NET Core
dotnet-run
.NET Core Tools dotnet-run
dotnet-run -- Runs source code 'in-place' without any explicit compile or launch commands.
• SYNOPSIS: dotnet run [--framework] [--configuration] [--project] [--help] [--]
• This command is useful for fast iterative development (can also be used to run a source-distributed program (website))
• Relies on dotnet build to build source inputs to a .NET assembly
• Before launching the program calls dotnet build to build
• Output files are written to the child bin folder, which will be created if it doesn't exist
• Temporary files are written to the child obj folder
• In case of multiple specified frameworks, dotnet run will first select the .NET Core frameworks
• To specify other frameworks, use the --framework argument
• dotnet run command works with projects, not built assemblies

.NET Core
dotnet-run
.NET Core Tools dotnet-run
Options:
• -- Delimits arguments to dotnet run from arguments for the application being run. All arguments after this one will be passed to
the application being run
• -f, --framework [FID] Runs the application for a given framework identifier (FID)
• -c, --configuration [Debug|Release] Configuration to use when publishing. The default value is "Debug"
• -p, --project [PATH] Specifies which project to run. It can be a path to a project.json file or to a directory containing a
project.json file. It defaults to current directory if not specified
dotnet run
dotnet run --project /projects/proj1/project.json
dotnet run --configuration Release -- --help

.NET Core
dotnet-build
.NET Core Tools dotnet-build
dotnet-build -- Builds a project and all of its dependencies
• SYNOPSIS: dotnet build [--output] [--build-base-path] [--framework] [--configuration] [--runtime] [--
version-suffix] [--build-profile] [--no-incremental] [--no-dependencies] [<project>]
• The binary will be in Intermediate Language (IL) by default and will have a DLL extension
• dotnet build will also drop a *.deps file which outlines what the host needs to run the application
• Building requires the existence of a lock file, which means that you have to run dotnet restore prior to building your code
• Before any compilation begins, the build verb analyzes the project and its dependencies for
incremental safety checks
• If all checks pass, then build proceeds with incremental compilation of the project and its
dependencies; otherwise, it falls back to non-incremental compilation

.NET Core
dotnet-build
All projects in the dependency graph that need compilation must pass the following safety checks in order for
the compilation process to be incremental:
• not use pre/post compile scripts
• not load compilation tools from PATH (for example, resgen, compilers)
• use only known compilers (csc, vbc, fsc)
In order to build an executable application, you need a special configuration section in your project.json file:
{
"compilerOptions": {
"emitEntryPoint": true
}
}

.NET Core
dotnet-build
OPTIONS:
• -o, --output [DIR]: Directory in which to place the built binaries.
• -b, --build-base-path [DIR]: Directory in which to place temporary outputs.
• -f, --framework [FRAMEWORK]: Compiles for a specific framework. Needs to be defined in the project.json file.
• -c, --configuration [Debug|Release]: Defines a configuration under which to build. If omitted, it defaults to Debug.
• -r, --runtime [RUNTIME_IDENTIFIER]: Target runtime to build for.
• --version-suffix [VERSION_SUFFIX]: Defines what * should be replaced with in the version field in the project.json file.
• --build-profile: Prints out the incremental safety checks that users need to address in order for incremental compilation
• --no-incremental: Marks the build as unsafe for incremental build. forces a clean rebuild of the project dependency graph.
• --no-dependencies: Ignores project-to-project references and only builds the root project specified to build.

.NET Core
dotnet-test
.NET Core Tools dotnet-test
dotnet-test - Runs unit tests using the configured test runner
• SYNOPSIS: dotnet test [--configuration] [--output] [--build-base-path] [--framework] [--runtime] [--no-
build] [--parentProcessId] [--port] [<project>]
• Unit tests are class library projects that have dependencies on the unit test framework (NUnit or xUnit)
and the dotnet test runner for that unit testing framework, These are packaged as NuGet packages and are restored as
ordinary dependencies for the project
• Test projects need to specify a test runner property in project.json using the "testRunner" node. This value
should contain the name of the unit test framework.

.NET Core
dotnet-test
{
"version": "1.0.0-*",
"buildOptions": { "debugType": "portable" },
"dependencies": {
"System.Runtime.Serialization.Primitives": "4.1.1",
"xunit": "2.1.0",
"dotnet-test-xunit": "1.0.0-rc2-192208-24" },
"testRunner": "xunit",
"frameworks": {
"netcoreapp1.0": {
"dependencies": {
"Microsoft.NETCore.App": { "type": "platform", "version": "1.0.0“ } },
"imports": [
"dotnet5.4",
"portable-net451+win8"
] } } }
dotnet test supports two running modes:
1. Console: In console mode, dotnet test simply executes fully
any command gets passed to it and outputs the results.
Anytime you invoke dotnet test without passing --port, it runs
in console mode, which in turn will cause the runner to run in
console mode.
2. Design time: used in the context of other tools, such as
editors or Integrated Development Environments (IDEs).
dotnet test
dotnet test /projects/test1/project.json

.NET Core
dotnet-test
OPTIONS
• [project]: Specifies a path to the test project. If omitted, it defaults to current directory.
• -c, --configuration [Debug|Release]: Configuration under which to build. The default value is Release.
• -o, --output [DIR]: Directory in which to find binaries to run.
• -f, --framework [FRAMEWORK]: Looks for test binaries for a specific framework.
• -r, --runtime [RUNTIME_IDENTIFIER]: Look for test binaries for a for the specified runtime.
• --no-build: Does not build the test project prior to running it.
• --parentProcessId: Used by IDEs to specify their process ID. Test will exit if the parent process does.
• --port: Used by IDEs to specify a port number to listen for a connection.

.NET Core
dotnet-pack
.NET Core Tools dotnet-pack
dotnet-pack - Packs the code into a NuGet package
• SYNOPSIS: dotnet pack [--output] [--no-build] [--build-base-path] [--configuration] [--version-suffix]
[<project>]
• The dotnet pack command builds the project and creates NuGet packages
• The result is two packages with the nupkg extension. One contains the code and the other contains the debug symbols
• NuGet dependencies of the project being packed are added to the nuspec file
• Project-to-project references are not packaged inside the project by default, for doing this, reference the
required project in dependencies node with a type set to "build"

.NET Core
dotnet-pack
.NET Core Tools dotnet-pack
OPTIONS
• [project]: The project to pack. It can be either a path to a project.json file or to a directory. If omitted, the current directory.
• -o, --output [DIR]: Places the built packages in the directory specified.
• --no-build: Skips the building phase of the packing process. useful in Continuous Integration (CI) build scenarios in which you
know the code was just previously built.
• --build-base-path: Places the temporary build artifacts in the specified directory. Default: obj directory in the current directory.
• -c, --configuration [Debug|Release]: Configuration to use when building the project. If not specified, "Debug".
dotnet pack
dotnet pack ~/projects/app1/project.json
dotnet pack --output nupkgs
dotnet pack --no-build --output nupkgs

.NET Core
dotnet-publish
.NET Core Tools dotnet-publish
dotnet-publish - Packs the application and all of its dependencies into a folder getting it ready for publishing
• SYNOPSIS: dotnet publish [--framework] [--runtime] [--build-base-path] [--output] [--version-suffix] [--
configuration] [<project>]
• compiles the application, reads through its dependencies specified in the project.json file and publishes
the resulting set of files to a directory
• Depending on the type of portable app, the resulting directory will contain the following:
1. Portable application - application's intermediate language (IL) code and all of application's managed dependencies.
• Portable application with native dependencies - same as above with a sub-directory for the supported platform of each
native dependency.
2. Self-contained application - same as above plus the entire runtime for the targeted platform.

.NET Core
dotnet-publish
OPTIONS
• [project]: needs access to the project.json file to work. If it is not specified, default is current directory.
• -f, --framework [FID]: Publishes the application for a given framework identifier (FID). If not specified, reads from project.json
• -r, --runtime [RID]: Publishes the application for a given runtime
• -o, --output: Specify the path where to place the directory. If not specified, it will default to
./bin/[configuration]/[framework]/ for portable applications
./bin/[configuration]/[framework]/[runtime] for self-contained applications.
• --version-suffix [VERSION_SUFFIX]: Defines what * should be replaced with in the version field in the project.json file.
• -c, --configuration [Debug|Release]: Configuration to use when publishing. The default value is Debug.

.NET Core
dotnet-publish
dotnet publish
Publishes an application using the framework found in project.json. If project.json contains runtimes node, publish for the RID of the current platform.
dotnet publish ~/projects/app1/project.json
Publishes the application using the specified project.json.
dotnet publish --framework netcoreapp1.0
Publishes the current application using the netcoreapp1.0 framework.
dotnet publish --framework netcoreapp1.0 --runtime osx.10.11-x64
Publishes the current application using the netcoreapp1.0 framework and runtime for OS X 10.10. This RID has to exist in the project.json runtimes node.

.NET Core
dotnet-install scripts reference
.NET Core Tools dotnet-install scripts reference
dotnet-install.ps1 | dotnet-install.sh - script used to install the Command Line Interface (CLI) tools and shared runtime
SYNOPSIS:
• Windows: dotnet-install.ps1 [-Channel] [-Version] [-InstallDir] [-Debug] [-NoPath] [-SharedRuntime]
• OS X/Linux: dotnet-install.sh [--channel] [--version] [--install-dir] [--debug] [--no-path] [--shared-runtime]
The dotnet-install scripts are used to perform a non-admin install of the CLI toolchain and the shared runtime. You can
download the scripts from our CLI GitHub repo. (ZIP/tarball). By default, SDK will downloaded.
Bash script also "understands" PowerShell switches.

.NET Core
Options PowerShell (Windows)
-Channel [CHANNEL]: Which channel (for example, "future", "preview", "production") to install from. default: "Production".
-Version [VERSION]: Version of CLI to install; 3-part version (i.e. 1.0.0-13232). If omitted, default: first global.json that contains the
sdkVersion property; if not presents, it will use Latest.
-InstallDir [DIR]: Path to install to. The directory is created if it doesn't exist. The default value is %LocalAppData%.dotnet.
-Debug: true to indicate that larger packages containing debugging symbols should be used; otherwise, false. The default value is false.
-NoPath: true to indicate that the prefix/installdir are not exported to the path for the current session; otherwise, false. The default value
is false, that is, the PATH is modified. This makes the CLI tools available immediately after install.
-SharedRuntime: true to install just the shared runtime bits; false to install the entire SDK. The default value is false.

.NET Core
Options Bash (OS X/Linux)
--channel [CHANNEL]: Which channel (for example "future", "preview", "production") to install from. The default value is "Production".
--version [VERSION]: Which version of CLI to install; version as 3-part version (i.e. 1.0.0-13232). If omitted default is the first global.json
that contains the sdkVersion property; if that is not present, it will use Latest.
--install-dir [DIR]: Path to where to install. The directory is created if it doesn't exist. The default value is $HOME/.dotnet.
--debug: true to indicate that larger packages containing debugging symbols should be used; otherwise, false. The default value is false.
--no-path: true to indicate that the prefix/installdir are not exported to the path for the current session; otherwise, false. The default value is false, that is,
the PATH is modified. This makes the CLI tools available immediately after install.
--shared-runtime: true to install just the shared runtime bits; false to install the entire SDK. The default value is false.

.NET Core
EXAMPLES
Windows: ./dotnet-install.ps1 -Channel Future
OS X/Linux: ./dotnet-install.sh --channel Future Installs the dev latest version to the default location.
Windows: ./dotnet-install.ps1 -Channel preview -InstallDir C:cli
OS X/Linux: ./dotnet-install.sh --channel preview --install-dir ~/cli

.NET Core
project.json reference
.NET Core Tools project.json reference
name
version
summary
description
copyright
title
entryPoint
projectUrl
licenseUrl
iconUrl
compilerName
testRunner
authors
owners
tags
language
releaseNotes
requireLicenseAcceptance
embedInteropTypes
compile
content
Resource
preprocess
publishExclude
shared
namedResource
packInclude
exclude
contentBuiltIn
compileBuiltIn
resourceBuiltIn
excludeBuiltIn
dependencies
tools
commands
scripts
compilationOptions
analyzerOptions
configurations
frameworks

.NET Core
project.json Example:
.NET Core Tools project.json

.NET Core
global.json reference
.NET Core Tools global.json reference
projects
Type: String[]
Specifies what folders the build system should search for projects when resolving dependencies. The build system will only
search top level child folders.
packages
Type: String[]
The folder to store packages.

.NET Core, ASP.NET Core Course, Session 2

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to .NET Core, ASP.NET Core Course, Session 2

Similar to .NET Core, ASP.NET Core Course, Session 2 (20)

More from aminmesbahi

More from aminmesbahi (11)

Recently uploaded

Recently uploaded (20)

.NET Core, ASP.NET Core Course, Session 2