Jet dotnet new Templates

This repo hosts the source for Jet's dotnet new templates.

Equinox related

• eqxweb - Boilerplate for an ASP .NET Core 2 Web App, with an associated storage-independent Domain project using Equinox.
• eqxwebcs - Boilerplate for an ASP .NET Core 2 Web App, with an associated storage-independent Domain project using Equinox, ported to C#.
• eqxtestbed - Host that allows running back-to-back benchmarks when prototyping models using Equinox, using different stores and/or store configuration parameters.

Propulsion related

• proProjector - Boilerplate for an Azure CosmosDb ChangeFeedProcessor (typically unrolling events from Equinox.Cosmos stores using Propulsion.Cosmos)

  -k adds Optional projection to Apache Kafka using Propulsion.Kafka. -p shows parallel consumption mode (where source is not stream-oriented; i.e. is not from Equinox.Cosmos)

• proConsumer - Boilerplate for an Apache Kafka Consumer using Propulsion.Kafka. (typically consuming from an app produced with dotnet new proProjector -k)

Templates combining usage of Equinox and Propulsion

• summaryProjector - Boilerplate for an a Projector that can consume from a) Azure CosmosDb ChangeFeedProcessor b) EventStore generating versioned Summary Event feed from an Equinox.Cosmos/.EventStore store using Propulsion.Cosmos/.EventStore.

• summaryConsumer - Boilerplate for an Apache Kafka Consumer using Propulsion.Kafka to ingest versioned summaries produced by a dotnet new summaryProjector)

• trackingConsumer - Boilerplate for an Apache Kafka Consumer using Propulsion.Kafka to ingest accumulating changes in an Equinox.Cosmos store idempotently.

• proSync - Boilerplate for a console app that that syncs events between Equinox.Cosmos and Equinox.EventStore stores using the relevant Propulsion.* libraries, filtering/enriching/mapping Events as necessary.

Walkthrough

As dictated by the design of dotnet's templating mechanism, consumption is ultimately via the .NET Core SDK's dotnet new CLI facility and/or associated facilities in Visual Studio, Rider etc.

To use from the command line, the outline is:

1. Install a template locally (use dotnet new --list to view your current list)
2. Use dotnet new to expand the template in a given directory

# install the templates into `dotnet new`s list of available templates so it can be picked up by
# `dotnet new`, Rider, Visual Studio etc.
dotnet new -i Equinox.Templates

# --help shows the options including wiring for storage subsystems,
# -t includes an example Domain, Handler, Service and Controller to test from app to storage subsystem
dotnet new eqxweb -t --help

# if you want to see a C# equivalent:
dotnet new eqxwebcs -t

# see readme.md in the generated code for further instructions regarding the TodoBackend the above -t switch above triggers the inclusion of
start readme.md

# ... to add a Projector
md -p ../Projector | Set-Location
# (-k emits to Kafka and hence implies having a Consumer)
dotnet new proProjector -k
start README.md

# ... to add a Consumer (proProjector -k emits to Kafka and hence implies having a Consumer)
md -p ../Consumer | Set-Location
dotnet new proConsumer
start README.md

# ... to add a Summary Projector
md -p ../SummaryProjector | Set-Location
dotnet new summaryProjector
start README.md

# ... to add a Summary Consumer (ingesting output from `summaryProjector`)
md -p ../SummaryConsumer | Set-Location
dotnet new summaryConsumer
start README.md

# ... to add a Testbed
md -p ../My.Tools.Testbed | Set-Location
# -e -c # add EventStore and CosmosDb suppport to got with the default support for MemoryStore
dotnet new eqxtestbed -c -e
start README.md
# run for 1 min with 10000 rps against an in-memory store
dotnet run -p Testbed -- run -d 1 -f 10000 memory
# run for 30 mins with 2000 rps against a local EventStore
dotnet run -p Testbed -- run -f 2000 es
# run for two minutes against CosmosDb (see https://github.com/jet/equinox#quickstart) for provisioning instructions
dotnet run -p Testbed -- run -d 2 cosmos

# ... to add a Sync tool
md -p ../My.Tools.Sync | Set-Location
# (-m includes an example of how to upconvert from similar event-sourced representations in an existing store)
dotnet new proSync -m
start README.md

CONTRIBUTING

Please don't hesitate to create a GitHub issue for any questions so others can benefit from the discussion. For any significant planned changes or additions, please err on the side of reaching out early so we can align expectations - there's nothing more frustrating than having your hard work not yielding a mutually agreeable result ;)

Contribution guidelines - equinox-* templates

See the Equinox repo's CONTRIBUTING section for general guidelines wrt how contributions are considered specifically wrt Equinox.

The following sorts of things are top of the list for the eqx* templates at the present time:

• Fixes for typos, adding of info to the readme or comments in the emitted code etc
• Small-scale cleanup or clarifications of the emitted code
• support for additional languages in the templates
• further straightforward starter projects

While there is no rigid or defined limit to what makes sense to add, it should be borne in mind that dotnet new eqx* is often going to be a new user's first interaction with Equinox and/or [asp]dotnetcore. Hence there's a delicate (and intrinsically subjective) balance to be struck between:

1. simplicity of programming techniques used / beginner friendliness
2. brevity of the generated code
3. encouraging good design practices