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.

Resources

Download

Documentation

Provide Feedback

Build & Run

macOS	Windows

External Build Dependencies & Development Environment

We generally track the latest (usually stable, but sometimes preview) releases of the Visual Studio / Xamarin release cycles. Below are complete sets of dependencies for building Workbooks on macOS and Windows. The dependency lists are generated by our VSTS build machines.

macOS Dependencies

Component	Version	Download
NuGet CLI	4.4.1	nuget.exe
Xcode	9.1.0
Node.js	8.9.1	node-v8.9.1.pkg
.NET Core	2.0.3	dotnet-sdk-2.0.3-osx-gs-x64.pkg
PowerShell Core	6.0.0-rc	powershell-6.0.0-rc-osx.10.12-x64.pkg
Mono	5.4.1.7	MonoFramework-MDK-5.4.1.7.macos10.xamarin.universal.pkg
Xamarin.iOS	11.4.0.214	xamarin.ios-11.4.0.214.pkg
Xamarin.Mac	4.0.0.214	xamarin.mac-4.0.0.214.pkg
Xamarin.Android	8.1.0-23	xamarin.android-8.1.0-23.pkg
Visual Studio for Mac (Preview)	7.3.0.764	VisualStudioForMac-Preview-7.3.0.764.dmg

Windows Dependencies

Component	Version	Download
Visual Studio Preview (any edition)	15.5.0	Download • Ensure the Xamarin workload is selected when installing
.NET Core	2.0.2	dotnet-sdk-2.0.2-win-x64.exe
Node.js	6.11.5	node-v6.11.5-x64.msi
NuGet CLI	4.3.0	nuget.exe
Git	2.14.3	Git-2.14.3-64-bit.exe
7-Zip	17.01	7z1701-x64.msi

Building

Ensure git submodules are up-do-date:

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

Any edition of Visual Studio or Visual Studio for Mac can be used to develop, build, and run Xamarin Workbooks by opening the top-level Xamarin.Interactive.sln solution. The entire solution is shared on macOS and Windows, so you will need to set the solution platform appropriately in Visual Studio:

OS	Solution Platform	Solution Configuration
macOS	`macOS`	`Debug` (default) or `Release`
Windows	`Windows`	`Debug` (default) or `Release`

It is recommended that your local builds use the default Debug solution configuration.

Finally, building from the command line is straightforward on both macOS and Windows. Unlike when building from Visual Studio, building directly via Build.proj does not require the solution platform (/p:Platform) to be set manually.

msbuild Build.proj

`Build.proj` Targets

Our top-level Build.proj MSBuild project has a number of useful targets:

Target	Description
`Build` (Default)	Perform a complete build of all projects
`Clean`	Clean all projects
`Package`	Builds a macOS `.pkg` or Windows `.msi` installer
`TestRegressions`	Runs the regression unit test suite
`UpdatePublicApiDefinitions`	Updates the API reference file with any changes in public API for the Xamarin.Workbooks.Integration NuGet
`UpdatePublicApiDocs`	Performs an `mdoc update` of API documentation for `Xamarin.Interactive.dll`
`AssemblePublicApiDocs`	Performs an `mdoc assemble` of API documentation for `Xamarin.Interactive.dll`

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 Build.proj \
  /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:

<Project>
  <PropertyGroup>
    <MacBuildHostAddress>porkbelly</MacBuildHostAddress>
    <MacBuildHostUser>aaron</MacBuildHostUser>
  </PropertyGroup>
</Project>

Contributing

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 https://cla.microsoft.com.

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 opencode@microsoft.com with any additional questions or comments.

Notices

Telemetry

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.

aduguid/workbooks