eBook 2.1 updates #4905

ardalis · 2018-04-09T15:20:51Z

READY TO MERGE

This is a PR with the 2.1 updates to the eShopOnWeb eBook.

Migrating content from microservices book Cleaning up some formatting.

Also fixing formatting and a couple of content errors.

Updating functional testing with 2.1 approach

ardalis · 2018-05-31T18:15:42Z

Ready for review @CESARDELATORRE

…is/ebookupdates

CESARDELATORRE · 2018-06-07T20:10:37Z

Maira, can you review/merge this PR when possible?
Thanks,

mairaw · 2018-06-07T20:12:10Z

Sure! I missed @ardalis last comment here. I'm working on your PR now.

mairaw · 2018-06-07T22:25:03Z

WIP is still on here. Let me close and reopen to see if it helps.

mairaw · 2018-06-07T22:28:46Z

Interesting. WIP bot is stuck. Have you ever seen this happen @terrajobst?

@ardalis I'll start the review now but please check the warnings from the last build report as well.

BillWagner · 2018-06-07T23:14:49Z

Interesting. WIP bot is stuck. Have you ever seen this happen @terrajobst?

I saw this once before when one of the earlier commit messages had "WIP" in the message. I think a squash (or other interactive rebase) to edit the commit message would fix it. Also, if that's the root cause, we should file a bug with that bot.

mairaw

Thanks @ardalis. It looks good overall but I didn't get through it all yet. But I wanted to give you some feedback already. I also sent you an e-mail - please check.

mairaw · 2018-06-07T22:29:22Z

...vices-architecture/microservice-ddd-cqrs-patterns/infrastructure-persistence-layer-design.md

 description: .NET Microservices Architecture for Containerized .NET Applications | Designing the infrastructure persistence layer
 author: CESARDELATORRE
 ms.author: wiwagn
 ms.date: 11/08/2017


update ms.date

mairaw · 2018-06-07T22:30:38Z

...vices-architecture/microservice-ddd-cqrs-patterns/infrastructure-persistence-layer-design.md

 The Specification pattern (its full name would be Query-specification pattern) is a Domain-Driven Design pattern designed as the place where you can put the definition of a query with optional sorting and paging logic.

-The Specification pattern defines a query in an object. For example, in order to encapsulate a paged query that searches for some products, you can create a PagedProduct specification that takes the necessary input parameters (pageNumber, pageSize, filter, etc.). Then, within any Repository method (usually a List() overload) it would accept an ISpecification and run the expected query based on that specification.
+The Specification pattern defines a query in an object. For example, in order to encapsulate a paged query that searches for some products, you can create a PagedProduct specification that takes the necessary input parameters (pageNumber, pageSize, filter, etc.). Then, within any Repository method (usually a List() overload) it would accept an `ISpecification` and run the expected query based on that specification.


I don't think you need specification uppercase here (e.g. https://en.wikipedia.org/wiki/Specification_pattern - ignore the URL, look at the content 😄)

mairaw · 2018-06-07T22:31:44Z

...vices-architecture/microservice-ddd-cqrs-patterns/infrastructure-persistence-layer-design.md

