automate 0.2.5-preview

This is a prerelease version of automate.
There is a newer version of this package available.
See the version list below for details.
dotnet tool install --global automate --version 0.2.5-preview
This package contains a .NET tool you can call from the shell/command line.
dotnet new tool-manifest # if you are setting up this repo
dotnet tool install --local automate --version 0.2.5-preview
This package contains a .NET tool you can call from the shell/command line.
#tool dotnet:?package=automate&version=0.2.5-preview&prerelease
nuke :add-package automate --version 0.2.5-preview

Build and Test __Nuget Tool __Discord __Presence

  ┌─┐┬ ┬┌┬┐┌─┐┌┬┐┌─┐┌┬┐┌─┐
  ├─┤│ │ │ │ ││││├─┤ │ ├┤ 
  ┴ ┴└─┘ ┴ └─┘┴ ┴┴ ┴ ┴ └─┘

The Basic Idea

Question to a Developer:

What if I gave you a command-line tool that wrote a lot of your code for you? and it took about ~5 command-line commands (or so) for you to build out an API endpoint or all the scaffolding for a UI page?

  • You would use this tool once per API or once per UI page.

Question to the Tech Lead on that codebase:

What if I gave you a command-line tool that built that other command-line tool for that developer? and it took about ~15 command-line commands (or so) for you to build it?

  • You would only need to do this once per codebase that you work together on.

What about, if later, that command-line tool was adapted and updated (by you) as the codebase evolved and changed? The next time it is used by the developer, it refactors and automatically fixes the old code for the developer automatically?

What if you had a selection of these kinds of tools stored alongside that code, in that codebase?

What is Automate?

  1. Why? - Consistency, and Timesaving
  2. Who? - Tech Leads, Lead Developers, Tech Consultants
  3. How? - Give fellow codebase contributors tools that capture and apply their own coding patterns, naming and structure consistently. And evolve as the code changes.

How is automate different from other similar tools?

The Process

Automate may look like other kinds of templating or scaffolding-type developer tools, but there are some important differences (under the covers) that make a big difference in the long run:

  1. The toolkits that you build with automate are NOT defined by, nor controlled by, the big vendors of the other software tools you are using (i.e. Microsoft, IBM, JetBrains, etc). Instead, you and your team get to define them. This means they are more specific to the way you write code, and how you want to do things. (break away from silly sample patterns).
  2. The toolkits that you build with automate will adapt and evolve as the code in your codebase changes and evolves. (you have full control)
  3. Your toolkits are stored inside your codebase, and source controlled along with your codebase. (everyone on the codebase gets to use them).
  4. Your toolkits are meant to be used throughout the lifecycle of your codebase, not just used once at project start-up.
  5. Your toolkits can chain together ANY developer tooling to help you get your job done better. Not just code generation.
  6. Your toolkits can be used with ANY programming language, on any platform, doing any kind of software development.

How does it work?

It works like this:

  1. You identify a pattern in your codebase. eg. It might be a layering pattern (an interface) or a vertical slice pattern (a domain pattern) or a certain kind of component, or a way to compose certain components together that is done similarly in multiple places, etc.
  2. You pick (from your codebase) the files and folders where the code exists for this pattern right now.
  3. Those files are then automatically extracted for you into code templates.
  4. You name the pattern, and you define some attributes for it. Attributes are the things that represent what could be variable in the pattern when it gets applied in the codebase. (e.g. the names of functions, classes, types, files, folders in the pattern, etc.)
  5. You modify the code templates to add substitutions for the attributes that you defined, which will be calculated when the code templates are rendered.
  6. Optionally, you can define other commands that can be executed on the codebase before and after the code templates are applied. e.g. you want to execute a package manager to install something, or maybe run some automated tests to verify the code has not been broken, etc.
  7. Optionally, you define constraints about where the pattern can be reused in a codebase (e.g. only in certain languages or locations, etc.)
  8. You "build" your pattern, and a portable toolkit is automatically created for you containing these templates and automation.
  9. You ship this new toolkit to your dev teams to install into their codebases, or you install it into an existing codebase they are using for them.
  10. They then use the toolkit to construct a usage of the pattern (called a "draft") and configure it for their specific use case in their workflow.
  11. The toolkit renders the code templates into files and folders in the codebase with information contained within the draft, and executes the relevant automation etc.

Dealing with change

At some point later (inevitably), you will want to update the pattern. Refactor it, modify it, fix a defect in it, or just add new capabilities to it, etc.

  1. You simply edit the original pattern. You edit or add more code templates, optionally add or change the automation and update the constraints.
  2. An upgraded toolkit version is then built for you automatically containing these upgrades.
  3. You ship this upgraded toolkit to your team (or codebase) to use.
  4. They run the upgraded toolkit and upgrade the code in their codebase.
  5. The toolkit automatically detects the previous files/folders that were written before and detects the previous draft configuration that was used before. The toolkit re-applies the upgraded pieces. The codebase evolves.

Does automate apply to you?

If these assumptions about your software team are all true, then you might consider taking a look at this tool.

  • You work on a codebase with others - you are working in a software team.

  • You are the Tech Lead/Lead Dev/Tech Consultant of the team. (or have some other well-respected position of authority in the team).

  • You contribute code yourself to this codebase, and you often collaborate with others on your team about how the code is structured or written.

  • You already have some defined coding patterns or can create some coding patterns that are worth repeating in this specific codebase.

  • Your team values: consistency, clarity, and maintainability.

  • You accept that code changes over time and keeping things up to date is important.

