AGcaRO — Auto Generated control as ReadOnly

A Visual Studio extension that opens generated source files as read-only, so nobody wastes an afternoon editing a file the next code generation will overwrite.

The problem

You open Model.g.cs, fix the bug, run the build — and the generator silently puts the old code back. The fix is gone, and you find out an hour later.

Generated files look exactly like hand-written ones in the editor. The <auto-generated> header is easy to scroll past, and nothing stops you from typing.

What AGcaRO does

//------------------------------------------------------------------------------
// <auto-generated>          ← the file opens locked, with the reason in the info bar
//------------------------------------------------------------------------------

Installing

From the Visual Studio Marketplace

Search for AGcaRO under Extensions ▸ Manage Extensions ▸ Online.

From source

git clone https://github.com/Tootega/AGcaRO
cd AGcaRO
.\New-Vsix.ps1 -Configuration Release

The package lands in artifacts\AGcaRO-<version>-Release.vsix next to its SHA-256 hash. Close Visual Studio and double-click it.

Build prerequisite: Visual Studio with the Visual Studio extension development workload (the Microsoft.VisualStudio.Component.VSSDK component).

Working on the extension

Open AGcaRO.slnx and press F5: Visual Studio builds it, installs it into the experimental hive and opens a second instance with it loaded — leaving your working installation untouched.

How detection works

Rules are evaluated in this order, and the first one that decides ends the evaluation:

Steps 3 to 5 come before the read precisely so the common case never touches the disk. Once the document is open, step 6 uses the text the editor already holds — zero I/O.

Only the header counts. By default the first 40 lines or 8 KB, whichever comes first. That is what keeps detection cheap, and what stops a file that merely mentions the tag halfway down from being locked.

What is recognised out of the box

Using it

When a file opens locked

An info bar appears at the top of the document with the exact reason and offers Unlock for this session, Always allow this file, Settings and Stop showing this.

Try to type and the status bar explains the block and reminds you of the shortcut.

Commands

Under Extensions ▸ AGcaRO, on the editor context menu and on the Solution Explorer context menu:

Opting a file out from inside the file

Put AGcaRO:allow-edit in the header. Useful for a file that started life in a generator and is now maintained by hand. Strict mode turns this off.

Configuration

Per user

Tools ▸ Options ▸ AGcaRO, across two pages: General (behaviour, feedback, diagnostics) and Detection (the marker and pattern lists).

Per repository — .agcaro.json

A file at the solution or repository root, version-controlled alongside the code, overriding everyone's individual preferences. It is re-read on its own whenever it changes.

{
  "$schema": "https://github.com/Tootega/AGcaRO/docs/agcaro.schema.json",

  // On this team, generated files are not edited.
  "allowUnlock": false,
  "strictMode": true,

  "nameGlobs": {
    "add": ["*.mygenerator.cs", "*Orm.g.cs"],   // on top of the factory patterns
    "remove": ["*.min.js"]                      // ...and drop one of them
  },

  "excludeGlobs": {
    "add": ["src/Legacy/**"]                    // relative to this file's folder
  }
}

Every list accepts either an array (which replaces the factory list) or the object form { replace, remove, add } (which adjusts it). Comments and trailing commas are accepted. Malformed JSON only produces a warning in the Output window and the global configuration keeps applying — the extension never stops working because of a broken config file.

The full schema lives in docs/agcaro.schema.json, and a commented example in docs/examples/.agcaro.json.

Precedence

user allow list  ▸  .agcaro.json  ▸  global options  ▸  factory defaults

Settings reference

Design decisions worth explaining

Protection lives in the editor, not on disk. The file system read-only attribute is available as an option (applyFileSystemAttribute) but ships off: marking the file on disk makes some generators fail when they try to rewrite it. Protecting the developer must not cost you the generator.

The default mechanism is Visual Studio's own. BSF_USER_READONLY blocks typing, pasting, formatting, snippets and refactorings — and, decisively, the shell knows how to suspend it while reloading the document after the generator rewrites the file. ShellAndReadOnlyRegion adds a direct buffer lock for anyone who wants maximum enforcement, at the cost of sometimes needing to close and reopen the file after regeneration.

