Matt Ward

NuGet Support in Visual Studio for Mac 7.0

New Features

  • .NET Core support
  • NuGet 4.0 support

More information on all the new features and changes in Visual Studio for Mac 7.0 can be found in the release notes.

.NET Core Support

.NET Core projects do not show a Packages folder in the Solution window. Instead the NuGet packages are displayed in a NuGet folder, which is inside a Dependencies folder.

Newtonsoft.Json NuGet package in Solution window - .NET Core project

The version of the NuGet package is displayed directly in the Solution window. For other project types you need to right click the package to see the version.

If the NuGet package depends on other packages then these can be seen by clicking on the arrow to expand the dependencies.

Newtonsoft.Json NuGet package expanded in Solution window - .NET Core project

Restoring Packages

NuGet packages will be restored automatically on opening a .NET Core project. This can be disabled in preferences by unchecking Automatically restore packages when opening a solution in the NuGet – General section.

You can manually restore NuGet packages for .NET Core projects by:

  • Right clicking the Dependencies folder and selecting Restore.
  • Right clicking the NuGet folder and selecting Restore.
  • Selecting Restore NuGet Packages from the Project menu.

Selecting Restore NuGet Packages from the Project menu will restore packages for the project or the solution depending on what is currently selected in the Solution window.

Restoring NuGet packages for a .NET Core project works differently compared with a project that uses a packages.config file. The NuGet packages themselves will be downloaded into the NuGet package cache folder ~/.nuget/packages if they do not exist, as before, but the NuGet packages will not be copied into a packages directory inside the solution’s directory. The project file will not contain have any Reference items added when a NuGet package is installed.

When a NuGet restore is run for a .NET Core project three files in the obj directory are created.

  • project.assets.json
  • ProjectName.csproj.nuget.g.props
  • ProjectName.csproj.nuget.g.targets

The project.assets.json file contains the dependencies for your project.

The nuget.g.props and nuget.g.targets files will contain any MSBuild imports that your NuGet package requires and they also define some properties, such as the path to the NuGet package cache on your machine.

These three files are used when building your project to resolve the assemblies to be referenced now that they are no longer explicitly stored in your project file.

Updating Packages

NuGet packages can be updated by:

  • Right clicking the package inside the NuGet folder and selecting Update.
  • Right clicking the NuGet folder and selecting Update.
  • Right clicking the Dependencies folder and selecting Update.
  • Selecting Update NuGet Packages from the Project menu.

Selecting Update NuGet Packages from the Project menu will update all packages in the project or in the solution depending on what is currently selected in the Solution window.

Removing Multiple NuGet Packages in One Step

You can remove multiple NuGet packages in one step from a .NET Core project by selecting the packages in the Solution window, right clicking and selecting Remove.

Removing multiple NuGet packages in Solution window - .NET Core project

Projects that use a packages.config file do not support removing multiple NuGet packages in one step.

Installing NuGet Packages

NuGet packages are installed by using the Add Packages dialog in the same way as with other project types. To open the Add Packages dialog for a .NET Core project:

  • Right click the NuGet folder and select Add Packages…
  • Right click the Dependencies folder and select Add Packages…
  • Right click the project and select Add – Add NuGet Packages…
  • From the Project menu select Add NuGet Packages…

When the first NuGet package is installed into a .NET Core project a packages.config file will not be created. Instead the NuGet package will be added as a PackageReference that is saved in the project file.

Package Reference

.NET Core projects do not use a packages.config file to record their NuGet dependencies. Instead the .NET Core project file will contain a PackageReference after the NuGet package is installed into the project.

1
2
3
4
5
6
7
8
9
10
11
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp1.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Newtonsoft.Json" Version="10.0.2" />
  </ItemGroup>
</Project>

Please note that Visual Studio for Mac currently only supports package references with the new SDK style projects which are used by .NET Core. If you use package references in other project types then the Solution window will not show the packages and a packages.config file will be created if you install a NuGet package.

Updated Packages Available

For other project types the Solution window will check for updated packages and show this information in the Packages folder. This is not currently supported with .NET Core projects.

NuGet 4.0 Support

Visual Studio for Mac now includes NuGet 4.0.

More information on the new features provided by NuGet 4.– can be found in the Announcing NuGet 4.0 RTM blog post and the NuGet 4.0 release notes.

NuGet Support in Xamarin Studio 6.2

  • Integrated support for creating NuGet packages with NuGetizer 3000
  • NuGet 3.5 support
  • Improved project.json support
  • Native License Acceptance dialog

More information on all the new features and changes in Xamarin Studio 6.2 can be found in the release notes.

NuGetizer 3000

NuGetizer 3000 is a set of build tools for creating NuGet packages inspired by NuProj. Support for NuGetizer 3000 in Xamarin Studio includes:

  • Project templates for creating NuGet packages
  • Support for creating a NuGet package from an existing project
  • Reference assembly generation for Portable Class Library profiles

The following sections look at the NuGetizer 3000 features provided by Xamarin Studio. For more detailed information on what is supported by NuGetizer 3000 please read the NuGetizer 3000 feature spec.

Project Templates

There are two new project templates available.

  • Multiplatform Library
  • NuGet package

Mulitplatform Library project template in New Project dialog

NuGet Package project template in New Project dialog

Multiplatform Library – Single for all platforms

The Mulitplatform Library project template will create a Portable Class Library project with NuGet package metadata when the Single for all platforms option is selected.

Multiplatform library - single for all platforms selected

