Use latest LabAPI version; rename SkipGit param

This commit is contained in:
2026-08-27 00:14:12 +02:00
parent 45eefc7765
commit 8ac9e21714
3 changed files with 23 additions and 21 deletions
+2 -10
View File
@@ -1,6 +1,5 @@
{ {
"$schema": "http://json.schemastore.org/template", "$schema": "http://json.schemastore.org/template",
"author": "Your name / organization",
"classifications": [ "Common", "Library", "SCP:SL", "LabAPI", "Game Plugin" ], "classifications": [ "Common", "Library", "SCP:SL", "LabAPI", "Game Plugin" ],
"identity": "SCPSL.LabApi.PluginTemplate", "identity": "SCPSL.LabApi.PluginTemplate",
"name": "SCP: Secret Laboratory LabAPI Plugin", "name": "SCP: Secret Laboratory LabAPI Plugin",
@@ -12,13 +11,6 @@
"sourceName": "LabApiPluginTemplate", "sourceName": "LabApiPluginTemplate",
"preferNameDirectory": true, "preferNameDirectory": true,
"symbols": { "symbols": {
"LabApiVersion": {
"type": "parameter",
"datatype": "string",
"defaultValue": "1.1.7",
"replaces": "1.1.7",
"description": "Version of the Northwood.LabAPI NuGet package to install in the project."
},
"PluginAuthor": { "PluginAuthor": {
"type": "parameter", "type": "parameter",
"datatype": "string", "datatype": "string",
@@ -32,7 +24,7 @@
"description": "If set, skips running 'dotnet restore' automatically after creating the project.", "description": "If set, skips running 'dotnet restore' automatically after creating the project.",
"defaultValue": "false" "defaultValue": "false"
}, },
"skipGit": { "SkipGit": {
"type": "parameter", "type": "parameter",
"datatype": "bool", "datatype": "bool",
"description": "If set, skips printing the reminder to initialize a git repository.", "description": "If set, skips printing the reminder to initialize a git repository.",
@@ -53,7 +45,7 @@
"continueOnError": true "continueOnError": true
}, },
{ {
"condition": "(!skipGit)", "condition": "(!SkipGit)",
"description": "This project is not a git repository yet.", "description": "This project is not a git repository yet.",
"manualInstructions": [ "manualInstructions": [
{ "text": "Run 'git init && git add -A && git commit -m \"Initial commit\"'" } { "text": "Run 'git init && git add -A && git commit -m \"Initial commit\"'" }
+18 -10
View File
@@ -13,18 +13,15 @@ are ordinary project files at that point, not template scaffolding.
## Repo is template *source* — read before touching any file ## Repo is template *source* — read before touching any file
`.template.config/template.json` sets this folder's name as the template's `.template.config/template.json` sets this folder's name as the template's
`sourceName` and defines two text-replacement `symbols` (plus `skipRestore` and `sourceName` and defines one text-replacement `symbol`, `PluginAuthor` (plus
`skipGit`, which only toggle post-generation actions and replace no text). The `skipRestore` and `SkipGit`, which only toggle post-generation actions and replace no
dotnet templating engine does a literal, repo-wide **string replacement** at text). The dotnet templating engine does a literal, repo-wide **string replacement**
generation time — not semantic renaming — driven by that config: at generation time — not semantic renaming — driven by that config:
- The folder/project name (`sourceName` in `template.json`, currently this repo's own - The folder/project name (`sourceName` in `template.json`, currently this repo's own
folder name) → whatever `-n`/`--name` the consumer passes to `dotnet new`. folder name) → whatever `-n`/`--name` the consumer passes to `dotnet new`.
- The placeholder value of the `PluginAuthor` symbol (the string currently sitting in - The placeholder value of the `PluginAuthor` symbol (the string currently sitting in
`EntryPoint.cs`'s `Author` property) → the consumer's `--PluginAuthor`. `EntryPoint.cs`'s `Author` property) → the consumer's `--PluginAuthor`.
- The placeholder value of the `LabApiVersion` symbol (the version string currently in
the `.csproj`'s `PackageReference` and in `EntryPoint.cs`'s `RequiredApiVersion`) →
the consumer's `--LabApiVersion`.
Open `template.json` to see the exact current literal for each — don't hardcode them Open `template.json` to see the exact current literal for each — don't hardcode them
again here or anywhere else in prose, because this file itself ships inside every again here or anywhere else in prose, because this file itself ships inside every
@@ -32,7 +29,7 @@ generated project and any exact match gets rewritten too (self-referential text
"the project is called X" would silently turn into nonsense after generation). "the project is called X" would silently turn into nonsense after generation).
Consequences: Consequences:
- Never introduce an exact match of one of those three literals elsewhere in the repo - Never introduce an exact match of one of those two literals elsewhere in the repo
unless you intend it to be substituted too. unless you intend it to be substituted too.
- If you add a new thing that should be configurable at generation time, add a symbol - If you add a new thing that should be configurable at generation time, add a symbol
to `template.json` (`type: parameter`, `replaces: "<literal>"`) instead of to `template.json` (`type: parameter`, `replaces: "<literal>"`) instead of
@@ -45,7 +42,7 @@ Consequences:
## Repo layout (only what affects decisions) ## Repo layout (only what affects decisions)
- `.template.config/template.json` — template identity, the symbols above plus - `.template.config/template.json` — template identity, the symbols above plus
`skipGit` (a display-only toggle, see below), `primaryOutputs` (points at the `SkipGit` (a display-only toggle, see below), `primaryOutputs` (points at the
project file using its pre-substitution literal name — that's correct and expected, project file using its pre-substitution literal name — that's correct and expected,
not a bug), and two `postActions`: the standard dotnet-templating "restore NuGet not a bug), and two `postActions`: the standard dotnet-templating "restore NuGet
packages" action (id `210D431B-...`; skipped in Visual Studio, which restores on packages" action (id `210D431B-...`; skipped in Visual Studio, which restores on
@@ -80,7 +77,7 @@ This was a deliberate choice after testing the alternative:
- Visual Studio's own "New Project" dialog already has a built-in "Create new Git - Visual Studio's own "New Project" dialog already has a built-in "Create new Git
repository" checkbox that works for any template, including this one, with zero repository" checkbox that works for any template, including this one, with zero
template-side configuration — so VS users get this for free regardless. template-side configuration — so VS users get this for free regardless.
- CLI users see the printed reminder above (governed by the `skipGit` symbol) and run - CLI users see the printed reminder above (governed by the `SkipGit` symbol) and run
the one-liner themselves. the one-liner themselves.
## LabAPI contract (verified against northwood-studios/LabAPI source, not guessed) ## LabAPI contract (verified against northwood-studios/LabAPI source, not guessed)
@@ -119,6 +116,17 @@ assume one exists.
`MSB3270` (via `ResolveAssemblyWarnOrErrorOnTargetArchitectureMismatch=None`). Don't `MSB3270` (via `ResolveAssemblyWarnOrErrorOnTargetArchitectureMismatch=None`). Don't
broaden either into a blanket suppression and don't remove them without broaden either into a blanket suppression and don't remove them without
understanding why (comments sit next to both in the `.csproj`). understanding why (comments sit next to both in the `.csproj`).
- The `Northwood.LabAPI` `PackageReference` uses a floating `Version="*"` on purpose,
so every `dotnet restore` always pulls whatever is the latest stable release on
NuGet at that moment — there's no version to bump here. This is intentionally
**not** wired to `EntryPoint.cs`'s `RequiredApiVersion`, which can't be a floating
value (`System.Version` has no such concept and would throw at runtime if it tried).
`RequiredApiVersion` is a separate, manually-maintained literal representing the
minimum LabAPI version the scaffolded code is known to work with — bump it by hand
if you verify compatibility with a newer release, don't try to auto-sync it with the
floating restore. Also be aware a floating version means a plugin generated today can
restore a different (newer) LabAPI release than one generated last week, with no
pinning — that's the deliberate trade-off of "always latest" over reproducibility.
## Code style for anything you write here ## Code style for anything you write here
+3 -1
View File
@@ -33,7 +33,9 @@
</PropertyGroup> </PropertyGroup>
<ItemGroup> <ItemGroup>
<PackageReference Include="Northwood.LabAPI" Version="1.1.7"> <!-- Floating version: restore always resolves to the latest stable Northwood.LabAPI
release published on NuGet at the time, instead of a version pinned here. -->
<PackageReference Include="Northwood.LabAPI" Version="*">
<NoWarn>NU1701</NoWarn> <NoWarn>NU1701</NoWarn>
</PackageReference> </PackageReference>
</ItemGroup> </ItemGroup>