Getting Started with JustAssembly — Install, Compare, and TroubleshootJustAssembly is a lightweight .NET assembly comparison tool designed to help developers quickly identify differences between two builds of managed assemblies. It’s focused, fast, and integrates smoothly into developer workflows to make regression analysis and binary diffing easier. This guide walks through installation, basic and advanced comparison workflows, interpreting results, and troubleshooting common issues.
What JustAssembly is and when to use it
JustAssembly compares compiled .NET assemblies (DLLs and EXEs) at the IL and higher-level code structure instead of raw binary bytes. That makes it ideal for:
- Finding behavioral regressions between two builds.
- Validating that a refactor didn’t change semantics.
- Reviewing changes introduced by automated code generation.
- Inspecting third-party dependencies for differences between versions.
The tool highlights method-level changes, added/removed members, differences in IL, and can show decompiled C# where helpful. It’s not a full decompiler/reverse-engineering suite but complements tools like ILSpy and dotPeek for quick diffs.
Installation
Supported environments: modern Windows with .NET Framework or .NET runtime installed. There are a few ways to obtain JustAssembly:
- Download an installer or ZIP from the official distribution page (project site/GitHub releases).
- Use package managers if available (e.g., Chocolatey) — check the package repository for the latest package name.
- If integrated into your IDE or CI, follow the specific integration docs for that environment.
Typical steps for a manual install:
- Download the appropriate release (installer or ZIP).
- If using an installer, run it and follow prompts.
- If using a ZIP, extract to a folder and optionally add that folder to PATH or create a desktop/start menu shortcut.
- Ensure the target machines have the correct .NET runtime/framework required by the JustAssembly build you downloaded.
Permissions: installation requires standard install privileges. If comparing assemblies produced on other machines, ensure you have read access to those files and any symbols (PDBs) you want to load.
Launching and basic UI overview
When you open JustAssembly you’ll typically see:
- Two panes or drop targets labeled “Old” and “New” (or similar) to load assemblies for comparison.
- A tree view listing namespaces, types, and members with icons indicating added, removed, or changed items.
- A diff pane that displays IL-level diffs and, where available, decompiled C# snippets.
- Options to control matching behavior, ignore settings, and formatting.
Basic workflow:
- Load the “Old” assembly (baseline).
- Load the “New” assembly (target to compare).
- Let JustAssembly analyze and populate the tree view.
- Browse changed items; select a method or type to view side-by-side diffs.
Comparison modes and settings
JustAssembly can operate at different comparison granularities and with settings that affect results:
- Assembly matching: matches types and members based on signatures. If obfuscation or assembly rewriting occurred, matching may fail or be noisy.
- Ignore options: you can ignore whitespace differences in decompiled code, assembly version differences, or specific attributes (like autogenerated markers).
- PDB support: loading PDBs provides more accurate member names and possibly source mappings which help interpret diffs. If PDBs are available, load them alongside assemblies.
- IL vs decompiled view: IL view is exact and shows low-level changes; the decompiled view is easier to understand for high-level logic differences but may obscure compiler-generated artifacts.
Adjust these settings when you see spurious differences (for example, frequent method addresses or token changes that aren’t semantically relevant).
Reading the diff results
The result tree classifies changes into:
- Added: new types/members present only in the New assembly.
- Removed: present only in the Old assembly.
- Changed: present in both but with differences.
Inside a changed member you’ll often see:
- IL diff: bytecode instructions with context lines; changed instructions highlighted.
- Decompiled code diff: higher-level C#-like code differences; useful for understanding intent.
- Metadata changes: signature edits, generic parameter changes, custom attributes added/removed.
Tips:
- Start by scanning types with the largest diffs or many changed members.
- Focus on public APIs and behavior-critical methods first.
- For small changes, IL diffs may reveal subtle instruction reordering, added null checks, or compiler-introduced temporary variables.
Using PDBs and symbol files
Loading symbol (.pdb) files improves the quality of diffs:
- Restores original method and local variable names when available.
- Helps map compiler-generated code back to source constructs.
- If source indexing or SourceLink is present, JustAssembly may present source file paths (but doesn’t fetch source itself).
Best practice: include PDBs for both Old and New assemblies when available. Keep them next to the assemblies or point the tool to their location.
Integrating into CI and automated workflows
JustAssembly can be used in automated regression checks:
- Run comparisons as part of a build pipeline to detect unintended changes between baseline and new build artifacts.
- Configure the CI task to fail when unexpected changed/removed public APIs are detected.
- Output machine-readable results (JSON or XML) if the tool supports it; use that output for dashboards or alerts.
Example CI steps:
- Build baseline artifacts and publish to a known storage location.
- Build new artifacts.
- Run JustAssembly diff between baseline and new artifacts.
- Parse results; fail the job on high-severity changes.
If the tool lacks a headless mode, consider scripting the UI using command-line options, or use alternative command-line diff tools that emit structured output.
Advanced tips
- Filter by namespace or type patterns to focus on relevant components.
- Use decompiled view for human review and IL for precise verification.
- For comparing large assemblies, compare only changed projects’ outputs to reduce noise.
- If frequent unimportant differences appear (compiler optimizations, reordering), add ignore rules for compiler-generated patterns or use repeated baseline snapshots after stabilizing build settings.
- When comparing obfuscated assemblies, try to obtain unobfuscated baselines or use mapping files (if available from obfuscator) to assist matching.
Common problems and troubleshooting
Problem: Assemblies fail to match members or show many spurious changes.
- Cause: Different compiler versions, obfuscation, or missing PDBs.
- Fixes:
- Load matching PDBs for both assemblies.
- Ensure both assemblies were built with the same compiler and options (e.g., optimization, deterministic builds).
- If obfuscation is present, use mapping files or compare unobfuscated builds.
Problem: Tool crashes or hangs on large assemblies.
- Cause: Memory limits or large dependency graphs.
- Fixes:
- Increase available memory or use the 64-bit build of the tool if available.
- Compare smaller subsets (single assembly or filtered types).
- Update to the latest JustAssembly release for performance fixes.
Problem: Decompiled view looks unintelligible or shows compiler artifacts.
- Cause: Compiler optimizations, inlining, or missing symbol information.
- Fixes:
- Inspect IL diff instead — it’s authoritative.
- Rebuild with debug-friendly options and load PDBs.
Problem: CI integration not reproducible locally.
- Cause: Different baseline artifacts or build pipeline ordering.
- Fixes:
- Reproduce the exact artifacts locally using the same build scripts and environment.
- Store baselines in a binary repository to ensure consistency.
Example walkthrough: comparing two builds
-
Prepare:
- Baseline: MyLib-v1.2.0.dll + MyLib-v1.2.0.pdb
- New: MyLib-v1.3.0.dll + MyLib-v1.3.0.pdb
-
Load baseline into the Old pane and new into the New pane.
-
Inspect top-level tree:
- Note added namespaces/types (new features).
- Note removed types (breaking changes).
-
Select a changed public method:
- Read decompiled diff to understand high-level change.
- Switch to IL diff to confirm no other low-level behavioral changes (e.g., removed exception checks).
-
If you find an unintended change, open source, fix, rebuild, and re-run comparison.
Alternatives and complementary tools
- ILSpy / dotPeek: full decompilers for deeper reverse engineering.
- Mono.Cecil / dnSpy (or dnlib): programmatic inspection and editing of assemblies.
- Binary diff tools (for native code) if you also work with unmanaged components.
A short comparison:
| Tool | Strength |
|---|---|
| JustAssembly | Focused diffing of managed assemblies; quick regression checks |
| ILSpy / dotPeek | Full decompilation and browsing |
| Mono.Cecil / dnlib | Programmatic inspection/editing of assemblies |
Final recommendations
- Always compare with PDBs when possible.
- Use decompiled view for human review and IL for confirmation.
- Integrate automated checks into CI to catch regressions early.
- Keep build environments and compiler settings stable to reduce noise.
If you want, tell me your OS, JustAssembly version, or a short description of the assemblies you’re comparing and I’ll provide tailored setup or troubleshooting steps.
Leave a Reply