To create a NuGet package right click the project and select Create NuGet Package. This will generate a NuGet package (.nupkg) in the output directory with the Portable Class Library assembly in the corresponding portable lib directory inside the NuGet package.

Multiplatform Library – Platform specific

This Multiplatform Library will create a shared project, an iOS project, an Android project and a NuGet packaging project when the iOS and Android options are selected.

Multiplatform library - iOS and Android selected

The iOS and Android project will reference the shared project. The NuGet packaging project will reference the iOS and Android projects. The NuGet packaging project will contain the NuGet package metadata.

When the NuGet packaging project is built it will create the NuGet package in its output folder and inside the NuGet package will be the Android and iOS output assemblies each in their own platform specific lib folders.

NuGet Packaging Project

NuGet package project template configuration

The NuGet packaging project can be used to create a meta NuGet package, which is a NuGet package that has no content itself but references other NuGet packages, or it can reference other projects and it will add their output assemblies to the NuGet package. If the referenced project has NuGet package references then these will be added to the generated NuGet package as dependencies.

NuGet packages can be added to the NuGet packaging project by using the Add Packages dialog.

To include files in the NuGet packaging project the files need to have Include in Package property set to true. This can be done by right clicking the file in the solution window, selecting Properties, then selecting Include in Package from the NuGet section in the Properties window.

Include in Package in Properties window

Adding NuGet Package Metadata

NuGet package metadata can be added to any .NET project by selecting the NuGet Package – Metadata page available in the project options.

NuGet package metadata in project options

The General tab shows compulsory metadata that must be specified for a NuGet package. The Details tab shows other optional metadata that can be specified. This NuGet package metadata is saved directly into the project file (.csproj).

NuGet package metadata in project options

Once NuGet package metadata has been added then the NuGet.Build.Packaging NuGet package will be added to the project if it does not already exist. This NuGet package provides MSBuild tasks that are used when creating the NuGet package for the project.

NuGet package metadata should be added to project if you want to be able to create a NuGet package for that project on its own. Without NuGet package metadata the project would need to be referenced by a NuGet packaging project, or another project with NuGet package metadata, for it to be included in a NuGet package.

If a NuGet packaging project references a project that has its own NuGet package metadata then a dependency will be added to the NuGet package created by the NuGet packaging project. The referenced project’s output assembly would not be included in the NuGet package created by the packaging project in this case.

Generating a NuGet Package

To generate a NuGet package you can right click the project and select Create NuGet Package.

Create NuGet Package menu item

For NuGet packaging projects you can also build the project and it will create a NuGet package.

For a .NET project that has NuGet package metadata you can generate a NuGet package when building the project by enabling the “Create a NuGet Package when building the project” option in the Project Options dialog.

Creating a NuGet Package when building the project - project options

Adding Platform Implementations

If you have a Portable Class Library with NuGet package metadata you can add platform specific implementations for iOS and Android by right clicking the project and selecting Add – Add Platform Implementation. This will open a dialog where you can choose iOS and Android, and also whether to create a shared project.

Add Platform Implementation dialog

After clicking OK an Android and iOS project will be created along with a NuGet packaging project that references these projects. The NuGet package metadata will be moved from the Portable Class Library project to the NuGet packaging project. If the shared project option was selected then the code from the Portable Class Library project will be moved to the shared project. The shared project will be referenced by the iOS and Android project.

Reference Assembly Generation

In the Project Options for a NuGet Packaging project there is a Reference Assemblies page in the NuGet Package category. This pages shows a list of Portable Class Library profiles that can be selected.

Reference assemblies in project options

Reference assemblies for the selected profiles will be generated based on the output assemblies from the projects referenced by the NuGet packaging project.

That brings us to the end of the walkthrough of the NuGetizer 3000 features provided by Xamarin Studio.

NuGet 3.5 Support

Xamarin Studio now includes NuGet 3.5.

More information on the new features provided by NuGet 3.5 can be found in the Announcing NuGet 3.5 RTM blog post and the NuGet 3.5 release notes.

Improved project.json Support

NuGet packages are now automatically restored when the project.json file is saved in the text editor.

Native License Acceptance Dialog

The Licence Acceptance dialog now uses native UI.

License Acceptance dialog

Bug Fixes

Updating all NuGet packages installs unexpected pre-release NuGet packages

With a pre-release NuGet package installed in a project, updating all the NuGet packages in the project could cause the stable NuGet packages to be updated to pre-release versions. On updating all the packages if any were pre-release the include pre-release flag would be set on updating which would allow any pre-release NuGet packages to be used on updating. Now the include pre-release flag is not set on updating. NuGet 3 will still update pre-release NuGet packages to the latest pre-release or latest stable, depending on which is the latest version, without this include pre-release flag being set. NuGet 2 required the include pre-release flag set to update a pre-release to the latest pre-release.

An example – project has the following NuGet packages installed:

Xamarin.Forms 2.3.3.180
Xamarin.Forms.CarouselView 2.3.0-pre1

Latest available packages from nuget.org:

Xamarin.Forms 2.3.3.180 (latest stable)
Xamarin.Forms 2.3.4.184-pre1 (latest pre-release)
Xamarin.Forms.CarouselView 2.3.0-pre2

Expected result on updating all packages in the project:

Xamarin.Forms 2.3.3.180
Xamarin.Forms.CarouselView 2.3.0-pre2

Actual result:

Xamarin.Forms 2.3.4.184-pre1
Xamarin.Forms.CarouselView 2.3.0-pre2

Types unavailable when NuGet package added to project.json file

When a NuGet package was added to a project that used a project.json file the types from the assembly provided by the NuGet package were not available until the project was reloaded or the references were modified. This prevented code completion from showing the correct information.

