Skip to content

Game.ProjectTemplateDependency

Assembly:
Namespace: Game.Modding.Toolchain.Dependencies

Type: class

Base: BaseDependency

Summary: Manages the installation, uninstallation and verification of the official C# mod project template used by the toolchain. This class ensures the Mod.props and Mod.targets MSBuild files are deployed to the user tooling path and that the ColossalOrder.ModTemplate .nupkg is installed (or removed) into the .NET template engine packages so that "dotnet new csiimod" works. It performs checks against installed .NET SDK version (requires .NET 6+), computes simple file caches (CRC) to determine up-to-dateness, invokes the dotnet CLI (via CliWrap) and logs warnings/errors through the toolchain logging infrastructure.

Fields

  • private const string kProjectName = "C# Mod project template" A friendly name used for logging and UI strings describing this dependency.

  • private const string kPropsFile = "Mod.props" The filename of the MSBuild props file included in the template packaging.

  • private const string kTargetsFile = "Mod.targets" The filename of the MSBuild targets file included in the template packaging.

  • private static readonly string kPropsFileSource = ToolchainDependencyManager.kGameToolingPath + "/Mod.props" Full path to the source Mod.props file bundled with the game/tooling (source location inside the game files).

  • private static readonly string kTargetsFileSource = ToolchainDependencyManager.kGameToolingPath + "/Mod.targets" Full path to the source Mod.targets file bundled with the game/tooling.

  • private static readonly string kPropsFileDeploy = ToolchainDependencyManager.kUserToolingPath + "/Mod.props" Destination path where Mod.props will be deployed for the user (user tooling path).

  • private static readonly string kTargetsFileDeploy = ToolchainDependencyManager.kUserToolingPath + "/Mod.targets" Destination path where Mod.targets will be deployed for the user.

  • private const string kTemplatePackageId = "ColossalOrder.ModTemplate" Package id used with the dotnet template engine commands (install/uninstall).

  • private const string kTemplateId = "csiimod" The template id exposed to dotnet new (used for identifying availability).

  • private static readonly string kTemplatePackageFile = "ColossalOrder.ModTemplate.1.0.0.nupkg" Filename of the template package included with the tooling.

  • private static readonly string kTemplatePackageSource = Path.Combine(ToolchainDependencyManager.kGameToolingPath, kTemplatePackageFile) Full path to the template package inside the game/tooling distribution.

  • private static readonly string kTemplatePackageInstallation = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.UserProfile), ".templateengine", "packages", kTemplatePackageFile) Expected location of the installed template package inside the user's .templateengine packages folder.

Properties

  • public override string name => "C# template" Human-readable short name for this dependency shown in UI.

  • public override string icon => "Media/Menu/ColossalLogo.svg" Icon resource path used in UI to represent this dependency.

  • public override LocalizedString installDescr => LocalizedString.Id("Options.WARN_TOOLCHAIN_INSTALL_PROJECT_TEMPLATE") Localized description shown when offering installation; references a localization id.

  • public override Type[] dependsOnInstallation => new Type[1] { typeof(DotNetDependency) } Declares that dotnet is required before installing this dependency.

  • public override Type[] dependsOnUninstallation => new Type[1] { typeof(DotNetDependency) } Declares that dotnet is required during uninstallation operations as well.

  • public override IEnumerable<string> envVariables Provides a list of environment variables that are relevant to the template/toolchain; used by the toolchain to expose environment to templates or tooling. The property yields many keys (CSII_PATHSET, CSII_INSTALLATIONPATH, CSII_USERDATAPATH, CSII_TOOLPATH, CSII_LOCALMODSPATH, CSII_UNITYMODPROJECTPATH, CSII_UNITYVERSION, CSII_ENTITIESVERSION, CSII_MODPOSTPROCESSORPATH, CSII_MODPUBLISHERPATH, CSII_MANAGEDPATH, CSII_PDXCACHEPATH, CSII_PDXMODSPATH, CSII_ASSEMBLYSEARCHPATH, CSII_MSCORLIBPATH).

