From: Juan Hoyos Date: Tue, 10 Nov 2020 21:25:52 +0000 (-0800) Subject: Add documentation on single file (#1709) X-Git-Tag: submit/tizen/20210909.063632~17^2~337 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=fb65a2c90acf744a7ea5051f313875f3425fba2e;p=platform%2Fcore%2Fdotnet%2Fdiagnostics.git Add documentation on single file (#1709) * Add documentation on single file tool deployments. Co-authored-by: Noah Falk Co-authored-by: John Salem --- diff --git a/documentation/single-file-tools.md b/documentation/single-file-tools.md new file mode 100644 index 000000000..74fbae575 --- /dev/null +++ b/documentation/single-file-tools.md @@ -0,0 +1,77 @@ +# Single File Diagnostic Tools + +Our diagnostic tools are distributed so far as [global tools](https://docs.microsoft.com/en-us/dotnet/core/tools/global-tools). Global tools provide a great user experience as they provide clear ways to easily download, update, and configure the scope of the tools. However, this mechanism requires a full .NET SDK to be available. This is rarely the case in environments like production machines. For these scenarios we provide a single file distribution mechanism that only requires a runtime to be available on the target machine. Other than the installation instructions, all functionality and usage remain the same. For instructions on usage and syntax, please refer to the [.NET Core diagnostic global tools documentation](https://docs.microsoft.com/en-us/dotnet/core/diagnostics/#net-core-diagnostic-global-tools). + +## Requirements to Run the Tools + +- The tools distributed in a single file format are *_framework dependent_* applications. They require a 3.1 or newer .NET Core runtime to be available. This means one of the following: + - Installing the runtime globally in a well-known location using one of the different installer technologies documented in the [official .NET download page](https://dotnet.microsoft.com/download). + - Downloading the binary archives from the [official .NET download page](https://dotnet.microsoft.com/download), extracting them to a directory, and setting the `DOTNET_ROOT` environment variable to the path of extraction. + - Using the [dotnet-install scripts](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-install-script) and setting `DOTNET_ROOT` to the installation directory. This mechanism is not recommended for development or production environments, but it's ideal for environments like CI machines. + - The workload is being run in a container with the runtime available. This could be either because the workload is running on one of the [official .NET runtime containers](https://hub.docker.com/_/microsoft-dotnet-runtime) or on a custom-built image that installs it at build time. +- These tools are elf-extracting archives will write files to disk as necessary. The extraction target folder is within the platform's `TEMP` directory by default - for Windows this will be in `%TEMP%` and on Unix based systems this will be under `$TMPDIR`. In case `TEMP` is not available in the target environment or there's a desire to control the extraction directory for reasons such as clean up, set the `DOTNET_BUNDLE_EXTRACT_BASE_DIR` environment variable to a path that can be used in lieu of `TEMP`. + +## Obtaining the Tools + +### Downloading the latest available release of a tool + +The latest release of the tools is always available at a link that follows the following schema: + +``` +https://aka.ms// +``` + +The tools we support are: + +- `dotnet-counters` +- `dotnet-dump` +- `dotnet-gcdump` +- `dotnet-sos` +- `dotnet-trace` + +The supported [runtime identifiers](https://docs.microsoft.com/en-us/dotnet/core/rid-catalog) are: + +- `win-arm` +- `win-arm64` +- `win-x64` +- `win-x86` +- `osx-x64` +- `linux-arm`. +- `linux-arm64` +- `linux-musl-arm64` +- `linux-x64` +- `linux-musl-x64` + +For example, the latest release of `dotnet-trace` for Windows x64 will be available at . + +To download these tools you can either use a browser or use a command line utility like `wget` or `curl`. It's important to note that the file name is returned in the `content-disposition` header of the request. If the utility you use to download the tools respects the header, the file will be saved with the name of the tool downloaded; otherwise you might need to rename the tool. A few examples are: + +1. *`curl` (available on Windows after 1706, macOS, and several distributions of Linux)* + +```sh +curl -JLO https://aka.ms/dotnet-dump/win-x64 +``` + +2. *`wget`* + +```sh +wget --content-disposition https://aka.ms/dotnet-dump/linux-x64 +``` + +3. *`pwsh` (PowerShell core)* + +```powershell +$resp = Invoke-WebRequest -Uri "https://aka.ms/dotnet-dump/win-x86" +$header = [System.Net.Http.Headers.ContentDispositionHeaderValue]::Parse($resp.Headers.'content-disposition') +[System.IO.File]::WriteAllBytes($header.FileName, $resp.content) +``` + +4. *`powershell`* + +```powershell +Invoke-WebRequest -Uri "https://aka.ms/dotnet-dump/win-x86" -Outfile "dotnet-dump.exe" +``` + +### Past Releases and Checksum Validation + +Each release in the [releases section](https://github.com/dotnet/diagnostics/releases) of the repository contains a table of stable links for our tools starting release `v5.0.152202`. Additionally, there's a CSV available as an attachment containing all the stable links and SHA512 checksums in case the downloaded files need to be validated.