Paket


The paket.references files

paket.references is used to specify which dependencies are to be installed into the MSBuild projects in your repository. Paket determines the set of dependencies that are to be referenced by each MSBuild project within a directory from its paket.references file.

It acts a lot like NuGet's packages.config files but there are some key differences:

Location

Paket looks for paket.references files underneath the folder where paket.dependencies is located.

Layout

The file whitelists any dependencies from the paket.lock file set that are to be referenced within the projects alongside it in a given directory:

1: 
2: 
3: 
4: 
5: 
6: 
7: 
Newtonsoft.Json
UnionArgParser
DotNetZip
RestSharp

group Test
    NUnit

For each MSBuild project alongside a paket.references, paket install and paket update will add references to the dependencies listed in paket.references and all their transitive dependencies (unless noted otherwise).

The references injected into the MSBuild project reflect the complete set of rules specified within the package for each lib and Content item; each reference is Conditional on an MSBuild expression predicated on the project's active framework etc. This allows you to change the target version of the MSBuild project (either within Visual Studio or e.g. as part of a multi-pass build) without reinstalling dependencies or incurring an impenetrable set of diffs.

Any Roslyn based analyzer present in the packages will also be installed in the project.

copy_local settings

It's possible to influence the Private property for references in project files:

1: 
Newtonsoft.Json copy_local: false

import_targets settings

If you don't want to import .targets and .props files you can disable it via the import_targets switch:

1: 
Microsoft.Bcl.Build import_targets: false

No content option

This option allows you to disable the installation of any content files for the given package:

1: 
2: 
3: 
jQuery content: none
Fody   content: once
ServiceStack.Swagger content: true

In this example, - once will install content files but not overwrite - content: true will install content and always override

Framework restrictions

Sometimes you don't want to generate dependencies for older framework versions. You can control this in the paket.dependencies file or via the framework switch:

1: 
2: 
Newtonsoft.Json framework: net35, net40
DotNetZip framework: >= net45           

Note: This feature is deprecated and can be seen as an expert feature. Using framework restrictions on single packages might make you projects uncompilable. The recommended way is to globally (on a group) specifiy the frameworks you want to compile for.

This feature basically tells paket to only consider the specified frameworks for this package on this particular project. The resolution will not be modified when restrictions are specified in the reference file. It means

In this project 'Newtonsoft.Json' is only required when compiling against 'net35' or 'net40'. I never need this package to compile for another framework like 'net45', therefore don't add references for other frameworks.

Redirects settings

You can instruct Paket to create assembly binding redirects for NuGet packages:

1: 
FSharp.Core redirects: on

Redirects are created only if they are required. However, you can instruct Paket to create it regardless:

1: 
FSharp.Core redirects: force

In contrast, you have the option to force Paket to not create a redirect:

1: 
FSharp.Core redirects: off

Redirects settings in references files takes precedence over settings in dependencies file.

Excluding libraries

This option allows you to exclude libraries from being referenced in project files:

1: 
2: 
3: 
4: 
5: 
6: 
PackageA
  exclude A1.dll
  exclude A2.dll
Dapper
NUnit
  exclude nunit.framework.dll

Library aliases

This option allows you to specify library aliases:

1: 
2: 
3: 
4: 
5: 
PackageA
  alias A1.dll Name2,Name3
  alias A2.dll MyAlias1
Dapper
NUnit

File name conventions

If Paket finds paket.references in a folder, the dependencies it specifies will be added to all MSBuild projects in that folder.

If you have multiple MSBuild projects in a folder that require a non-homogeneous set of references, you have two options:

  • Have a shared paket.references file that acts as a default for all except ones that require special treatment. For each special-case project, add a <MSBuild project>.paket.references file
  • Add a project-specific <MSBuild project>.paket.references file for each and every project that requires any references

Please note that Paket does not union the directory's shared reference list with the project-specific references. If a specific references file is present, it overrides the default (even if that file is empty, in which case it prevents anything being added to its sibling project file).

Global paket.references

1: 
2: 
3: 
4: 
5: 
6: 
7: 
8: 
/
/paket.dependencies
/paket.lock
/src/Example.csproj
/src/Example.fsproj
/src/Example.vbproj
/src/paket.references
/test/Example.csproj

In this example,

  • the dependencies specified in /src/paket.references will be added to /src/Example.csproj, /src/Example.fsproj and /src/Example.vbproj
  • /test/Example.csproj is left untouched

Global paket.references with project-specific override

1: 
2: 
3: 
4: 
5: 
6: 
7: 
8: 
/
/paket.dependencies
/paket.lock
/src/Example.csproj
/src/Example.fsproj
/src/Example.vbproj
/src/Example.vbproj.paket.references
/src/paket.references

In this example,

  • the dependencies specified in /src/paket.references will be added to /src/Example.csproj and /src/Example.fsproj
  • the dependencies specified in /src/Example.vbproj.paket.references will be added to /src/Example.vbproj
  • Paket does not merge the dependencies of /src/paket.references and /src/Example.vbproj.paket.references

Project-specific references only

1: 
2: 
3: 
4: 
5: 
6: 
7: 
/
/paket.dependencies
/paket.lock
/src/Example.csproj
/src/Example.csproj.paket.references
/src/Example.fsproj
/src/Example.fsproj.paket.references

In this example,

  • the dependencies specified in /src/Example.csproj.paket.references will be added to /src/Example.csproj
  • the dependencies specified in /src/Example.fsproj.paket.references will be added to /src/Example.fsproj
val lock : lockObject:'Lock -> action:(unit -> 'T) -> 'T (requires reference type)

Full name: Microsoft.FSharp.Core.Operators.lock
Fork me on GitHub