Constructors

  • public ProjectTemplateDependency() No explicit constructor is defined in source; the class uses the default public constructor. Initialization and state transitions are handled in override methods; no special construction-time logic is required.

Methods

  • public override async Task<bool> IsInstalled(CancellationToken token)
    Checks whether the template is already installed and usable:
  • Verifies that Mod.props and Mod.targets exist in the user tooling path.
  • Queries the installed dotnet SDK version (must be major >= 6).
  • Executes dotnet new --list csiimod (or the legacy command depending on SDK version) via CliWrap to check whether the template id is listed.
  • Collects stderr lines and logs warnings if any are produced.

  • Returns true only if all checks pass; catches exceptions and logs an error before returning false.

  • public override Task<bool> IsUpToDate(CancellationToken token)
    Compares CRC caches of source vs deployed files and the template package to determine if the deployed files match the bundled sources:

  • Uses a local static CalculateCache function that reads file bytes and computes a CRC (Crc with specific parameters).
  • If any cache differs or an exception occurs, returns false (and logs the exception).

  • Returns true if all caches match.

  • public override Task<bool> NeedDownload(CancellationToken token)
    Always returns false: the template files are supplied with the game/tooling and no download step is needed.

  • public override Task Download(CancellationToken token)
    No-op: returns Task.CompletedTask since there's nothing to download.

  • public override async Task Install(CancellationToken token)
    Installs the project template:

  • Throws if the token is canceled.
  • Sets state to Installing and copies Mod.props and Mod.targets from game tooling source to user tooling deploy path (ensuring directories exist).
  • Verifies the installed dotnet SDK version (requires major >= 6), otherwise throws a ToolchainException with a helpful message.
  • Attempts to uninstall any existing ColossalOrder.ModTemplate via dotnet new --uninstall ColossalOrder.ModTemplate (logs any stderr).
  • Installs the provided nupkg into the .NET template engine using dotnet new --install "<path>" --force.
  • Inspects exit code and throws ToolchainException if the template package installation failed.

  • Wraps unexpected exceptions in ToolchainException to surface consistent errors to toolchain.

  • public override async Task Uninstall(CancellationToken token)
    Removes the deployed files and unregisters the template package:

  • Throws if the token is canceled.
  • Sets state to Removing and deletes the deployed Mod.props and Mod.targets files.
  • Verifies dotnet version (requires major >= 6).
  • Calls dotnet new --uninstall ColossalOrder.ModTemplate to remove the installed template package and checks exit code, throwing ToolchainException on failure.

  • Catches exceptions and wraps them into ToolchainException for consistent error handling.

  • public override Task<List<IToolchainDependency.DiskSpaceRequirements>> GetRequiredDiskSpace(CancellationToken token)
    Returns a list of DiskSpaceRequirements describing how much disk space the source files occupy and where they will be placed; used by the toolchain to present required disk space before installation. It reports sizes for:

  • kPropsFileDeploy (size taken from kPropsFileSource)
  • kTargetsFileDeploy (size taken from kTargetsFileSource)
  • kTemplatePackageInstallation (size taken from kTemplatePackageSource)

Usage Example

// Example: install the project template via the toolchain dependency
var dependency = new ProjectTemplateDependency();
using var cts = new CancellationTokenSource(TimeSpan.FromMinutes(5));
try
{
    if (!await dependency.IsInstalled(cts.Token))
    {
        await dependency.Install(cts.Token);
        Console.WriteLine("Project template installed.");
    }
    else
    {
        Console.WriteLine("Project template already installed.");
    }
}
catch (ToolchainException tex)
{
    // Handle install/uninstall specific failures
    Console.Error.WriteLine($"Toolchain error: {tex.Message}");
}
catch (OperationCanceledException)
{
    Console.Error.WriteLine("Operation canceled.");
}
catch (Exception ex)
{
    Console.Error.WriteLine($"Unexpected error: {ex}");
}