PowerShell Support in Xamarin Studio

Xamarin Studio version 6.0 and later now have PowerShell editing and debugging support with a PowerShell addin. The PowerShell addin uses the PowerShell Editor Services which is also used by the PowerShell extension for Visual Studio Code.

Debugging a PowerShell script in Xamarin Studio

Features

  • Code completion
  • Debugging support
    • Immediate window
    • Locals window
    • Watch window
  • Find references
  • PowerShell file template
  • Rename variable or method
  • Show API documentation
  • Syntax highlighting

Requirements

Xamarin Studio 6.x or MonoDevelop 6.x.

PowerShell 6 needs to be installed on Mac and on Linux.

PowerShell 3 and higher are supported on Windows.

Code Completion

As you type in the text editor you will see code completion for PowerShell variables.

PowerShell variable code completion

Code completion for PowerShell commands.

PowerShell command code completion

An overview of PowerShell command parameters when you press the space key after entering a PowerShell command.

PowerShell command parameters overview code completion

Code completion for PowerShell command parameters.

PowerShell command parameter code completion

Hovering the mouse over a PowerShell command will show a tooltip with information about that command.

PowerShell command tooltip on hover

Syntax Errors

Syntax errors are highlighted in the text editor. Hovering the mouse over the highlighted error will show information about the error.

PowerShell syntax error highlighting

Find references

To find references of a variable or a method you can right click in the text editor and select Find References.

PowerShell find references text editor context menu

The references found are then displayed in the Search Results window.

PowerShell find references text editor context menu

Rename

A variable or method can be renamed in the text editor by right clicking and selecting Rename.

PowerShell rename text editor context menu

On typing the new name and the text will be replaced.

Show API Documentation

Right clicking on a PowerShell command and selecting Show API Documentation will open the online help for that PowerShell command, if it is available, in the web browser.

API Documentation text editor context menu

PowerShell API documentation web page

Creating a new PowerShell Script

To create a new PowerShell script there is an empty PowerShell file template available from the New File dialog.

PowerShell script file template in New File dialog

After creating a new PowerShell file it must be saved before it can be run or debugged.

Debugging

To debug the currently active PowerShell file open in the text editor, set a breakpoint on a line by clicking in the left hand margin, then select Start Debugging from the Run menu.

Run - Start Debugging menu

Alternatively you can click the Run button in the main toolbar.

Run button in the main toolbar

A solution does not need to be open in order for a PowerShell script to be run with the debugger. You can open just a PowerShell script into Xamarin Studio and then run the debugger.

Once the debugger has started you can select Step Over, Step In, Step Out or Continue Debugging from the Run menu by clicking one of the main toolbar buttons.

Run menu with Step menu items

Hovering the mouse over a variable will open a tooltip showing the variable value.

Debug tooltip on hover

Breakpoints

Breakpoint conditions should use PowerShell syntax and not C# syntax. The Edit Breakpoint dialog says to use a C# boolean expression which is incorrect.

PowerShell breakpoint condition in Edit Breakpoint dialog

Hit conditions are only partially supported. The PowerShell Editor Services debugger supports the ‘When hit count is equal to’. Due to this restriction the other hit count options may not work as expected.

Printing a message and continuing is not currently supported.

Breaking when the value of an expression changes is not currently supported.

Function and exception breakpoints are not currently supported.

Locals Window

When debugging the Locals window will show the values of variables grouped by each PowerShell scope – Auto, Local, Script and Global.

Locals Window

Watch Window

Variables and expressions can be entered in the Watch Window.

Watch window

Please note that entering a PowerShell command with missing parameters will cause the debugger to stop working. The PowerShell file will need to be closed and re-opened before the debugger will work again.

Immediate Window

Expressions and variables can be entered in the immediate window to get or set values.

Immediate window

As with the Watch Window, entering a PowerShell command with missing parameters will cause the debugger to stop working.

Passing Arguments when Debugging

To pass arguments when debugging a PowerShell script you can select Debug PowerShell Script… from the Run menu.

Run - Debug PowerShell Script menu

This will open a Debug PowerShell Script dialog where arguments can be specified. These arguments will be passed to the PowerShell script being run with the debugger. The settings used in this dialog will be remembered for the active text editor whilst it is open in Xamarin Studio.

Debug PowerShell Script dialog

Launch Configuration Support

In Visual Studio Code a launch.json file can be used to store launch configurations. These are supported in by the PowerShell addin in Xamarin Studio. The PowerShell addin will look for a launch.json file in the directory where the PowerShell file exists or in a .vscode subdirectory.

The launch configurations are shown under Active Configurations in the Run menu. Only PowerShell launch configurations which have a request type of “launch” are supported.

PowerShell launch configurations in Run menu

The currently selected launch configuration will be used when debugging or running the PowerShell script. By default no launch configuration will be selected.

Running without the Debugger

To run the PowerShell file with PowerShell directly, instead of using the debugger, select Start without Debugging from the Run menu.

Run - Start without Debugging menu

Output from the PowerShell script will be displayed in the Application Output window.

PowerShell script Application Output window

Installation

The PowerShell addin is available from the MonoDevelop addin repository on the beta channel. To install the addin open the Add-in Manager, search for the PowerShell addin, then click the Install button.

PowerShell addin in Addin manager dialog

Source Code

NuGet Support in Xamarin Studio 6.1

Xamarin Studio 6.1 was released last week as part of the latest stable Xamarin Platform release and it includes changes made to the NuGet support.