+// https://github.com/dotnet-architecture/eShopOnWeb
 public interface ISpecification<T>
 {
    Expression<Func<T, bool>> Criteria { get; }


line 122, you haven't updated that EF Core 2.1 as well?

mairaw · 2018-06-07T22:32:32Z

...vices-architecture/microservice-ddd-cqrs-patterns/infrastructure-persistence-layer-design.md

+  [http://deviq.com/repository-pattern/](http://deviq.com/repository-pattern/)
+
+* **Edward Hieatt and Rob Mee. Repository pattern.**
+  [_http://martinfowler.com/eaaCatalog/repository.html_](http://martinfowler.com/eaaCatalog/repository.html)


use https link

mairaw · 2018-06-07T22:35:54Z

...vices-architecture/microservice-ddd-cqrs-patterns/infrastructure-persistence-layer-design.md

+
 # Designing the infrastructure persistence layer

 Data persistence components provide access to the data hosted within the boundaries of a microservice (that is, a microservice’s database). They contain the actual implementation of components such as repositories and [Unit of Work](https://martinfowler.com/eaaCatalog/unitOfWork.html) classes, like custom EF DBContexts.


please add alt text to the images - it's something that wasn't done earlier and is important for accessibility

line 23 - last sentence is hard to read. Can you improve that?

line 47 - GitHub struggles to show formatting with incomplete code so it's hard to spot after that code block if something is using the wrong formatting or not. Can you add ... and closing braces so we can see the content better while diffing?

mairaw · 2018-06-07T23:59:06Z

docs/standard/modern-web-apps-azure-architecture/common-web-application-architectures.md

 ![](./media/image5-13.png)

-You can include multiple components/libraries or internal layers within each container, as illustrated in Figure 5-X. But, following the container principal of *"a container does one thing, and does it in one process*", the monolithic pattern might be a conflict.
+You can include multiple components/libraries or internal layers within each container, as illustrated in Figure 5-X. But, following the container principal of _"a container does one thing, and does it in one process_", the monolithic pattern might be a conflict.


you mention several times figure 5-X but there doesn't seem to be such figure

mairaw · 2018-06-08T00:00:33Z

docs/standard/modern-web-apps-azure-architecture/common-web-application-architectures.md

-> -   Interfaces
-> -   Services
-> -   DTOs
+>


any special reason to add these lists inside quotation marks?

No, someone converted my Word doc to Markdown and did that.

mairaw · 2018-06-08T00:04:37Z

docs/standard/modern-web-apps-azure-architecture/index.md

 This guide provides end-to-end guidance on building monolithic web applications using ASP.NET Core and Azure.

-This guide is complementary to the "*Architecting and Developing Containerized and Microservice-based Applications with .NET*" which focuses more on Docker, Microservices, and Deployment of Containers to host enterprise applications.
+This guide is complementary to the "_Architecting and Developing Containerized and Microservice-based Applications with .NET_" which focuses more on Docker, Microservices, and Deployment of Containers to host enterprise applications.


add link to that book here? the one on docs I mean

mairaw · 2018-06-08T00:05:20Z

docs/standard/modern-web-apps-azure-architecture/test-asp-net-core-mvc-apps.md

 You should name your tests in a consistent fashion, with names that indicate what each test does. One approach I've had great success with is to name test classes according to the class and method they are testing. This results in many small test classes, but it makes it extremely clear what each test is responsible for. With the test class name set up to identify the class and method to be tested, the test method name can be used to specify the behavior being tested. This should include the expected behavior and any inputs or assumptions that should yield this behavior. Some example test names:

-   CatalogControllerGetImage.CallsImageServiceWithId
+* CatalogControllerGetImage.CallsImageServiceWithId


codefence these

mairaw · 2018-06-08T00:06:03Z

docs/standard/modern-web-apps-azure-architecture/test-asp-net-core-mvc-apps.md

+ > \_- Anonymous-

 ## Summary



line 36... same issue here with incomplete code samples

terrajobst · 2018-06-08T18:04:16Z

Interesting. WIP bot is stuck. Have you ever seen this happen @terrajobst?

AFAIK the WIP bot also looks at commit messages. There is still one commit that includes "WIP" in it. Try to reword that commit.

terrajobst · 2018-06-08T18:07:47Z

I saw this once before when one of the earlier commit messages had "WIP" in the message. I think a squash (or other interactive rebase) to edit the commit message would fix it. Also, if that's the root cause, we should file a bug with that bot.

It's currently by-design but it's discussed here.

ardalis · 2018-06-08T20:14:24Z

Read that thread - seems odd that some ancient commit that happened to be WIP will then make the entire PR forever be considered WIP. That's not a great design. Having to rewrite history on older commits like that is someone nerve-wracking, too. I can do it if it that's what's required here, though. Please confirm that's what I should do and (if you have some) point me to known good instructions for doing so. I think this is the (only) offending commit:
d227706

BillWagner · 2018-06-08T20:17:33Z

@ardalis this is a good resource for squash and rebase.

mairaw

Few more comments after my quick fixes via GH UI

mairaw · 2018-06-28T20:49:07Z

...vices-architecture/microservice-ddd-cqrs-patterns/infrastructure-persistence-layer-design.md

 This’ll probably be my biggest feedback. I’m really not a fan of repositories, mainly because they hide the important details of the underlying persistence mechanism. It’s why I go for MediatR for commands, too. I can use the full power of the persistence layer, and push all that domain behavior into my aggregate roots. I don’t usually want to mock my repositories – I still need to have that integration test with the real thing. Going CQRS meant that we didn’t really have a need for repositories any more.

 We find repositories useful, but we acknowledge that they are not critical for your DDD, in the way that the Aggregate pattern and rich domain model are. Therefore, use the Repository pattern or not, as you see fit.



Ok, thanks! So I'll change to not use we then.

mairaw · 2018-06-28T20:53:15Z

docs/standard/modern-web-apps-azure-architecture/common-web-application-architectures.md

-> -   Services
-> -   DTOs
+### Application Core types
+


can you add some introductory sentences before each list?

mairaw · 2018-06-28T20:59:04Z

docs/standard/modern-web-apps-azure-architecture/develop-asp-net-core-mvc-apps.md

+}
 ```

 Routes can be specified on [HttpGet] and similar attributes, avoiding the need to add separate [Route\] attributes. Attribute routes can also use tokens to reduce the need to repeat controller or action names, as shown below:


line 46 - should that \ really be there?

mairaw · 2018-06-28T21:32:03Z

docs/standard/modern-web-apps-azure-architecture/develop-asp-net-core-mvc-apps.md


 In addition to serving pages and responding to requests for data via web APIs, ASP.NET Core apps can communicate directly with connected clients. This outbound communication can use a variety of transport technologies, the most common being WebSockets. ASP.NET Core SignalR is a library that makes it simple to add real-time server-to-client communication functionality to your applications. SignalR supports a variety of transport technologies, including WebSockets, and abstracts away many of the implementation details from the developer.

 ASP.NET Core SignalR is currently under development, and will be available in the next release of ASP.NET Core. However, other [open source WebSockets libraries](https://github.com/radu-matei/websocket-manager) are currently available.


this is not up-to-date given the SignalR release in 2.1.

mairaw · 2018-06-28T21:39:03Z

...rd/modern-web-apps-azure-architecture/choose-between-traditional-web-and-single-page-apps.md

 ---
 title: Choose between traditional web apps and single page apps
-description: Architect modern web applications with ASP.NET Core and Microsoft Azure
+description: Architect Modern Web Applications with ASP.NET Core and Azure | Choose Between Traditional Web App or SPA


one sentence, don't include the name of the book

mairaw · 2018-06-28T21:53:30Z

docs/standard/modern-web-apps-azure-architecture/develop-asp-net-core-mvc-apps.md

+- Advanced diagnostics

-*Learn more about Azure deployment options in Chapter 10.*
+_Learn more about Azure deployment options in Chapter 10._


mairaw · 2018-06-28T22:01:45Z

@ardalis I've left a few last comments but it's looking good. Take a look at my comments and questions from earlier today and just now.

ardalis · 2018-06-29T02:51:48Z

All good.

mairaw

There are still a few things here and there that I'd like to see addressed overall in these e-books to help with SEO (description should be modified for all articles, image file names should be friendly) and accessibility (all images should have alt text) but I'm going to approve this one. Thanks for your work on this. It looks great!

Should we publish ASAP or do you have a specific day in mind of when the update should be published?

ardalis · 2018-06-29T12:44:33Z

I'm fine to publish immediately. Maybe check with @CESARDELATORRE

Intro Update

4b5622f

mairaw closed this Apr 9, 2018

mairaw reopened this Apr 9, 2018

Merge branch 'master' into ardalis/ebookupdates

8135ad1

mairaw added the WIP label Apr 10, 2018

ardalis added 3 commits May 29, 2018 12:20

Adding more Docker/Monolith Content

b90ccc1

Migrating content from microservices book Cleaning up some formatting.

Updating Feature Comparison Table

f16eb30

Also fixing formatting and a couple of content errors.

Formatting Updates and WIP

d227706

Updating functional testing with 2.1 approach

ardalis mentioned this pull request May 31, 2018

[Book improvement] Book Feature Comparison Table Missing Containers dotnet-architecture/eShopOnWeb#84

Closed

Updated functional test examples

47a63ec

ardalis changed the title ~~eBook 2.1 Updates (WIP)~~ eBook 2.1 Updates May 31, 2018

Merge branch 'master' into ardalis/ebookupdates

c4da3d2

Merge remote-tracking branch 'origin/ardalis/ebookupdates' into ardal…

1cfc06b

…is/ebookupdates

mairaw removed the WIP label Jun 7, 2018

mairaw closed this Jun 7, 2018

mairaw reopened this Jun 7, 2018

mairaw changed the title ~~eBook 2.1 Updates~~ eBook 2.1 updates Jun 7, 2018

mairaw changed the title ~~eBook 2.1 updates~~ WIP eBook 2.1 updates Jun 7, 2018

mairaw changed the title ~~WIP eBook 2.1 updates~~ eBook 2.1 updates Jun 7, 2018

mairaw requested changes Jun 8, 2018

View reviewed changes

mairaw added 17 commits June 28, 2018 14:35

Update index.md

7fbcc62

Update index.md

25aaf2b

fix button

5585cd7

fix button

eb11aaf

one more try

b810bb6

fix button formatting

e509d5d

remove we

e5bb033

fix formatting

2551b53

fix formatting

7805750

fix formatting

5ff840f

fix formatting

d47d1f7

fix formatting

c4a16dc

fix formatting

a75b1e6

fix formatting

12639f3

fix formatting

a3f5392

fix code formatting

d3d138a

Merge branch 'master' into ardalis/ebookupdates

62a6373

mairaw reviewed Jun 28, 2018

View reviewed changes

ardalis added 2 commits June 28, 2018 22:49

Updated SignalR to note release with 2.1

0f16d00

Responding to PR feedback

bc068fa

fixed description

c64d797

mairaw approved these changes Jun 29, 2018

View reviewed changes

mairaw added 4 commits June 28, 2018 21:29

fix link list

80ee239

fix link list

a96e216

fix link list

2212c67

fix link list

2bb8c62

mairaw merged commit fcb96dd into dotnet:master Jul 2, 2018


		# Designing the infrastructure persistence layer

		Data persistence components provide access to the data hosted within the boundaries of a microservice (that is, a microservice’s database). They contain the actual implementation of components such as repositories and [Unit of Work](https://martinfowler.com/eaaCatalog/unitOfWork.html) classes, like custom EF DBContexts.

		This’ll probably be my biggest feedback. I’m really not a fan of repositories, mainly because they hide the important details of the underlying persistence mechanism. It’s why I go for MediatR for commands, too. I can use the full power of the persistence layer, and push all that domain behavior into my aggregate roots. I don’t usually want to mock my repositories – I still need to have that integration test with the real thing. Going CQRS meant that we didn’t really have a need for repositories any more.

		We find repositories useful, but we acknowledge that they are not critical for your DDD, in the way that the Aggregate pattern and rich domain model are. Therefore, use the Repository pattern or not, as you see fit.


		In addition to serving pages and responding to requests for data via web APIs, ASP.NET Core apps can communicate directly with connected clients. This outbound communication can use a variety of transport technologies, the most common being WebSockets. ASP.NET Core SignalR is a library that makes it simple to add real-time server-to-client communication functionality to your applications. SignalR supports a variety of transport technologies, including WebSockets, and abstracts away many of the implementation details from the developer.

		ASP.NET Core SignalR is currently under development, and will be available in the next release of ASP.NET Core. However, other [open source WebSockets libraries](https://github.com/radu-matei/websocket-manager) are currently available.

eBook 2.1 updates #4905

eBook 2.1 updates #4905

Uh oh!

Conversation

ardalis commented Apr 9, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

READY TO MERGE

Uh oh!

ardalis commented May 31, 2018

Uh oh!

CESARDELATORRE commented Jun 7, 2018

Uh oh!

mairaw commented Jun 7, 2018

Uh oh!

mairaw commented Jun 7, 2018

Uh oh!

mairaw commented Jun 7, 2018

Uh oh!

BillWagner commented Jun 7, 2018

Uh oh!

mairaw left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

terrajobst commented Jun 8, 2018

Uh oh!

terrajobst commented Jun 8, 2018

Uh oh!

ardalis commented Jun 8, 2018

Uh oh!

BillWagner commented Jun 8, 2018

Uh oh!

mairaw left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mairaw commented Jun 28, 2018

Uh oh!

ardalis commented Jun 29, 2018

Uh oh!

mairaw left a comment

Choose a reason for hiding this comment

ardalis commented Apr 9, 2018 •

edited

Loading