Makes a package's assemblies available to the Clr object and inline C#. The script does not start if a required package cannot be made available.
#Package *i Provider:PackageId Version
Note: The bundled NuGet provider needs only the .NET runtime Keysharp already uses; no .NET SDK or NuGet executable is required. Restoring a package set which is not yet cached may require network access to a configured feed.
Type: String
The local package-system provider. If omitted, this is nuget, so #Package Newtonsoft.Json and #Package nuget:Newtonsoft.Json are equivalent. A provider name begins with a letter and contains only letters, digits, - or _.
Providers are installed under Keysharp's components/packages/<name> directory, and a missing one is not downloaded. For example, #Package aris:dev/name passes dev/name to an installed aris provider.
Type: String
The identifier understood by the selected provider. For NuGet this is the package identifier as it appears on the feed, such as Newtonsoft.Json, and may contain letters, digits, ., _ and -. Other providers validate their own identifier forms.
Type: String
The selected provider validates and interprets this text. The bundled NuGet provider accepts the same AHK-style shapes #Requires accepts. An optional letter "v" may precede a version number.
| Written | Meaning |
|---|---|
| omitted | The newest stable release. |
v13 or 13 | The newest 13.x release. |
v13.0 or 13.0 | The newest 13.0.x release. |
13.0.3 | Exactly that version. |
>=13.0, <14, >=13.0 <14 | A bounded range. <, <=, >, >= and = are accepted. |
13.* | A floating version. |
[13.0,14.0) | A NuGet interval. |
Prerelease versions are not selected unless the version says so explicitly (for example 1.0.0-beta.1).
Note: This parameter is not an expression. Neither parameter accepts variable references.
If present, the package is optional: if it or its separately installed provider cannot be made available, the script continues without it instead of stopping. The reason is reported through OutputDebug. If the provider is installed, malformed provider-specific package or version syntax is still an error.
If the package is not available, an error is raised only where a type from it is used.
Packages are resolved when the script is compiled. The exact version each request resolved to is recorded in the built script and loaded on every later run, so a floating version such as #Package Newtonsoft.Json is decided once, by the build. This is also what lets inline C# use types from a declared package.
Resolution happens in this order:
Note: --validate and CompileScript do not restore packages; a package set which has not been restored on this machine is reported as such. Running or compiling the script restores it.
The NuGet provider discovers NuGet.Config beginning at the script directory. Its enabled package sources, credentials, package-source mapping, trusted-signer policy, global-packages folder, fallback folders and ordinary NuGet feed/network behavior apply. Changing a discovered config file or enabled source invalidates the cached graph.
Package contents live in the global packages folder selected by NuGet configuration (%NUGET_PACKAGES% when set, otherwise the NuGet default), shared with other .NET tooling.
Note: A package contributes its assemblies, resource assemblies and native libraries for the current runtime. Its MSBuild tasks, analyzers, source generators and contentFiles are not used, so a package which depends on them may not work.
Every #Package directive in a script is resolved together, grouped by provider, and each must appear at the top level of a script or module. Requesting the same provider/package identity twice with different versions is a load-time error. Requesting it twice with the same version is accepted and has no additional effect.
Types are reached through Clr by namespace. Types from a package's own dependencies are reachable too, even though the script never names those packages.
Like other directives, #Package cannot be executed conditionally.
If the NuGet provider reports a known security advisory for a resolved package, the advisory is passed through to OutputDebug and the script continues.
For a .NET assembly already on disk, use Clr.Load.
Warning: A package is third-party code, and it runs inside the script's process with the script's full privileges. Packages are not reviewed by the Keysharp project. Treat an unfamiliar package name with the same caution as an unfamiliar DLL.
Note: A compiled script carries the exact package assets it was built against, so the target machine needs no provider, network access or package cache for #Package. Distribute the .keysharp/packages directory written beside a .cks or executable with it; an exe-min embeds the assets instead (see --compile). If an asset is missing at startup, the script stops with an error naming the package and version.
For a package chosen by a computed name, or one needed only on some code paths, use Clr.LoadPackage.
Clr, Clr.LoadPackage, #DllLoad, #Requires
Requires a specific version of a package, then parses JSON with it.
#Package Newtonsoft.Json 13.0.3
#Import "Ks" { Clr }
Obj := Clr.Newtonsoft.Json.Linq.JObject.Parse('{"name":"Keysharp","version":2}')
MsgBox Obj["name"].ToString()
Takes the newest 13.x release, and marks a second package optional so the script still runs without it.
#Package Newtonsoft.Json 13
#Package *i Serilog >=4.0 <5
#Import "Ks" { Clr }
MsgBox Clr.Newtonsoft.Json.JsonConvert.SerializeObject([1, 2, 3])
Uses a type from a dependency the script never names. SQLitePCL.raw comes from SQLitePCLRaw.core, pulled in as a dependency, and the database engine itself is a native file the package supplies for this platform.
#Package SQLitePCLRaw.bundle_e_sqlite3 2.1.10
#Import "Ks" { Clr }
Clr.SQLitePCL.Batteries_V2.Init()
MsgBox Clr.SQLitePCL.raw.sqlite3_libversion_number()