Changes

  • NuGet 3.4.3 support
  • Support for project.json files
  • A specific NuGet package version can now be installed from a list shown in the Add Packages dialog
  • NuGet operations can now be cancelled from the status bar or Package Console
  • Support browsing for a local directory when creating a package source
  • Support forcefully removing a NuGet package when it is missing from all package sources
  • Packages installed in the solution are no longer shown in the Add Packages dialog
  • Only global package sources are now shown in Preferences
  • NuGet version supported is now displayed in the About dialog

More information on all the new features and changes in Xamarin Studio 6.1 can be found in the release notes.

NuGet 3.4.3 support

Xamarin Studio now includes NuGet 3.4.3 which means project.json files are now supported and NuGet packages that only support NuGet 3 or above can now be installed.

Support for project.json files

The project.json file is a new package file format introduced with NuGet 3 which supports transitive restore. More detailed information on project.json can be found in the NuGet documentation.

A project.json file replaces the packages.config file and holds the NuGet packages being used by the project. One difference you will notice is that the project.json file may not show the same list of NuGet packages that a packages.config file would show. This is because the project.json file only shows the NuGet packages you explicitly install into your project. So if you install say bootstrap you will only see bootstrap in the project.json file even though it depends on jQuery. If you do the same for a packages.config file you would see both bootstrap and jQuery saved in the file. Another difference is that references are not added to your project file (.csproj) when using a project.json file.

In order to use a project.json file with Xamarin Studio you will need to create the file yourself in the project directory and close and re-open the solution. The project.json file needs to be available when you open the project otherwise Xamarin Studio will default to using a packages.config file.

An example project.json file for a .NET 4.5 library project is shown below:

{
  "frameworks": {
    "net45": {}
  }
}

When you add a NuGet package to a project that uses a project.json file the NuGet package information will be added into a dependencies section:

 "dependencies": {
   "NUnit": "3.2.1"
 }

Please note that when using a project.json file the project will not display a From Packages directory inside the References folder. This is because the project file does not have any references added to it when using a project.json and the reference information is currently not available from the project system.

Please note that there are future plans to move the information stored in a project.json file into the project file.

NuGet 3 package source

Xamarin Studio now supports using the NuGet 3 package source:

https://api.nuget.org/v3/index.json

This can be added into your package sources in Preferences. It is also the package source that will be created by default if your global NuGet.Config file is missing.

Installing a specific NuGet package version from the Add Packages dialog

Older versions of Xamarin Studio supported being able to install specific package versions by using a package version search in the Add Packages dialog as shown below:

NUnit version:*

This package version search was not easy to discover and so it has been removed and replaced in Xamarin Studio 6.1 with a combo box that allows a particular version to be selected. The Version combo box is in the bottom right hand corner of the Add Packages dialog as shown in the screenshots below.

Add Packages dialog

Add Packages dialog with version combo box selected

Note that in order to populate the version combo box a second request is sent to the package source so it may not show all the versions immediately.

Also note that for package sources which are local directories only the latest version will be displayed in the version combo box.

Cancelling a NuGet operation

With Xamarin Studio you can now cancel the currently running NuGet package operation. This can be done by clicking the red Stop button in the Status Bar or in the Package Console.

Status bar stop button

Adding local package sources

When adding a package source in Preferences it is now easier to create a package source for a directory on your local machine. There is now a browse button which will allow you to browse to a directory and add it rather than having to type the full path into the text box.

Add Package Source dialog

The Add Package Source dialog has also been changed to make it more obvious that either a URL or a folder can be used as a package source. The URL label has been changed to Location and the placeholder text now specifies that a URL or a folder can be used.

Forced NuGet package removal

A NuGet package can now be removed when it not restored and is unavailable from all package sources.

With older versions of Xamarin Studio a NuGet package must be restored before it can be removed. This is a requirement of NuGet since it requires the original NuGet package to work out what has been installed so it can determine what needs to be uninstalled. NuGet can do more than just update the project file with references and MSBuild .targets files, it may add new files to the project or it may run app.config or web.config transforms.

When the NuGet package removal fails because the NuGet package cannot be restored a dialog will be displayed asking whether you want to try to remove the NuGet package anyway. If the OK button is selected then Xamarin Studio will:

  1. Remove the NuGet package from the packages.config file.
  2. Remove any assembly references for the NuGet package from the project file (.csproj).
  3. Remove any Imports that refer to .targets or .props files that were included with that NuGet package.

This process may miss files that were added to the project by NuGet but in the majority of cases it should remove the NuGet package successfully without having to manually remove the NuGet package information from the project file.

Packages installed in solution are no longer shown in Add Packages dialog

With previous versions of Xamarin Studio all packages installed in the solution were shown first in the list of packages in the Add Packages dialog. Packages installed in the solution are now no longer shown in the Add Packages dialog.

Only global package sources shown in Preferences

The package sources shown in the Preferences dialog are now only read from the global NuGet config file. Per-solution NuGet.Config files located in individual solution directories are no longer read when showing the package sources in Preferences. This is because changes made in Preferences only modifies the global NuGet.Config file.

The package sources shown in the Add packages dialog will still include package sources defined in a solution’s NuGet.Config file and is unaffected by this change.

NuGet version displayed in About dialog

The version of NuGet supported by Xamarin Studio is now displayed in the About dialog when the Show Details button is selected.

About dialog

Bug Fixes

Custom MSBuild .targets files were not always added to the end of the project

