dotnet-installer/Documentation/specs/installation-scenarios.md

Notes

This section describes placeholders used inside this spec.

Placeholder	Description
<Channel>	`(future
<Version>	version string
<OSName>	`(win
<LowestSupportedOSVersion>	Lowest supported OS Version
<Architecture>	Processor architecture related to binaries produced
<Extension>	File extension. This will be described in more details later for each OS separately.
<OSID>	Abbreviation for: <OSName><LowestSupportedOSVersion>.<Architecture>. See more info
<VersionPointer>	`(latest
<ExecutableExtension>	Executable extension including dot specific to OS (can be empty string)
<CommitHash>	Commit hash related to state of repository from where build with specific <Version> was build
<DebianPackageName>	Name of the debian package. See more info

Build Output

Each official, successful build should create and upload packages to location described by following URLs:

https://dotnetcli.blob.core.windows.net/dotnet/<Channel>/<Version>/dotnet.<OSID>.<Version>.<Extension>

Currently:
https://dotnetcli.blob.core.windows.net/dotnet/<Channel>/Binaries/<Version>/dotnet-sharedframework-<OSName>-<Architecture>.<Version>.zip
https://dotnetcli.blob.core.windows.net/dotnet/<Channel>/Binaries/<Version>/dotnet-host-<OSName>-<Architecture>.<Version>.zip
https://dotnetcli.blob.core.windows.net/dotnet/<Channel>/Binaries/<Version>/dotnet-<OSName>-<Architecture>.<Version>.zip

Content of the package should contain binaries which layout will be described later.

Additionally each build should update latest version descriptors

Windows output

Nuget - WIP, this should include versioning scheme

<Extension>	Description
exe	Installer bundle. It should be used by end customers
zip	Packed binaries. Used by installation script
symbols.zip	Packed binaries with included symbols. See symbol packages

Including dotnet cli installer as part of your bundle

In order to install dotnet cli with other installer you need an MSI package. To get MSI, download exe bundle and extract it using dark tool which is part of WiX Toolset:

dark.exe -x <FolderWhereToExtract> <InstallerPath>

OSX output

<Extension>	Description
pkg	WIP
tar.gz	Packed binaries. Used by installation script
symbols.tar.gz	Packed binaries with included symbols. See symbol packages

Ubuntu output

<Extension>	Description
deb	Debian package. This package is being pushed to a debian feed
tar.gz	Packed binaries. Used by installation script
symbols.tar.gz	Packed binaries with included symbols. See symbol packages

RedHat/CentOS output

<Extension>	Description
tar.gz	Packed binaries. Used by installation script
symbols.tar.gz	Packed binaries with included symbols. See symbol packages

Debian output

<Extension>	Description
tar.gz	Packed binaries. Used by installation script
symbols.tar.gz	Packed binaries with included symbols. See symbol packages

Example build output links

WIP

Questions

• Should include channel name to avoid situation where you have two files on your computer and latest file might have lower version than the newest?

Obtaining dotnet

Installation scripts

Installation script is a shell script which lets customers install dotnet.

For Windows we are using PowerShell script (install-dotnet.ps1). For any other OS we are using bash script (install-dotnet.sh)

WIP: Exact script action description.

Script arguments description

PowerShell/Bash script	Bash script only	Default	Description
-Channel	--channel	production	Which channel to install from. Possible values: future, preview, production
-Version	--version	global.json or latest	global.json currently not supported
-InstallDir	--prefix	Windows: %LocalAppData%\Microsoft\.dotnet	Path to where install dotnet. Note that binaries will be placed directly in a given directory.
-Architecture	--architecture	auto	Possible values: auto, x64, x86. auto refers to currently running OS architecture. This switch is currently not supported in bash scripts.
-DebugSymbols	--debug-symbols	<not set>	If switch present, installation will include debug symbol
-DryRun	--dry-run	<not set>	If switch present, installation will not be performed and instead deterministic invocation with specific version and zip location will be displayed.
-NoPath	--no-path	<not set>	If switch present the script will not set PATH environmental variable for the current process.
-Verbose	--verbose	<not set>	If switch present displays diagnostics information.
-AzureFeed	--azure-feed	See description	Azure feed URL, default: https://dotnetcli.blob.core.windows.net/dotnet

Script location

WIP: permanent link for obtaining latest version WIP: versioning description Newest version of the scripts can be found in the repository under following directory:

https://github.com/dotnet/cli/tree/rel/1.0.0/scripts/obtain

Older version of the script can be obtained using:

https://github.com/dotnet/cli/blob/<commit_hash>/scripts/obtain

Getting started page

WIP

Repo landing page

WIP

Version descriptors

Version pointers

Version pointers represent URLs to the latest and Last Known Good (LKG) builds. Specific URLs TBD. This will be something similar to following:

<Domain>/dotnet/<Channel>/<VersionPointer>.<OSID>.version

<Domain> TBD

Version files

Version files can be found in multiple places:

• Package: relative path inside the package ./.version
• Latest/LKG version file: WIP

URL:

https://dotnetcli.blob.core.windows.net/dotnet/<Channel>/<VersionPointer>.<OSID>.version

File content

Each version file contains two lines describing the build:

<CommitHash>
<Version>

Version badge

Version badge (SVG) is an image with textual representation of <Version>. It can be found under following URL:

https://dotnetcli.blob.core.windows.net/dotnet/<Channel>/<VersionPointer>.<OSID>.svg

Questions/gaps

• Version Pointer links should be permanent and hosted on a separate domain

Package content

Currently package is required to contain two files:

• .version - version file
• dotnet - entry point for all dotnet commands

Disk Layout

.\
    .version
    bin\
        dotnet<ExecutableExtension>

Channels

Currently we have 3 channels which gives us idea about stability and quality of our product.

Channel name	Description
future	This channel can contain new features which may not be fully complete. This is usually most unstable channel.
preview	This channel is in the process of stablization. Most of the bugs and gaps are known. No new features expected.
production	This is the most stable channel. Features and gaps are known. No breaking changes can be expected. This channel will only be producing new versions on hotfixes.

Github branches relation

Each branch on each successful build produces packages described in build output. Mapping between branches and channel name can be found in the table below:

Channel name	Github branch
future	master
preview	rel/1.0.0
production	N/A, prod?

Debian feed relation

After each successful build package is being pushed to the debian feed. More information on debian feed can be found here.

Channel name	<DebianPackageName>
future	dotnet-future
preview	dotnet-preview
production	dotnet

Nuget semantic version suffix relation

WIP

Questions

• What is the bar for triggering hotfix?

OSID

OSID represents abbreviation for:

<OSName><LowestSupportedOSVersion>.<Architecture>

This naming scheme gives us flexibility to easily create new binaries when OS makes a breaking change without creating confusing names.

In example, we currently put api-ms-*.dll files in our binaries. Those files are not needed on Windows 8 and higher. When using name win7.x64 we can easily decide to get rid of api-ms-*.dll in the newest packages and simply call new version win8.x64 which would mean that from Windows 8 forward those are recommended binaries (there is currently no issue with those files and this should be only treated as an example).

Debian feed

Newest binaries in debian feed may be delayed due to external issues by up to 24h.

Obtaining binaries

Add debian feed:

sudo sh -c 'echo "deb [arch=amd64] http://apt-mo.trafficmanager.net/repos/dotnet/ trusty main" > /etc/apt/sources.list.d/dotnetdev.list'

sudo apt-key adv --keyserver apt-mo.trafficmanager.net --recv-keys 417A0893

sudo apt-get update

Install:

sudo apt-get install <DebianPackageName>=<Version>

Questions

• Is debian version compatible with <Version> or does it require additional revision number, i.e.: 1.0.0.001598-1?
• How to differentiate between Debian package for Debian and Debian package for Ubuntu?

Symbol packages

WIP