Failing means allowing, never locking. An I/O error, an unreachable network share, a denied permission, an unreadable configuration: in every one of those cases the file is treated as editable. A protection extension that locks the developer out because of its own error is worse than no extension at all.

The header window is bounded on purpose. Scanning whole files would find markers anywhere, but it would also lock any file that merely quotes the tag in a comment — and it would make opening a large generated file noticeably slower.

FAQ

Development

src/AGcaRO/
  Core/            detection engine - plain .NET, no Visual Studio dependency at all
  Editor/          editor integration: locking, info bar, command filter
  Services/        logging, configuration and the coordinator
  Options/         the Tools > Options pages
  Commands/        menu commands
tests/             111 tests over Core, runnable with `dotnet test`
samples/           sample files + manual verification walkthrough
build/             helper scripts: build, publishing and asset generation
publish/           Marketplace manifest and store page
docs/              requirements, publishing guide and the .agcaro.json schema
.github/workflows/ CI and release
New-Vsix.ps1       produces the .vsix packages - at the root, being the release entry point

Core/ deliberately does not reference the VSSDK: the test project compiles those sources straight against net8.0, which is what lets the whole suite run without Visual Studio.

Scripts

.\New-Vsix.ps1                            # bump the build and produce Release into artifacts\
.\New-Vsix.ps1 -Configuration Both        # Debug and Release sharing one version
.\New-Vsix.ps1 -NoVersionBump             # rebuild without bumping
.\New-Vsix.ps1 -Version 1.1.0             # pinned version, repository untouched

.\build\Build.ps1                         # build and test, without packaging
.\build\Publish-Vsix.ps1 -Validate        # check everything without contacting the store

Versioning

MAJOR.MINOR.BUILD, starting at 1.0.123. New-Vsix.ps1 bumps BUILD on every packaging run and writes it to source.extension.vsixmanifest — commit that change along with the rest.

The manifest is the single source of the version: the .csproj reads it from there (target SetVersionFromManifest), so AssemblyVersion, FileVersion and the VSIX version can never diverge. Never set the version anywhere else.

Working on the PowerShell scripts

The scripts run on both Windows PowerShell 5.1 and PowerShell 7 — except Test-MefExports.ps1, which needs 7 (it uses System.Reflection.Metadata, absent from .NET Framework) and refuses to run on 5.1 with a clear message.

build\Test-Scripts.ps1 checks for the two traps below, and CI runs it:

UTF-8 with a BOM is not optional. Without it, Windows PowerShell 5.1 reads the file as ANSI and any accented character breaks the parser before the first line executes. The .editorconfig pins charset = utf-8-bom, but automated tooling strips BOMs easily — Test-Scripts.ps1 -Fix puts them back.

Never use curly quotes (“ ”) inside literals. PowerShell accepts them as string delimiters equivalent to ", so one in the middle of a message ends the string there and the error surfaces several lines later with a misleading message. Quote with straight single quotes.

Troubleshooting the build

Publishing

The full walkthrough — creating the publisher, generating the PAT, validating and publishing — is in docs/PUBLISHING.md, with a release checklist and the common pitfalls.

Before the first publish, replace the placeholder values (publisher, repository URLs) listed in the table at the top of that document.

Documents

• docs/REQUIREMENTS.md — the expanded requirements, with traceable IDs (FR-* / NFR-*) referenced from the code comments.
• docs/PUBLISHING.md — publishing to the Marketplace.
• samples/README.md — manual verification walkthrough inside VS.
• CHANGELOG.md — change history.

Compatibility

Contributing

Issues and pull requests are welcome. Before opening a PR:

.\build\Test-Scripts.ps1     # if you touched any .ps1
.\build\Build.ps1            # build + 111 tests

New detection rules should come with a test in tests/AGcaRO.Core.Tests and, when they are worth demonstrating, a file under samples/ plus a row in its walkthrough table.

Licence

MIT — see LICENSE.txt.