When installing a NuGet package that has a .targets file the Import element created was grouped with the existing Import elements. This is OK most of the time however if there are other items in the project added after the import then any build targets may fail since these items are included after the import. One example is the netfx-System.StringResources NuGet package which may not find any resource files that occur in the project after its Import element.

Now .targets files are added as the last element in the project file. This also makes the behaviour consistent with how NuGet works in Visual Studio.

Custom MSBuild .props files were not added to the start of the project

Installing a NuGet package that included an MSBuild .props file would add an Import element for the .props file at the end of the project file which is incorrect. Now .props files are added to the project file as the first child element inside the Project’s root element.

Known Issues

Offline package restore

Package restore may not work when you are offline even though the NuGet packages may be available in the local NuGet cache on your machine.

The current workaround is to create a package source that points to a local directory containing all the required NuGet packages and disable all online NuGet package sources. With just the local package source enabled you can then restore the NuGet packages when you are offline. Note that this problem also affects Visual Studio 2015.

NuGet Package Explorer for Xamarin Studio

When diagnosing why a NuGet package cannot be installed into a project the application I use is the excellent NuGet Package Explorer. Whenever there is an error trying to install a NuGet package, similar to the one shown below, you can open the NuGet package with NuGet Package Explorer and take a look at the target frameworks it supports.

You are trying to install this package into a project that targets 'MonoAndroid,Version=v6.0',
but the package does not contain any assembly references or content files that are compatible with that framework.

Currently NuGet Package Explorer is only available on Windows. On other operating systems you can change the file extension to .zip, extract the contents of the NuGet package, or open it into a zip application, and take a look at the files.

To make exploring NuGet packages easier on operating systems where the NuGet Package Explorer application is not available there is a now NuGet Explorer addin that you can install into Xamarin Studio or MonoDevelop. With this addin you can open and explore NuGet packages from online package sources or from the local file system.

Exploring the Xamarin.Android.Support NuGet package in Xamarin Studio

Now let us take a look in more detail of the features provided by the NuGet Package Explorer addin.

Features

  • Open and view NuGet packages from online package sources or from the local file system.
  • View the NuGet package metadata.
  • View the NuGet package files.
  • View the NuGet package .nuspec file.
  • Open any file stored inside the NuGet package.
  • Open other NuGet packages that are listed as dependencies.

Supports Xamarin Studio 6.0 and MonoDevelop 6.0.

Opening a NuGet Package from a Package Source

To open a NuGet package from a package source you can select Open NuGet Package from the File menu.

File Open NuGet Package menu

Alternatively if you have a project open you can right click the Packages folder in the Solution window and select Open NuGet Package.

Open Package menu on Packages folder

This will open the Open Package dialog. This dialog is the same as the Add Packages dialog used when installing a NuGet package and allows you to search for NuGet packages. The dialog is based on the version available with Xamarin Studio 6.1 so it has a version combo box where you can select a specific package version instead of having to remember the syntax for the package version search.

Open Package dialog

Select one or more NuGet packages and click the Open Package button to download and display them in Xamarin Studio.

Exploring the JSON.NET NuGet package in Xamarin Studio

The NuGet package metadata is shown on the left. On the right are the files that the NuGet package contains. You can also view the .nuspec file stored in the NuGet package by selecting the NuSpec tab at the bottom of the window.

Viewing JSON.NET .nuspec file

Exploring Dependencies

NuGet package dependencies are displayed with hyperlinks.

If you click one these hyperlinks the Open Package dialog will be opened and the package will be searched for. You can then choose a package version and open the NuGet package.

Opening Files Contained Inside the NuGet Package

To open a file contained inside a NuGet package you can double click the file, or right click the file and select Open.

Open menu to open file inside NuGet package into Xamarin Studio

The file will then be opened inside Xamarin Studio.

Opening a NuGet Package File

If you have a NuGet Package (.nupkg) stored on the local machine that is not available from any package source you can open the file directly in Xamarin Studio by selecting Open from the File menu.

You can also associate .nupkg files directly with Xamarin Studio and have them automatically open inside the IDE.

Opening a NuGet Package Installed in a Project

You can explore NuGet packages that are installed in your project by right clicking the package in the Solution window and selecting Open Package.

Open installed package context menu

Installing the NuGet Package Explorer addin

The NuGet Package Explorer addin is available from the MonoDevelop addin repository on the beta channel. It can be installed by from the Add-in Manager by searching the gallery and then clicking the Install button.

Addin Manager dialog

File Nesting in Xamarin Studio

With recent versions of Xamarin Studio it is not currently possible to nest files without directly editing the project file. In the past it was possible to drag and drop a file so it was then nested inside another file.

Solution window with nested files in Xamarin Studio

Visual Studio also does not support nesting files by using drag and drop however Mads Kristensen created a File Nesting extension that adds support for manual and automatic nesting of files within Visual Studio. There is a demo video of the File Nesting extension that shows the extension being used with Visual Studio. This extension has now been ported to Xamarin Studio and is available from the MonoDevelop Add-in Repository.

Let us take a walkthrough of the features of the File Nesting addin for Xamarin Studio.

Features

  • Manual file nesting
  • Manual file un-nesting
  • Automatic file nesting of selected files based on rules
  • Automatic file nesting when files are added to a project
  • Options to specify which file nesting rules are applied

Supports

  • Xamarin Studio 6.0 or MonoDevelop 6.0.

Manual File Nesting

To manually nest a file select it in the Solution window then right click and select File Nesting – Nest Item…

Manual file nesting - nest item context menu

This will open a file nesting dialog where the parent file can be selected.

File nesting dialog

Select the parent file and click OK to nest the file under that parent file.

Manual file nesting result in solution window

