GhFileAnalysis 1.0.0

GhFileAnalysis

GhFileAnalysis is a .NET 7 single-file console and library project for reading and writing version information in Grasshopper .gh and .ghx files. It automates and standardizes the management of version metadata in Grasshopper workflows, especially for teams and CI/CD pipelines.

Project Background & Evolution

This project originated from the need to programmatically inspect and update the "version" panel in Grasshopper files, a common practice for tracking definitions in computational design workflows. Early solutions were based on manual editing or ad-hoc scripts, but these approaches were error-prone and not easily automated.

The codebase evolved by:

• Studying community scripts (notably by David Rutten and Andrew Heumann) for safe manipulation of GH_IO chunks.
• Experimenting with the GH_IO API to ensure compatibility with both legacy and current Grasshopper file formats.
• Refactoring into a reusable service (GhVersionService) and a robust CLI, supporting both interactive and non-interactive (pipeline) use.
• Implementing true single-file deployment by embedding and dynamically loading GH_IO.dll at runtime, so only one executable is needed.

Current Capabilities

• Read the version from the first panel with NickName "version" in a .gh or .ghx file.
• Set or update the version in that panel, or create it if missing.
• Interactive console mode for manual workflows.
• CLI mode for scripting and automation, with clear exit codes for integration.
• Reusable C# API for integration into other .NET projects.
• True single-file deployment: all dependencies, including GH_IO.dll, are embedded and loaded at runtime.
• Windows support (due to GH_IO dependency).

Usage

CLI

Print the version from a .gh or .ghx

• file:GhFileAnalysis.exe path/to/file.ghx
• GhFileAnalysis.exe path/to/file.gh Print the version (alternative syntax)
• GhFileAnalysis.exe -v path/to/file.ghx
• GhFileAnalysis.exe -v path/to/file.gh Set the version in a .ghx file
• GhFileAnalysis.exe path/to/file.ghx -v 1.2.3
• GhFileAnalysis.exe path/to/file.gh -v 1.2.3

Interactive

Run without arguments to enter interactive mode. You can:

• Enter a file path to inspect.
• Use -v to print the version.
• Use -v <version> to set the version.
• Type x to exit.

As a Library

Reference GhVersionService in your own .NET project:

using GhFileAnalysis;
string? version = GhVersionService.GetVersion("path/to/file.ghx");
bool ok = GhVersionService.SetVersion("path/to/file.ghx", "1.2.3");

(Works for both .gh and .ghx files.)

Implementation Details

• Single-file deployment is achieved by embedding GH_IO.dll as a resource and extracting/loading it at runtime using a custom loader (DllResourceLoader).
• No extra files are needed at runtime; just distribute the single .exe.
• Assembly resolution is handled so that GH_IO.dll is found and loaded even when extracted to a temporary location.

Where It Still Needs Work

• Panel search is basic: only the first "version" panel is read or written; multiple panels are not handled.
• No backup/undo: Overwrites files in place; consider versioning or backup strategies for production use.
• Limited error reporting: Some edge cases (e.g., malformed files) may not provide detailed diagnostics.
• No advanced metadata: Only the "UserText" field is managed; other panel or document metadata is not exposed.
• Windows only: Due to the GH_IO dependency.

Contributing & License

This is a beta version and as such comments, suggestions, and bug reports are welcome.

• Currently, the code is not open for contributions, but this may change in the future. Licensed under the MIT License.

Credits

• Inspired by scripts and advice from the Grasshopper community
  • especially David Rutten and
  • Andrew Heumann
• Uses GH_IO.dll for Grasshopper file access