If this sounds like your situation, then maybe we can help you define (and enforce) some codebase-specific coding patterns for your team to reuse.

Getting Started

See our Documentation for more details on each of the commands below.

Making your first toolkit

  1. Install the automate tool:

    • Platform installers are all here: https://github.com/jezzsantos/automate/releases
    • If .NET is installed, install from the command line: dotnet tool install automate --global (note: we are in preview at the moment)
  2. Navigate to the root of a codebase of yours.

  3. Harvest your first pattern from it:

    • automate create pattern "MyPattern1"

    For this example, we are going to assume that you have the following files and folders in the current directory (where you are running this tool). You can adjust the commands below to suit the files of any codebase.

    ¡
    ├ 📂Controllers
    │ └ 📜BookingController.cs
    
  4. Add attributes, code templates, and automation to make it programmable:

    • automate edit add-attribute "Name" --isrequired
    • automate edit add-codetemplate "Controllers/BookingController.cs"
    • automate edit add-codetemplate-command "CodeTemplate1" --targetpath "~/Controllers/{{Name}}Controller.cs"
    • automate edit add-command-launchpoint "*" --name "Generate"
  5. Edit the contents of the code template:

    • automate edit code-template "CodeTemplate1" --with "notepad.exe"

      Or use another editor like VS Code [on Windows]: %localappdata%\Programs\Microsoft VS Code\code.exe

    • Add the following snippet somewhere in this file:
    Here is the {{Name}}Contoller.
    
    • Save the file
  6. Publish a toolkit for this pattern to share with others on your team:

    • automate publish toolkit

    This will build a versioned self-contained toolkit file, and it will publish it to the desktop on your machine, and also provide you with the command to install it into this codebase.

  7. Share the toolkit file (MyPattern1_0.1.0.toolkit) over email/slack/etc with someone on your team.


Using your first toolkit

Now, that person (or you), can:

  1. Install the automate tool:

    • Installers are here: https://github.com/jezzsantos/automate/releases
    • If .NET is installed, install from the command line: dotnet tool install automate --global
  2. Install the toolkit, fetched from above (i.e email/slack/etc):

    • automate install toolkit "<DOWNLOADLOCATION>/MyPattern1_0.1.0.toolkit"
  3. Create a new 'Draft' from this toolkit:

    • automate run toolkit "MyPattern1" --name "Demo"
  4. Configure it

    • automate configure on "{MyPattern1}" --and-set "Name=Banana"
  5. Now run the toolkit:

    • automate execute command "Generate"

    This command will generate the code from the code template into the destination folder (--targetpath), using the value of the Name property which you configured as Banana

If you now open that generated file, you will also see the value of Banana in the contents of the file.


Upgrading your first toolkit

Now, you want to make a change to the toolkit:

  1. Add a new attribute to your toolkit:

    • automate edit add-attribute "Color" --isrequired -isoneof "Red;Green;Blue"
  2. Update the code:

    • automate edit code-template "CodeTemplate1" --with "notepad.exe"
    • Add color to this file
    Here is the {{Name}}Contoller it is {{Color}}.
    
    • Save the file
  3. Rebuild the toolkit:

    • automate publish toolkit
  4. Upgrade the toolkit:

    • automate install toolkit "<DOWNLOADLOCATION>/MyPattern1_0.2.0.toolkit"
  5. Upgrade your draft:

    • automate upgrade draft
  6. Configure the new color property:

    • automate configure on "{MyPattern1}" --and-set "Color=Green"
  7. Re-run the toolkit:

    • automate execute command "Generate"

If you now open that generated file, you will also see the value of Green in the contents of the file.

More...

Sick of silly examples, and keen to see an example on a real codebase?

  • Here is a demo toolkit (built from scratch) with a scripted walk-through on a real codebase which anyone can follow on their machine.

Read our Documentation

Join the Discussion on Discord

Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

Version Downloads Last updated
1.3.0 264 5/14/2023
1.2.0 162 5/7/2023
1.1.0 465 11/5/2022
1.0.7 453 10/29/2022
1.0.5 446 10/15/2022
1.0.4 473 10/3/2022
1.0.3 466 9/28/2022
1.0.2 437 9/25/2022
1.0.1 453 9/19/2022
0.2.7-preview 210 8/9/2022
0.2.6-preview 195 7/3/2022
0.2.5-preview 172 6/20/2022
0.2.4-preview 171 6/17/2022
0.2.3-preview 230 6/12/2022
0.2.2-preview 230 6/9/2022
0.2.1-preview 282 6/5/2022
0.2.0-preview 220 6/4/2022
0.1.13-preview 218 5/31/2022
0.1.12-preview 190 5/29/2022
0.1.11-preview 206 5/27/2022
0.1.10-preview 206 5/17/2022
0.1.9-preview 188 5/16/2022
0.1.8-preview 207 4/25/2022
0.1.7-preview 202 3/28/2022
0.1.6-preview 266 3/18/2022
0.1.5-preview 212 3/11/2022
0.1.4-preview 214 3/6/2022
0.1.1-preview 234 2/23/2022