You can also nest multiple files under a parent by selecting multiple files in the Solution window and selecting the Nest Item menu.

Manual File Un-nesting

To un-nest a file select it in the Solution window then right click and select File Nesting – Un-nest Item.

Manual file nesting - un-nest item context menu

The file will then be un-nested from its parent.

Manual file un-nesting result in solution window

Automatic Nesting Rules

The file nesting rules are available from the Preferences dialog.

File nesting rules in preferences

Each rule has a tooltip which will show more detailed information about what the rule does.

Enable auto-nesting

The Enable auto-nesting option will enable or disable automatic file nesting when a file is added to a project.

Enable extension rule

This rule will nest files added with an extra extension under their corresponding parent file. For example MyView.xaml.cs nests under MyView.xaml.

Nested file using extension rule

Enable interface implementation rule

This nests C# interface implementations under the corresponding interface based on the filename. For example, if there is an interface file IMyInterface.cs then a new file called CustomMyInterface.cs will be nested under the IMyInterface file.

Nested file using interface implementation rule

Enable known file type rule

This nests certain known files types. For example, MyPage.ts will be nested under MyPage.html.

Nested file using known file type rule

Enable path segment rule

This nests files with an added path segment under its parent. For example, MyFile.Designer.cs nests under MyFile.cs.

Nested file using path segment rule

Automatic Nesting of Selected Files

To automatically nest files, based on the enabled file nesting rules, select the files, or folder, or project, then right click and select File Nesting – Auto-nest selected items.

Auto-nest selected items context menu

This will then apply the enabled file nesting rules to the selected files.

Automatic File Nesting on Adding Files

To enable automatic file nesting when files are added right click the project and select File Nesting – Enable automatic nesting.

Enable automatic nesting context menu

A check box will be displayed next to this menu item if this feature is enabled. Now when a file is added the enabled nesting rules will be applied and the file will be automatically nested.

Installation

The File Nesting addin is available from the MonoDevelop Add-in Repository on the beta channel. To install the addin open the Add-in Manager, search for the File Nesting addin, then click the Install button.

File Nesting addin in addin manager window

After installing the addin Xamarin Studio will need to be restarted for the addin to work correctly.

Source Code

.NET Core Test Runner Support in Xamarin Studio

The latest version of the .NET Core addin for Xamarin Studio and MonoDevelop now supports .NET Core Test Runners.

.NET Core Test Runner in Xamarin Studio

Xamarin Studio uses the .NET Core test communication protocol to support .NET Core test runners. This protocol provides a way to discover and run the unit tests provided by a .NET Core test runner.

When Xamarin Studio finds a testRunner in the project.json file it will attempt to discover the unit tests for that project.

{
    "version": "1.1.0-*",

    "testRunner": "nunit",

    "dependencies": {,
        "NUnit": "3.4.0",
        "dotnet-test-nunit": "3.4.0-beta-1"
    },

    "frameworks": {
        "netcoreapp1.0": {
            "imports": [
                "netcoreapp1.0",
                "portable-net45+win8"
            ],
            "dependencies": {
                "Microsoft.NETCore.App": {
                    "version": "1.0.0-*",
                    "type": "platform"
                }
            }
        }
    }
}

The discovered tests are then shown in the Unit Tests window.

Discovered NET Core unit tests in Unit Tests window

After building the project the Unit Tests window will discover any new tests that have been added.

Tests can be run by clicking Run All or by right clicking a test in the Unit Tests window and selecting Run Test.

Run NET Core unit tests in Unit Tests window

The test results are shown in the Test Results window.

.NET Core test results  in Test Results window

Console output from the test runner is shown in the Application Output window.

.NET Core Test Runner in Xamarin Studio

Debugging the unit tests is not yet supported.

xUnit and NUnit provide .NET Core test runners and both of these are supported in Xamarin Studio. More information can be found in existing tutorials on how to use these test runners:

NuGet Support in Xamarin Studio 6.0

Xamarin Studio 6.0 was released last week and it includes a lot of new features, such as a new dark theme and Roslyn integration. This release also includes some improvements made to the NuGet support.

Add Packages Dialog - Dark Theme

New Features

  • Support NuGet packages targeting tvOS.
  • Support updating pre-release NuGet packages.
  • Show updates available for pre-release NuGet packages.
  • Remember Show pre-release Packages setting in Add Packages dialog.
  • Error dialog displayed if NuGet.Config file cannot be read.

More information on all the changes in Xamarin Studio 6.0 can be found in the release notes.

Support NuGet packages targeting watchOS

A new Xamarin.WatchOS target framework is now supported which allows NuGet packages to contain assemblies for watchOS.

Support updating pre-release NuGet packages

Previously it was not possible to update a pre-release NuGet package to a later pre-release from the Solution window, only updates to stable NuGet packages were supported. The only way to update to a later pre-release NuGet package was to use the Add Packages dialog.

Now an individual pre-release NuGet package can be updated by right clicking and selecting Update. When all packages in a project or solution are updated then pre-release NuGet packages will be updated to a later pre-release version if they are available.

Show updates available for pre-release NuGet packages

Previously Xamarin Studio would only show stable NuGet package updates as being available if a pre-release NuGet package was installed. Now Xamarin Studio will check for updates for pre-release NuGet packages as well as stable packages and display this information in the Solution window.

Pre-release NuGet package updates in Solution window

Only if an installed NuGet package is a pre-release version will pre-release updates be shown as available in the Solution window. Xamarin Studio will not check for pre-release updates for stable NuGet package versions that are installed.

