RecordCommander is a C# library that enables you to create, update, and manage records using a command-line–inspired interface. With a focus on simplicity and flexibility, RecordCommander allows you to register your data types, define unique keys and property mappings, and use both positional and named arguments to seed data or integrate with import/export systems.
- Command-Based Record Management: Create or update records using single-line commands (e.g.,
add language nl Dutch). - Flexible Configuration: Register classes by specifying unique keys, positional property order, and named property assignments.
- Data Seeding & Import/Export: Ideal for seeding data, providing sample data for documentation, or integrating with external systems.
- JSON–Like Parsing: Supports complex property values (including arrays) with JSON–like syntax.
- No External Dependencies: Uses only the default Microsoft libraries.
Simply clone the repository and include the source code in your project. Since RecordCommander relies solely on standard .NET libraries, no additional NuGet packages are required.
Or install the library via NuGet Package Manager Console:
Install-Package RecordCommander
Before running commands, register your record types with the library. For example, suppose you have the following domain classes:
public class MyData
{
public List<Language> Languages { get; set; } = new List<Language>();
public List<Country> Countries { get; set; } = new List<Country>();
}
public class Language
{
public string Key { get; set; }
public string Name { get; set; }
}
public class Country
{
public string Code { get; set; }
public string Name { get; set; }
public string[] SpokenLanguages { get; set; } = Array.Empty<string>();
}You would register them as follows:
using System;
using System.Collections.Generic;
using System.Linq.Expressions;
using RecordCommander;
// Register the Language record.
RecordCommandRegistry.Register<MyData, Language>(
name: "language",
collectionAccessor: ctx => ctx.Languages,
uniqueKeySelector: x => x.Key,
positionalPropertySelectors: new Expression<Func<Language, object>>[] { x => x.Name }
);
// Register the Country record.
RecordCommandRegistry.Register<MyData, Country>(
name: "country",
collectionAccessor: ctx => ctx.Countries,
uniqueKeySelector: x => x.Code,
positionalPropertySelectors: new Expression<Func<Country, object>>[] { x => x.Name, x => x.SpokenLanguages }
);The AliasAttribute can be used on classes and properties to provide alternative names for the command and properties. For example:
[Alias("lang")]
public class Language
{
public string Key { get; set; }
[Alias("n")]
public string Name { get; set; }
}After registration, you can execute commands that create or update records in your data context. For example:
// Create a context instance.
var context = new MyData();
// Run commands to seed or update data.
RecordCommandRegistry.Run(context, "add language nl Dutch");
RecordCommandRegistry.Run(context, "add language fr French");
RecordCommandRegistry.Run(context, "add country be Belgium");
// Update an existing record using named arguments:
RecordCommandRegistry.Run(context, "add country be --SpokenLanguages=['nl','fr']");
// Or using the aliases:
RecordCommandRegistry.Run(context, "add lang de --n=German");After executing the commands above, you might see output like:
Languages:
Key: nl, Name: Dutch
Key: fr, Name: French
Countries:
Code: be, Name: Belgium, SpokenLanguages: nl, fr
-
Registration:
You register each record type with a command name, a lambda to access the target collection from your context, and expressions that define the unique key and positional properties. -
Command Parsing:
TheRunmethod tokenizes the input command. It supports quoted strings, simple escape sequences, and recognizes tokens prefixed with--as named property assignments. Likewise theRunManymethod supports multiple commands in a single string, separated by newlines, ignoring empty lines and lines starting with#. -
Record Updating/Creation:
The library searches for an existing record using the unique key. If found, it updates the record’s properties; otherwise, it creates a new record and adds it to the collection. -
Type Conversion:
Values are converted to the target property types using built-in conversion mechanisms. Array values can be provided in a JSON–like syntax for easy parsing.
You can use named arguments to update properties of an existing record. For example:
RecordCommandRegistry.Run(context, "add country be --SpokenLanguages=['nl','fr']");You can run multiple commands in a single string, separated by newlines. For example:
RecordCommandRegistry.RunMany(context, @"
add language nl Dutch
add language fr French
add country be Belgium
add country be --SpokenLanguages=['nl','fr']
");You can add comments to your command strings by starting a line with #. For example:
RecordCommandRegistry.RunMany(context, @"
add language nl Dutch
add language fr French
# Add Belgium with Dutch and French as spoken languages
add country be --SpokenLanguages=['nl','fr']
");You can use the AliasAttribute to provide alternative names for the command and properties. For example:
[Alias("lang")]
public class Language
{
public string Key { get; set; }
[Alias("n")]
public string Name { get; set; }
}You can create custom commands by calling the RegisterCommand method. For example:
RecordCommandRegistry<MyData>.RegisterCommand("clear", (MyData ctx) => ctx.Languages.Clear());
RecordCommandRegistry.Run(context, "clear");You can create custom commands with optional arguments by calling the RegisterCommand method. For example:
RecordCommandRegistry<MyData>.RegisterCommand("clear", (MyData ctx, string argument, int optionalArg = 10) => ctx.Languages.Clear());
RecordCommandRegistry.Run(context, "clear arg1");
RecordCommandRegistry.Run(context, "clear arg1 20");You can register custom converters for the types. For example:
RecordCommandRegistry<TestContext>.RegisterCustomConverter((ctx, code) => ctx.Countries.Find(c => c.Code == code));You can generate commands from existing records. For example:
var lang = new Language { Key = "en", Name = "English Language" };
var cmd = RecordCommandRegistry<TestContext>.GenerateCommand(lang);
Assert.Equal("add language en \"English Language\"", cmd);You can call methods on your objects using the --Property:Argument=Value syntax. For example:
// Assuming Language has a method SetLabel(string culture, string label)
RecordCommandRegistry.Run(context, "add language en English --SetLabel:de=Englisch");This will find or create a language with key "en", set its Name to "English", and then call the SetLabel method with arguments "de" and "Englisch".
When generating commands from existing objects, you can control the output format using CommandGenerationOptions:
// Generate with aliases instead of full property names
var options = new CommandGenerationOptions(preferAliases: true);
var cmd = RecordCommandRegistry<MyData>.GenerateCommand(record, options);
// Generate with named arguments instead of positional properties
var options = new CommandGenerationOptions(usePositionalProperties: false);
var cmd = RecordCommandRegistry<MyData>.GenerateCommand(record, options);
// Include default values in the generated command
var options = new CommandGenerationOptions(ignoreDefaultValues: false);
var cmd = RecordCommandRegistry<MyData>.GenerateCommand(record, options);RecordCommander can generate usage examples for your registered commands:
// Get a basic usage example
string example = RecordCommandRegistry<MyData>.GetUsageExample<Country>();
// Output: "add country <Code> <Name> <SpokenLanguages>"
// Get a detailed usage example with parameter descriptions
string detailed = RecordCommandRegistry<MyData>.GetDetailedUsageExample<Country>();
// Output includes parameter types and descriptionsThis is particularly useful for documentation or CLI help text.
RecordCommander handles both regular enums and flags enums:
// Using a regular enum
RecordCommandRegistry.Run(context, "add book 978-1234567890 \"My Book\" \"Jane Doe\" --Status=Borrowed");
// Using a flags enum (combine multiple values with commas)
RecordCommandRegistry.Run(context, "add book 978-1234567890 \"My Book\" \"Jane Doe\" --Flags=Fiction,Mystery,Romance");RecordCommander respects the DefaultValueAttribute on properties:
public class SampleRecord
{
public string Id { get; set; }
[DefaultValue(-1)]
public int Age { get; set; } = -1;
[DefaultValue(true)]
public bool IsActive { get; set; } = true;
}When generating commands, properties with default values can be omitted:
var record = new SampleRecord { Id = "123", Name = "Alice" };
var cmd = RecordCommandRegistry<MyData>.GenerateCommand(record);
// Age and IsActive won't appear in the command if they have default valuesOnce you have a simple set of commands, you can use AI models to let you generate the data for you, for example giving the following propmt to GPT-4o:
add country BE "Belgium" --SpokenLanguages=['nl','fr']
add country DE "Germany" --SpokenLanguages=["de"]
add country FR "France" --SpokenLanguages=["fr"]
can you extend the list with all the EU countries in the same format as above
It will then generate the following output:
add country AT "Austria" --SpokenLanguages=["de"]
add country BE "Belgium" --SpokenLanguages=['nl','fr']
add country BG "Bulgaria" --SpokenLanguages=["bg"]
add country HR "Croatia" --SpokenLanguages=["hr"]
add country CY "Cyprus" --SpokenLanguages=["el"]
add country CZ "Czech Republic" --SpokenLanguages=["cs"]
add country DK "Denmark" --SpokenLanguages=["da"]
add country EE "Estonia" --SpokenLanguages=["et"]
add country FI "Finland" --SpokenLanguages=["fi", "sv"]
add country FR "France" --SpokenLanguages=["fr"]
add country DE "Germany" --SpokenLanguages=["de"]
add country EL "Greece" --SpokenLanguages=["el"]
add country HU "Hungary" --SpokenLanguages=["hu"]
add country IE "Ireland" --SpokenLanguages=["en", "ga"]
add country IT "Italy" --SpokenLanguages=["it"]
add country LV "Latvia" --SpokenLanguages=["lv"]
add country LT "Lithuania" --SpokenLanguages=["lt"]
add country LU "Luxembourg" --SpokenLanguages=["lb", "fr", "de"]
add country MT "Malta" --SpokenLanguages=["mt", "en"]
add country NL "Netherlands" --SpokenLanguages=["nl"]
add country PL "Poland" --SpokenLanguages=["pl"]
add country PT "Portugal" --SpokenLanguages=["pt"]
add country RO "Romania" --SpokenLanguages=["ro"]
add country SK "Slovakia" --SpokenLanguages=["sk"]
add country SI "Slovenia" --SpokenLanguages=["sl"]
add country ES "Spain" --SpokenLanguages=["es"]
add country SE "Sweden" --SpokenLanguages=["sv"]
You can use this library to seed data for your development environment.
You can use this library to reproduce bugs in your application by creating the same data that caused the bug.
You can use this library to generate sample data for your documentation. So that the user reading your documentation can copy and paste the commands to seed the data.
You can use this library to generate commands from existing records. Check the following test:
[Fact]
public void Generation_UsingSpaces()
{
var lang = new Language { Key = "en", Name = "English Language" };
var cmd = RecordCommandRegistry<TestContext>.GenerateCommand(lang);
Assert.Equal("add language en \"English Language\"", cmd);
}This could be used for exporting data from your application.
- No Validation:
The library does not perform any validation on the input data. You should validate the data before using it in your application. - Performance:
The library is not optimized for performance. It is designed to be simple and easy to use.
Contributions are welcome! If you have suggestions or improvements, please open an issue or submit a pull request.
This project is licensed under the MIT License.