Workbooks is an interactive programming environment that’s perfect for experimentation, learning, and documentation: an educational tool for learning the myriad of .NET platforms, APIs, and libraries.
Clone or download
abock Merge pull request #507 from sandyarmstrong/sw-master
Let npm-shrinkwrap get updated
Latest commit 1ef3b23 Nov 28, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github .github/CODEOWNERS: BEAR order Dec 6, 2017
.vscode .vscode: add workspace rulers Apr 2, 2018
Agents Telemetry: Use Azure Application Insights Jun 29, 2018
ClientIntegrations iOS: Fix ancient error message Jul 3, 2018
Clients Let npm-shrinkwrap get updated Nov 28, 2018
CodeAnalysis Resolving: Fix another NRE Jul 3, 2018
External Windows: use WindowsAPICodePack from myget Feb 14, 2018
Package Win: Remove some System.Memory from installer Jul 3, 2018
Samples ClientIntegrations/, Samples/: add .gitignore Nov 8, 2017
Tests Log: Add LogEntry.Exception Jun 29, 2018
Tools .NET Core: Bump to netcoreapp2.1 across the board. Jun 22, 2018
WorkbookApps iOS: bump to iOS 12 SDK Jul 3, 2018
build Telemetry: Use Azure Application Insights Jun 29, 2018
docs Telemetry: Use Azure Application Insights Jun 29, 2018
.appveyor.yml AppVeyor: disable cache, install .NET Core from global.json Jun 22, 2018
.editorconfig Web: a brand new UX built on the existing core Mar 16, 2018
.gitignore .gitignore: update Apr 11, 2018
.gitmodules Windows: use WindowsAPICodePack from myget Feb 14, 2018
.travis.yml .NET Core: Bump to .NET Core SDK 2.1 Jun 22, 2018
.vsts-ci.yml build: install Mono 5.12 beta in VSTS hosted pool Jun 27, 2018
Directory.Build.props .NET Core: Bump to netcoreapp2.1 across the board. Jun 22, 2018
Directory.Build.targets Build: move to Directory.Build.{props,targets} Apr 4, 2018
LICENSE Initial import for the open-sourcening Nov 2, 2017
NuGet.config NuGet.config: fix formatting, make first again Jun 27, 2018 README updates Jun 25, 2018
RETHESIS RETHESIS: update for 1.4.0-beta1 Nov 14, 2017
ThirdPartyNotices.txt Initial import for the open-sourcening Nov 2, 2017 UPDATES: 1.4.0 final Jan 19, 2018
build.proj build: force separate Restore and Build targets May 22, 2018
dependencies.json Telemetry: Use Azure Application Insights Jun 29, 2018 Telemetry: Use Azure Application Insights Jun 29, 2018
global.json .NET Core: Bump to .NET Core SDK 2.1 Jun 22, 2018

Xamarin Workbooks


Xamarin Workbooks provide a blend of documentation and code that is perfect for experimentation, learning, and creating guides and teaching aids.

Create a rich C# workbook for .NET Core, Android, iOS, Mac, or WPF, and get instant live results as you learn these APIs. Workbooks also have access to the vast NuGet package ecosystem to make learning new APIs a breeze.




Provide Feedback

Continuous Integration Status

Service macOS Windows Linux

Build & Run

Ensure git submodules are up-do-date:

git submodule sync
git submodule update --recursive --init

Now simply run:

msbuild /restore

Or for the strict .NET Core subset:

dotnet build

Configuring the Build

The top-level build system can be driven either by the system msbuild or by the installed .NET Core SDK dotnet build. When using dotnet build, only projects that can run on .NET Core will be built.

Additionally, the build can be shaped via profiles. Any number of profiles may be selected. By default, all profiles will be selected.


Profiles are specified via the MSBuild Profile property and may be combined with a + delimiter:

msbuild /restore /p:Profile=Console+Web
Name Description Minimum Dependencies
Web Build the ASP.NET Core Workbooks server .NET Core ≥ 2.1, Node.js ≥ 8.10, Yarn ≥ 1.5.1
Console Build the Console client .NET Core ≥ 2.1
Desktop Build the macOS or Windows desktop client Visual Studio 2017 ≥ 15.6

Note: Support for Xamarin platforms will be detected automatically and built if available. On macOS, the "macOS" platform (Xamarin.Mac) must be installed to build the client. Xamarin/mobile is entirely optional on Windows.


Many properties that can be specified on the command line will be persisted for subsequent runs. For example:

# "Configure" and perform initial build:
msbuild /restore \
  /p:Profile=Web \
  /p:Configuration=Release \

# Rebuild with the same configuration as above, implied
# thanks to _build/Configuration.props:

The following properties will persist and do not need to be specified on the command line on subsequent runs:

Name Description Default Value
Profile The set of profiles to build Web+Console+Desktop
Configuration The build configuration (Debug or Release) Debug
WithoutXamarin A shortcut for setting all HaveXamarin* properties below to false unset
HaveXamarinMac Whether or Xamarin.Mac is available to the build auto-detected
HaveXamarinIos Whether or Xamarin.iOS is available to the build auto-detected
HaveXamarinAndroid Whether or Xamarin.Android is available to the build auto-detected
External Tools:
NuGet Path to nuget.exe resolved via PATH
Node Path to node resolved via PATH
Yarn Path to yarn resolved via PATH
Npm Path to npm resolved via PATH

Windows Nuances

If you want to build a Release build on Windows (for example, you want to build an installer), you will need to build in a slightly different fashion. First, make sure that you connect to a Mac build host via Visual Studio at least once. You can do this by doing the following:

  • Open Visual Studio
  • Go to Tools → Options → Xamarin → iOS Settings
  • Click "Find Xamarin Mac Agent"
  • Select a Mac on your network, or add one by name
  • Enter credentials when prompted

Once the connection completes, click OK to close all the dialogs. Then, build the Release configuration by running the following:

msbuild \
  /p:MacBuildHostAddress="<hostname-or-ip-of-your-mac>" \
  /p:MacBuildHostUser="<mac-username>" \
  /p:Configuration=Release /t:Build,Install

This is needed because the installer build now needs a zipped copy of the Xamarin.iOS workbook app from the server. The Xamarin.Workbooks.iOS project will do the build and copy automatically when a Mac build host is used. If you are building in Debug, you can omit those properties unless you need the Workbook app to be copied locally, in which case, include them there as well.

Note: the build will read properties from Build/Local.props as well, for example:



This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact with any additional questions or comments.



Official builds and releases of Xamarin Workbooks & Inspector from Microsoft collect usage data and send it to Microsoft to help improve our products and services. Read our privacy statement to learn more.

Users may opt out of telemetry and usage data collection from the Preferences dialog.

Non-Microsoft builds do not enable telemetry collection at all.

Third Party Code

Xamarin Workbooks & Inspector incorporates open source code from external projects. See ThirdPartyNotices.txt for attribution.