Remember Show pre-release Packages setting in Add Packages dialog

The Show pre-release Packages check box setting will now be remembered in the Add Packages dialog on a per solution basis.

Error dialog displayed if the NuGet.Config file cannot be read

Previously if the NuGet.Config file could not be read the error would be silently logged, but not reported, and Xamarin Studio would then switch to using the default official NuGet package source. Now an error dialog is shown indicating that there was a problem reading the NuGet.Config file.

Bug Fixes

Support NuGet packages that use icons from local files

A NuGet package can now use an icon, which will be shown in the Add Packages dialog, taken from the local file system using a file url. Previously this would fail with an invalid cast exception.

Incorrect update count displayed after updating NuGet packages.

When an update caused a NuGet package to be uninstalled the Packages folder in the Solution window would show an incorrect count for the available updates.

NuGet restore and update not working for workspaces

With a workspace opened, or multiple solutions opened in Xamarin Studio, then restoring and updating NuGet packages would only work for one of the solutions.

Unable to add Google Play Services packages

The Xamarin.Android.Support.v7.AppCompat NuGet package depends on a single version of the Xamarin.Android.Support.v4 NuGet package. When a Xamarin Google Play Services NuGet package is installed that depends on a higher version of the Xamarin.Android.Support.v4 NuGet package the install would fail to find a version of the AppCompat NuGet package that is compatible. An error similar to the following would be displayed in the Package Console window:

Could not add Xamarin.GooglePlayServices.Ads.
Updating 'Xamarin.Android.Support.v4 23.1.1.0' to
'Xamarin.Android.Support.v4 23.1.1.1' failed. Unable to find a version
of 'Xamarin.Android.Support.v7.AppCompat' that is compatible with
'Xamarin.Android.Support.v4 23.1.1.1'.

The problem was that the AppCompat NuGet package is not involved in the initial NuGet package resolution using the remote package source so it is initially not considered for installation into the packages directory. When a package reference is then added to the packages.config file a search for a compatible AppCompat package was only using the local solution’s packages directory which fails causing the install to fail.

To fix this the local solution packages directory is used first when looking for a compatible AppCompat NuGet package and will fallback to using the configured remote package sources if no suitable package is found in this directory. To handle a package being added to the packages.config at this point, after the original NuGet packages have already been downloaded to the solution’s packages directory, Xamarin Studio will detect a package is added to the packages.config file and install the NuGet package if it is not already in the local solution packages directory.

Incorrect package version being installed

When installing a NuGet package using the Google Play Services dialog a package version is not specified by the dialog. If the NuGet package being installed was found in the local machine’s NuGet cache it would be used instead of the latest version from the official NuGet gallery at nuget.org. This could result in a lower version being installed than expected.

MSBuild property files (.props) not being added at correct project location

Installing a NuGet package that included an MSBuild .props file would add an Import element for the .props at the end of the project file (.csproj) instead of at the start. The .props files are now added to the project file as the first child element inside the project’s root element.

ASP.NET Core 1.0 RC2 support in Xamarin Studio

Xamarin Studio and MonoDevelop now have support for ASP.NET Core 1.0 RC2 with an alpha release of the .NET Core addin.

ASP.NET Core web project in Solution window

This is an update of the original DNX addin which adds support for .NET Core RC2 and also, thanks to David Karlaš, adds support for debugging .NET Core applications on the Mac.

Features

  • Debugging .NET Core applications with the .NET Core CLR on Mac.
  • Project templates for console, library and web applications
  • Code completion
  • NuGet integration
  • Solution window integration

Supports

  • MonoDevelop and Xamarin Studio 6.0 (build 5166). (Note that 6.1 is not yet supported)
  • .NET Core 1.0 RC2.

Installing .NET Core SDK

The .NET Core SDK needs to be installed separately before using the .NET Core addin. Detailed installation instructions can be found on Microsoft’s .NET Core web site.

Installing the addin

The addin is currently available from MonoDevelop’s Add-in Repository in the alpha channel. In Xamarin Studio open the Add-in Manager and select the Gallery tab. Click the repository drop down and if Xamarin Studio Add-in Repository (Alpha Channel) is not displayed then click Manage Repositories. In the window that opens tick the check box next to Xamarin Studio Add-in Repository (Alpha Channel) and then click the Close button.

.NET Core addin selected in Addin Manager dialog

Select the .NET Core addin and then click the Install button.

After installing the .NET Core addin you will need to restart Xamarin Studio before the project templates are available in the New Project dialog.

Creating a .NET Core project

There are three project templates available for .NET Core in the New Project dialog.

New ASP.NET 5 project templates

Debugging

Thanks to David Karlaš there is a support for debugging .NET Core applications when running on the .NET Core CLR if you have the VSCode Debugger addin installed.

Debugging a .NET Core application

The VSCode Debugger addin is currently available from MonoDevelop’s Add-in Repository on the alpha channel.

Debugging .NET Core console and web projects that target the full .NET framework is supported on all platforms. The .NET Core command line tool (dotnet.exe) will create an executable when targeting the full .NET Framework which can be debugged in Xamarin Studio. On Windows the x86 version of the .NET Core SDK needs be installed since Xamarin Studio currently cannot debug x64 applications on Windows.

Source Code

The source code for the addin is available on GitHub.

ASP.NET 5 and DNX support in Xamarin Studio

Xamarin Studio and MonoDevelop now have support for ASP.NET 5 and DNX with an alpha release of the DNX addin.

DNX web project in Solution window

The core part of the addin that communicates with the DNX host is taken directly from OmniSharp and is used mostly unchanged.

