Skip to content
Browse files

Whole page proof and revision.

  • Loading branch information...
1 parent cec9144 commit 0cc35d99b97849985f923d8cab9ccc801a584f81 @graydo64 graydo64 committed with
Showing with 91 additions and 88 deletions.
  1. +91 −88 Docs/Getting started with Ncqrs.xml
View
179 Docs/Getting started with Ncqrs.xml
@@ -20,20 +20,21 @@
<para>Ncqrs is a framework for .NET that assists in building scalable, extensible and
maintainable applications by helping developers apply the Command Query
Responsibility Segregation (CQRS) architectural pattern. It does so by providing an
- infrastructure and implementations for the most important building blocks for
- command handling and execution, domain modeling, event sourcing, domain events,
- denormalization and event storage. These building blocks help you to focus on the
- code that adds business value. They come with annotation, convention and
- configuration support and help you to write isolated and testable code.</para>
+ infrastructure and implementations for the most important building blocks of command
+ handling and execution, domain modeling, event sourcing, domain events,
+ denormalization and event storage. These building blocks help you to focus on code
+ that adds business value. They come with annotation, convention and configuration
+ support and help you to write isolated and testable code.</para>
</section>
<section>
<title>When to use Ncqrs</title>
<para>Scotty said in Star Trek V: <emphasis>“How many times do I have to tell you, the
- right tool for the right job!“</emphasis>. Ncqrs isn’t the right tool for every
- job. This means that not every application will benefit from Ncqrs. Simple <link
- xlink:href="http://en.wikipedia.org/wiki/Create,_read,_update_and_delete"
- >CRUD</link> based systems without much behavior will not benefit from it. But
- there are a wide variety of applications that could benefit from Ncqrs.</para>
+ right tool for the right job!“</emphasis>. Ncqrs isn't the right tool for every
+ job. This means that not every application will benefit from using Ncqrs. Simple
+ <link xlink:href="http://en.wikipedia.org/wiki/Create,_read,_update_and_delete"
+ >CRUD</link> based systems without much behavior are unlikely to benefit from
+ using this pattern. But there are a wide variety of applications that could benefit
+ from Ncqrs.</para>
<para>Applications will most likely benefit from Ncqrs when they have one or more of the
following characteristics:</para>
<orderedlist>
@@ -85,7 +86,7 @@
<section>
<title>Introduction</title>
<para>Ncqrs is an open source project driven by software developers who love to make the
- world just a little bit better. The project is driven by people's contribution:
+ world just that little bit better. The project is driven by people's contribution:
whether they give feedback, make a bug report, fix some code or add some
documentation. The project would not be a success without the people that
contribute. They keep the project vibrant, alive and progressive.</para>
@@ -108,11 +109,11 @@
<section>
<title>Feedback</title>
<para>One of the key drivers for us is feedback. We take all feedback seriously and it
- help us in decision making and in choosing the parts of the project that we devote
- time to. Feedback can also be a good way to just put a smile on our faces. Whether
- you just want to say that we rock, that you would like to see feature X or Y, or
- that you are confused about something related to the project you can drop your
- feedback to us in one of the follow ways:</para>
+ helps us in decision making and in choosing the parts of the project that we devote
+ time to. Feedback can also be a good way to put a smile on our faces! Whether you
+ just want to say that we rock, that you would like to see feature X or Y, or that
+ you are confused about something related to the project you can get your feedback to
+ us in one of the follow ways:</para>
<itemizedlist>
<listitem>
<para><link xlink:href="http://twitter.com/ncqrs">@ncqrs at
@@ -131,13 +132,13 @@
<title>Documentation</title>
<para>A solid framework is one thing, but a framework is almost worthless without
documentation. Applications that are built using the Ncqrs framework will have
- documentation as part of their fundament. The choice of a component can have a big
- impact on the future of an application. Documentation is important to guide people
+ documentation as part of their fundament. The choice of a component can have a big
+ impact on the future of an application. Documentation is important to guide people
and to prevent them from making mistakes. This documentation can come in many ways,
- for example, the current form that you are reading. But also quick starts, blog
- posts, how to video’s, they all have a big impact. Did you blog about your
- experience with Ncqrs? Did you find a weak spot in our documentation or do you have
- any other contribution? Please let us know!</para>
+ for example, the current form that you are reading. But also quick-starts, blog
+ posts, how-to videos: they all have a big impact. Have you blogged about your
+ experience with Ncqrs? Have you found a weak spot in our documentation or do you
+ have any other contribution? Please let us know!</para>
<para>This documentation is stored in the main repository of the framework, so you can
fork it, make a change and do a pull request.</para>
</section>
@@ -150,8 +151,8 @@
insights are obtained and so requirements change. This makes it important to develop
applications that can deal with change. A well known way to solve this problem is to
split a system into layers. This architecture is known as N-tier. In this
- architecture the system is horizontal split into logical layers that depend on each
- other like a stack of plates. A layer only depends on the layer below. Layers
+ architecture the system is horizontally split into logical layers that depend on
+ each other like a stack of plates. A layer only depends on the layer below. Layers
never depend on a layer above, or further down then the direct layer below. This is
a great way to reach a certain level of abstraction. It also gives the ability to
replace a particular implementation without breaking a lot. You only break the
@@ -187,15 +188,15 @@
<para linkend="system-flow">The figure <xref linkend="architecture-overview"/> shows the
architectural overview of a CQRS based system. The first thing you should notice is
that it is not just horizontally layered as you might recognise from general
- architectures. It is fundamentally separated by a read- and a write side. This means
+ architectures. It is fundamentally separated by a read and a write side. This means
that the user interface - or any other top component - doesn't use the same model to
read data as it does to write data. Instead of getting for example customer data,
- modifying it and save the changes, the user interface read all the data needed from
- a read database, displays it to the user and to make modification it sends command
+ modifying it and save the changes, the user interface reads all the data needed from
+ a read database, displays it to the user and to make modifications it sends commands
to the command handlers. These command handlers make changes to the domain. The
- changes in the domain cause events to occur, these events represent the changes.
- These events are stored and published to denormalizers. The denormalizers make
- modifications to the read database according to the events and event data. This way
+ changes in the domain cause events to occur: these events represent the changes. The
+ events are stored and published to denormalizers. The denormalizers make
+ modifications to the read database according to the events and event data. This way
the read databases are kept up to date. Now the user interface can read the data
again and we have a closed loop. This process is illustrated in <xref
linkend="system-flow"/>.</para>
@@ -220,16 +221,16 @@
example of the command could be <code>MoveUserToNewAddress</code>. The command
should hold the new address for the user and the user id that indicates which user
has moved.</para>
- <para>Commands also tent to express intent by there name. For example, although the
- command <code>MoveUserToNewAddress</code> and <code>CorrectAddressForUser</code>
- both contain the same data – the address and the user id – the intent is definitely
- different. All commands are send to a Command Service. This service receives the
- commands and routes them to the corresponding command executors. All command
- executors respond to a specific command and execute an action based on there
- content. Command executors should not contain any business logic. The only thing
- they do is making changes to aggregate roots from the domain and makes changes to
- them. To stay away from plumbing code, Ncqrs supports mapping for command to map a
- command directly to an domain object.</para>
+ <para>Commands also tend to express their intent through their name. For example,
+ although the command <code>MoveUserToNewAddress</code> and
+ <code>CorrectAddressForUser</code> both contain the same data – the address and
+ the user id – the intent is definitely different. All commands are sent to a Command
+ Service. This service receives the commands and routes them to the corresponding
+ command executors. All command executors respond to a specific command and execute
+ an action based on the command's content. Command executors should not contain any
+ business logic. The only thing they do is to make changes to aggregate roots from
+ the domain. To stay away from plumbing code, Ncqrs supports mapping for commands to
+ map a command directly to a domain object through convention.</para>
</section>
<section>
<title>The Domain</title>
@@ -238,71 +239,73 @@
to optimize this model for behavior. Aggregate roots contain the actual business
logic and are responsible for guarding their own invariants. State changes on
aggregate roots cause domain events to occur. This sequence of domain events
- represents all the changes that has been made. This pattern is called event
- sourcing.</para>
+ represents all the changes that have been made. This pattern is called Event
+ Sourcing.</para>
</section>
<section>
<title>Events</title>
<para>All state changes in the domain are represented by domain events. They are simple
- object that contain all data related to the change. We gave two examples of command
- names. The events that are related to the state change of these commands will be
+ objects that contain all data related to the change. We gave two examples of command
+ names. The events that are related to the state change of these commands would be
<code>UserMovedToNewAddress</code> and <code>AddressCorrectedForUser</code>.
Notice that the names are in the past tense.</para>
</section>
<section>
<title>Repository</title>
- <para>The repository is used to get and save aggregate roots. This is done by there
- events. Saving an aggregate root will result in persisting all his uncommitted
- events that occurred while making change to it. Getting an aggregate root is done by
- getting this events and replaying them to build up the aggregate root into the
- latest state. The events are stored in the event store and when an aggregate root is
- saved, all the events will also be published to the event store.</para>
+ <para>The repository is used to get and save aggregate roots. This is done through their
+ events. Saving an aggregate root will result in persisting all of the uncommitted
+ events that occurred while making the changes to it. Getting an aggregate root is
+ done by getting these events and replaying them to build up the aggregate root into
+ its latest state. The events are stored in the event store and when an aggregate
+ root is saved, all the events will also be published to the event store.</para>
</section>
<section>
<title>Event Store</title>
- <para>All events that have occurred end up in the event store. It contains all the event
- that represents the state changes in the system. These can be used to build up the
- current state by replaying them all. This store can also be used to fill up new or
- repair existing read model.</para>
+ <para>All events that have occurred end up in the event store. It contains all of the
+ events that represent the state changes in the system. These can be used to build up
+ the current state by replaying them all. This store can also be used to fill up new
+ or repair existing read models.</para>
</section>
<section>
<title>Event Bus</title>
- <para>When an aggregate root is saved via the repository all the uncommitted events that
- represent the state changes that has been made are persisted into the event store.
- Beside that, the repository also publish these events via the event bus. This bus
- publishes it to everybody that has registered itself as one being interested in the
- events. An event bus can be synchronous or asynchronous, but the read models will be
- consistent at some point of time.</para>
+ <para>When an aggregate root is saved to the repository all of the uncommitted events
+ that represent the state changes that have been made are persisted to the event
+ store. Beside that, the repository also publishes these events via the event bus.
+ This bus publishes them to everything that has registered itself as being interested
+ in events, i.e. everything that has subscribed to the events. An event bus can be
+ synchronous or asynchronous, but the read models will be consistent at some point of
+ time.</para>
</section>
<section>
<title>Denormalizers</title>
<para>There are different event handlers subscribed to the events bus. The most common
- one are denormalizers. These event handlers take events and makes changes to the
- read model based on them. For example, a denormalizer could update the users address
- in the user table based on the data in the <code>UserMovedToNewAddress</code> event.
- But it could also update the total number of users in city <emphasis role="italic"
- >X</emphasis> based on that the same event. </para>
- <para>Event handlers are not only interesting to keep the read model up to date. But
- they could also be written to make changes to an external system or send warning
- email to the business when certain event occur. It could also be that an event
- handler issues a new command. Event handlers are great components to extent the
- system with new functionality without making changes in it.</para>
+ ones are denormalizers. These event handlers take events and make changes to the
+ read model based upon them. For example, a denormalizer could update the users
+ address in the user table based on the data in the
+ <code>UserMovedToNewAddress</code> event. But it could also update the total
+ number of users in city <emphasis role="italic">X</emphasis> based on that the same
+ event. </para>
+ <para>Event handlers are not only useful in keeping the read model up to date. They
+ could also be written to make changes to an external system or send a warning email
+ to the business when certain events occur. It could also be that an event handler
+ issues a new command. Event handlers are great components to extend the system with
+ new functionality without making changes to the existing logic.</para>
</section>
<section>
<title>Read Model</title>
- <para>An important part of every application is data. Most of the screen in an user
- interface request it. But every screen just tents to have a different view on the
- data. For example, one wants all the products with there name, price and category,
- while another wants the products with there name and top 3 latest product review
- score and name of the reviewer. Read models are models that can be optimized for
- data querying. And what is a optimal query? That is a query that just queries the
+ <para>An important part of every application is data. Most of the screens in a user
+ interface show data. But many screens tend to have a different view of the same
+ data. For example, one shows all the products with their name, price and category,
+ while another shows the products with their name and top 3 latest product review
+ scores and name of the reviewer. Read models are models that can be optimized for
+ data querying. And what is an optimal query? It is a query that just queries the
data from one source. In other words: select * from x where y. No joining, just give
me the data. We can accomplish this by creating one table per view. So that every
- view can just request data by a simple query. You read model doesnt even have to be
- a relational database, it could be a document based database that contains a
- collection for every view. Ncqrs does only provide a base class for denormalizers
- that allows them be subscribed to the event bus. The denormalization itself is
- simple and straightforward.</para>
+ view can just request data by a simple query. Your read model doesn't even have to
+ be a relational database, it could be a document based database that contains a
+ collection for every view. Ncqrs provides a base class for denormalizers that allows
+ them to subscribe to the event bus. The denormalization itself is simple and
+ straightforward.</para>
</section>
</chapter>
<chapter>
@@ -326,8 +329,8 @@
</figure></para>
<section>
<title>Mapped by convention</title>
- <para>Since aggregate roots modify there own state by handling events, you can
- end up with a lot of event handlers. To prevent you from writing a lot of
+ <para>Since aggregate roots modify their own state by handling events, you can
+ end up with a lot of event handlers. To save you having to write a lot of
plumbing code to wire event handlers the Ncqrs framework offers aggregate
root based types that support event handler mapping.</para>
<para>When you use the <code>AggregateRootMappedByConvention</code> class as
@@ -338,7 +341,7 @@
{
// Will be mapped as a event handler for the FooEvent.
}</code></programlisting></para>
- <para>All methods that satisfy the following convention are mapped as event
+ <para>All methods that satisfy the following convention are mapped as an event
handler:</para>
<para>
<orderedlist>
@@ -356,7 +359,7 @@
<para>The method accepts only one parameter.</para>
</listitem>
<listitem>
- <para>That parameter is type of, or inherit from, the
+ <para>That parameter is a type of, or inherits from, the
<code>SourcedEvent</code> class.</para>
</listitem>
<listitem>
@@ -366,12 +369,12 @@
</orderedlist>
</para>
<para>Although a method may be public, protected, internal, protected internal
- or private and can be virtual we do not advice you to make event handlers
+ or private and can be virtual we do not advise you to make event handlers
public.</para>
<section>
<title>Excluding methods</title>
- <para>Sometimes you want to prevent methods that satisfy the convention for
- being mapped. The can be excluded from the mapping by annotating them
+ <para>Sometimes you want to prevent methods that satisfy the convention from
+ being mapped. They can be excluded from the mapping by annotating them
with the <code>NoEventHandlerAttribute</code> attribute. All methods
annotated with this attribute will be ignored in the mapping process.
The following code shows a method that will be excluded:</para>

0 comments on commit 0cc35d9

Please sign in to comment.
Something went wrong with that request. Please try again.