Features

  • Project templates for console, library and web applications
  • Code completion
  • Debugger support with Mono 4.3
  • NuGet integration
  • Solution window integration

Supports

  • MonoDevelop and Xamarin Studio 5.9 and later versions.
  • ASP.NET 5 RC 1 Update 1 and earlier versions.

Installing ASP.NET 5

ASP.NET 5 needs to be installed separately before using the DNX addin. There are instructions on get.asp.net on how to do this for Mac, Linux and Windows.

Installing the addin

The addin is currently available from MonoDevelop’s Add-in Repository in the alpha channel. In Xamarin Studio open the Add-in Manager and select the Gallery tab. Click the repository drop down and if Xamarin Studio Add-in Repository (Alpha Channel) is not displayed then click Manage Repositories. In the window that opens tick the check box next to Xamarin Studio Add-in Repository (Alpha Channel) and then click the Close button.

Enabling alpha channel addins

Back in the Add-in Manager dialog click the Refresh button to update the list of addins. Use the search text box in the top right hand corner of the dialog to search for the addin by typing in DNX.

DNX addin selected in Addin Manager dialog

Select the DNX addin and then click the Install button.

After installing the DNX addin you will need to restart Xamarin Studio before the project templates will be available in the New Project dialog.

Creating an ASP.NET 5 project

There are three project templates available for ASP.NET 5 in the New Project dialog.

New ASP.NET 5 project templates

Each of the project templates will create a solution and an .xproj file in the same way as Visual Studio 2015 does. The projects created should be compatible with Visual Studio 2015.

DNX console project in Solution window

Dependencies

When you create or open an ASP.NET 5 project the NuGet packages it uses will automatically be restored.

Restoring NuGet packages in Solution window

In the Solution window the dependencies show a warning icon if they are not resolved and the Dependencies folder shows a message that it is restoring the NuGet packages. Once restored you can expand the Dependencies folder and see the dependency hierarchy.

Dependency hierarchy in Solution window

If the DNX runtime being used by the solution is not installed then an error icon will be displayed next to the Dependencies folder.

Dependencies error icon in Solution window

Hovering the mouse over the error icon will show more information about the error.

Building

When you build the solution or project any errors and warnings are displayed in the Errors window and in the text editor. No assemblies are generated when you build.

DNX build error in text editor

DNX build errors in Errors window

Running

The main toolbar shows the currently selected command and the framework that will be used when the application is run. These are taken from the project.json file.

DNX commands in main toolbar

The screenshot above shows the main toolbar for a web project. There are three entries:

  • web
  • web DNX 4.5.1
  • web DNX Core 5.0

The first entry will run the web command and use the default runtime which will currently be DNX 4.5.1. The last two entries will run the web command but will explicitly run the application with the specified runtime.

Debugging

Thanks to David Karlaš and Zoltan Varga there is support for debugging DNX applications with DNX 4.5.1 if you have Mono 4.3 installed.

Debugging a DNX application

Debugging ASP.NET 5 projects with the CoreCLR is not supported on Mac nor on Linux. Debugging ASP.NET 5 projects is not supported at all on Windows.

Adding NuGet Packages

To add a NuGet package to a project you can right click the Dependencies folder in the Solution window and select Add NuGet Packages, or alternatively you can double click the Dependencies folder.

Add NuGet Packages menu in Solution window

This will open up the Add NuGet Packages dialog. Installing a NuGet package using this dialog will add the NuGet package into the project.json file.

Note that using the Add Packages dialog from the Packages folder will not add the NuGet package into the project.json file and will instead download the package to the packages directory and update the packages.config file.

Adding Dependencies

Dependencies can also be added directly into the project.json file. Currently there is no code completion available in the project.json file but changes to the file are monitored and the Dependencies folder will be updated when items are added or removed. New NuGet package dependencies that are added will automatically be restored if they are missing.

Removing Dependencies

A dependency can be removed by selecting it in the Solution window, right clicking and selecting Remove, or by pressing the delete key.

Remove dependency menu in Solution window

Changing the active framework

In Visual Studio the active framework can be changed by selecting it from the drop down list at the top of the text editor. Currently using the drop down list at the top of the text editor to change the active framework is not supported in Xamarin Studio. Instead you can right click in the text editor, select Active Framework and then select the framework.

Active DNX framework context menu in text editor

The active framework affects the code completion provided in the text editor. In the screenshot below the active framework has been set to DNX Core and you can see that the DateTime type does not show ToShortDateString in its completion list.

Code completion for active DNX framework

You can also see that the code in the #if DNX451 block is grayed out since it is not used with the currently active framework.

DNX Output

Output from the DNX host and from OmniSharp can be seen in the DNX Output window. This window can be opened by selecting DNX Output from the View menu.

DNX Output window

By default only warnings and errors will be displayed in the DNX Output window. To see more or less information you can change the DNX output verbosity in preferences in the DNX – General section.

Known Issues

kqueue() FileSystemWatcher has reached the maximum number of files to watch

When opening a project with many source files, such as AutoFac, you may see the above FileSystemWatcher error message. To resolve this problem you can set the MONO_MANAGED_WATCHER to false:

export MONO_MANAGED_WATCHER=false

Xamarin Studio will need to be run from the command line for this environment variable to be used.

project.json file formatting

When adding or removing dependencies from the Solution window will cause the project.json file to be reformatted differently compared to how Visual Studio 2015 formats the file.

Source Code

The source code for the addin is available on GitHub.

There is also a separate branch that supports MonoDevelop and Xamarin Studio 6.0.