.NET Core in Action

.NET Core in Action

Dustin Metzgar

Copyright

For online information and ordering of this and other Manning books, please visit www.manning.com. The publisher offers discounts on this book when ordered in quantity. For more information, please contact

      Special Sales Department

      Manning Publications Co.

      20 Baldwin Road

      PO Box 761

      Shelter Island, NY 11964

      Email:

orders@manning.com

©2018 by Manning Publications Co. All rights reserved.

No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by means electronic, mechanical, photocopying, or otherwise, without prior written permission of the publisher.

Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in the book, and Manning Publications was aware of a trademark claim, the designations have been printed in initial caps or all caps.

Recognizing the importance of preserving what has been written, it is Manning’s policy to have the books we publish printed on acid-free paper, and we exert our best efforts to that end. Recognizing also our responsibility to conserve the resources of our planet, Manning books are printed on paper that is at least 15 percent recycled and processed without the use of elemental chlorine.

Development editors: Cynthia Kane, Kristen Watterson

Review editor: Aleksandar Dragosavljević

Technical development editor: Mike Shepard

Project manager: Kevin Sullivan

Copyeditor: Andy Carroll

Proofreader: Melody Dolab

Technical proofreader: Ricardo Peres

Typesetter and cover designer: Marija Tudor

Illustrator: Chuck Larson

ISBN 9781617294273

Printed in the United States of America

1 2 3 4 5 6 7 8 9 10 – DP – 23 22 21 20 19 18

Brief Table of Contents

Copyright

Brief Table of Contents

Table of Contents

Foreword

Preface

Acknowledgments

About this book

About the author

About the cover illustration

Chapter 1. Why .NET Core?

Chapter 2. Building your first .NET Core applications

Chapter 3. How to build with .NET Core

Chapter 4. Unit testing with xUnit

Chapter 5. Working with relational databases

Chapter 6. Simplify data access with object-relational mappers

Chapter 7. Creating a microservice

Chapter 8. Debugging

Chapter 9. Performance and profiling

Chapter 10. Building world-ready applications

Chapter 11. Multiple frameworks and runtimes

Chapter 12. Preparing for release

A. Frameworks and runtimes

B. xUnit command-line options

C. What’s in the .NET Standard Library?

D. NuGet cache locations

 Options for .NET command-line dotnet tool

Index

List of Figures

List of Tables

List of Listings

Table of Contents

Copyright

Brief Table of Contents

Table of Contents

Foreword

Preface

Acknowledgments

About this book

About the author

About the cover illustration

Chapter 1. Why .NET Core?

1.1. Architecting enterprise applications before .NET Core

1.2. If you’re a .NET Framework developer

1.2.1. Your .NET apps can be cross-platform

1.2.2. ASP.NET Core outperforms ASP.NET in the .NET Framework

1.2.3. .NET Core is the focus for innovation

1.2.4. Release cycles are faster

1.3. If you are new to .NET

1.3.1. C# is an amazing language

1.3.2. .NET Core is not starting from scratch

1.3.3. Focus on performance

1.4. What is .NET Core?

1.5. Key .NET Core features

1.5.1. Expanding the reach of your libraries

1.5.2. Simple deployment on any platform

1.5.3. Clouds and containers

1.5.4. ASP.NET performance

1.5.5. Open source

1.5.6. Bring your own tools

1.6. Applying .NET Core to real-world applications

1.7. Differences from the .NET Framework

1.7.1. Framework features not ported to Core

1.7.2. Subtle changes for .NET Framework developers

1.7.3. Changes to .NET reflection

Additional resources

Summary

Chapter 2. Building your first .NET Core applications

2.1. The trouble with development environments

2.2. Installing the .NET Core SDK

2.2.1. Installing on Windows operating systems

2.2.2. Installing on Linux-based operating systems

2.2.3. Installing on macOS

2.2.4. Building .NET Core Docker containers

2.3. Creating and running the Hello World console application

2.3.1. Before you build

2.3.2. Running a .NET Core application

2.4. Creating an ASP.NET Core web application

2.4.1. ASP.NET Core uses the Kestrel web server

2.4.2. Using a Startup class to initialize the web server

2.4.3. Running the Hello World web application

2.5. Creating an ASP.NET Core website from the template

2.6. Deploying to a server

2.6.1. Publishing an application

2.6.2. Deploying to a Docker container

2.6.3. Packaging for distribution

2.7. Development tools available for .NET Core

2.7.1. OmniSharp

2.7.2. Visual Studio for Mac

2.7.3. Visual Studio 2017

Additional resources

Summary

Chapter 3. How to build with .NET Core

3.1. Key concepts in .NET Core’s build system

3.1.1. Introducing MSBuild

3.1.2. Creating .NET projects from the command line

3.1.3. Clearing up the terminology

3.2. CSV parser sample project

3.3. Introducing MSBuild

3.3.1. PropertyGroups

3.3.2. Targets

3.3.3. ItemGroups

3.4. Dependencies

3.5. Targeting multiple frameworks

Additional resources

Summary

Chapter 4. Unit testing with xUnit

4.1. Why write unit tests?

4.2. Business-day calculator example

4.3. xUnit—a .NET Core unit-testing framework

4.4. Setting up the xUnit test project

4.5. Evaluating truth with xUnit facts

4.6. Running tests from development environments

4.7. When it’s impossible to prove all cases, use a theory

4.8. Shared context between tests

4.8.1. Using the constructor for setup

4.8.2. Using Dispose for cleanup

4.8.3. Sharing context with class fixtures

4.8.4. Sharing context with collection fixtures

4.9. Getting output from xUnit tests

4.10. Traits

Additional resources

Summary

Chapter 5. Working with relational databases

5.1. Using SQLite for prototyping

5.2. Planning the application and database schema

5.2.1. Tracking inventory

5.2.2. Creating tables in SQLite

5.3. Creating a data-access library

5.3.1. Specifying relationships in data and code

5.3.2. Updating data

5.3.3. Managing inventory

5.3.4. Using transactions for consistency

5.4. Ordering new parts from suppliers

5.4.1. Creating an Order

5.4.2. Checking if parts need to be ordered

Additional resources

Summary

Chapter 6. Simplify data access with object-relational mappers

6.1. Dapper

6.1.1. Inserting rows with Dapper

6.1.2. Applying transactions to Dapper commands

6.1.3. The drawback of a micro-ORM

6.1.4. A brief introduction to dependency injection

6.1.5. Dependency injection in .NET Core

6.1.6. Configuring the application

6.1.7. When to build your own data-access layer

6.2. Entity Framework Core

6.2.1. Using EF migrations to create the database

6.2.2. Running the tests using EF

Additional resources

Summary

Chapter 7. Creating a microservice

7.1. Writing an ASP.NET web service

7.1.1. Converting Markdown to HTML

7.1.2. Creating an ASP.NET web service

7.1.3. Testing the web service with Curl

7.2. Making HTTP calls

7.3. Making the service asynchronous

7.4. Getting data from Azure Blob Storage

7.4.1. Getting values from configuration

7.4.2. Creating the GetBlob method

7.4.3. Testing the new Azure storage operation

7.5. Uploading and receiving uploaded data

7.6. Listing containers and BLOBs

7.7. Deleting a BLOB

Additional resources

Summary

Chapter 8. Debugging

8.1. Debugging applications with Visual Studio Code

8.1.1. Using the .NET Core debugger

8.2. Debugging with Visual Studio 2017

8.3. Debugging with Visual Studio for Mac

8.4. SOS

8.4.1. Easier to get started with a self-contained app

8.4.2. WinDBG/CDB

8.4.3. LLDB

Additional resources

Summary

Chapter 9. Performance and profiling

9.1. Creating a test application

9.2. xUnit.Performance makes it easy to run performance tests

9.3. Using PerfView on .NET Core applications

9.3.1. Getting a CPU profile

9.3.2. Analyzing a CPU profile

9.3.3. Looking at GC information

9.3.4. Exposing exceptions

9.3.5. Collecting performance data on Linux

Additional resources

Summary

Chapter 10. Building world-ready applications

10.1. Going international

10.1.1. Setting up the sample application

10.1.2. Making the sample application world-ready

10.2. Using a logging framework instead of writing to the console

10.2.1. Using the Microsoft .Extensions.Logging library

10.2.2. Internationalization

10.2.3. Globalization

10.2.4. Localizability review

10.3. Using the Microsoft localization extensions library

10.3.1. Testing right-to-left languages

10.3.2. Invariant culture

10.3.3. Using EventSource to emit events

10.3.4. Using EventListener to listen for events

10.4. Other considerations for globalization

10.5. Localization

Additional resources

Summary

Chapter 11. Multiple frameworks and runtimes

11.1. Why does the .NET Core SDK support multiple frameworks and runtimes?

11.2. .NET Portability Analyzer

11.2.1. Installing and configuring the Visual Studio 2017 plugin

11.2.2. Sample .NET Framework project

11.2.3. Running the Portability Analyzer in Visual Studio

11.3. Supporting multiple frameworks

11.3.1. Using EventSource to replace EventProvider

11.3.2. Adding another framework to the project

11.3.3. Creating a NuGet package and checking the contents

11.3.4. Per-framework build options

11.4. Runtime-specific code

Additional resources

Summary

Chapter 12. Preparing for release

12.1. Preparing a NuGet package

12.1.1. How to handle project references

12.1.2. NuGet feeds

12.1.3. Packaging resource assemblies

12.2. Signing assemblies

12.2.1. Generating a signing key

12.2.2. Delay-signing

12.2.3. Signing an assembly in .NET Core

Additional resources

Summary

A. Frameworks and runtimes

B. xUnit command-line options

C. What’s in the .NET Standard Library?

netstandard 1.0

netstandard 1.1

netstandard 1.2

netstandard 1.3

netstandard 1.4

netstandard 1.5

netstandard 1.6

netstandard 2.0

D. NuGet cache locations

 Options for .NET command-line dotnet tool

Index

List of Figures

List of Tables

List of Listings

front matter

Foreword

.NET Core is what we’ve always asked for as .NET developers: an open source, fast, and portable runtime for C#, VB, F#, and more. The book you’re holding is a great on-ramp to the world of .NET and .NET Core. You’ll learn the why, what, and how of building systems on this new platform. You’ll utilize a host of open source libraries to test your code, access databases, build microservices, and ultimately go live! You’ll also learn how to debug and profile real code in the real world with practical tips and a pragmatic perspective.

.NET Core brings the Common Language Runtime not just to Windows, but also to Mac, Linux, and beyond. You can run .NET Core in a Docker container on an ARM-based Raspberry Pi if it makes you happy! You can code against the .NET Standard and create libraries that can be shared among all these platforms as well as iOS, Android, and even an Apple Watch.

.NET Core is yours and mine, and I’m thrilled you’re joining us on this adventure. The .NET community has rallied alongside .NET Core like nothing we’ve seen before in the Microsoft development community. Over half the pull requests for the .NET Core framework come from outside Microsoft! You can run .NET Core apps in Azure, Amazon, Google, and more. Large-scale open source container orchestrators such as Kubernetes can build sophisticated hybrid systems that include all the languages that make you productive—all running side by side on the OS of your choice.

SCOTT HANSELMAN

PRINCIPAL PROGRAM MANAGER, .NET, MICROSOFT

Preface

Software developers keep learning throughout their careers. It’s part of the appeal of the field. The more I learn, the more I discover how much I don’t know (the known unknown). The times when I learned the most were the times when an unknown unknown became a known unknown—when a whole category of development was revealed to me that I hadn’t heard of before. Subjects such as performance profiling and localization never even occurred to me when I started out. Yet they have an important role in professional software development.

With so much information available through blogs, tweets, Stack Overflow, conferences, and online documentation, some may wonder if physical books can still be relevant, especially with a subject like .NET Core, where the book may be outdated by the time it reaches print. I believe the true value of a book, what gives it lasting impact, is the revelation of the unknown unknown to the reader. The book should cause you to ask questions you haven’t asked before and provide new context and ways to process the avalanche of information out there on a particular topic.

While this book is about .NET Core, a lot of the concepts have been part of the .NET Framework for years. By opening .NET Core to other platforms, Microsoft hopes to reach a new audience of developers. I’m fortunate enough to be in the right place at the right time to write a book that introduces not only .NET Core but also some important aspects of software engineering and how they’re accomplished in the .NET ecosystem. It’s my goal with this book to make you a better developer and pique your curiosity about aspects of software engineering you may not have thought about before.

A significant portion of my career has been spent on .NET. My introduction to .NET happened while I was working as a consultant for enterprise resource planning (ERP) systems. A salesman for the consulting company didn’t know (or care) that our web ERP portal product was written in Java. The customer liked the portal but wanted to customize it and to use .NET. We worked to rebuild the portal in .NET in a few months and collaborated with the customer’s development team on their customizations. That turned out to be my favorite consulting job. Years later, I was fortunate enough to be hired by Microsoft and work on the .NET Framework itself. I got to work with many talented developers and wrote code now used by countless applications.

When .NET Core started, I was excited about its potential and got involved early. An editor at Manning saw some of my early work and gave me the opportunity to submit a proposal and table of contents. I’d always wanted to write a book, so I jumped at the chance. It takes a special kind of naïveté to think you have time to write a book after the birth of a child and after taking a larger lead role at work. Not only that, but .NET Core was a moving target in the beginning, which resulted in my having to throw out or rewrite finished chapters and parts of the table of contents.

This book took way longer to write than I expected. But I learned a lot along the way, and I’m pleased with the result. I’m also proud that I was able to deliver most of the ambitious table of contents I originally planned. I hope you finish this book not only with the ability to write and publish libraries and applications in .NET Core, but also with a desire to learn more.

Acknowledgments

This book wouldn’t have been possible without the support of my wife, Sherry. Our son is a handful sometimes, so I really appreciate you giving me time to write. I doubt I would have finished without your encouragement.

Thanks also to the editors at Manning who kept the bar high and helped me write the book I wanted to write: Kristen Watterson, for guiding me to production; Cynthia Kane, for helping me through writing most of the manuscript; Mark Renfrow, for getting me to my first MEAP release; and Greg Wild, for giving me the chance to write this book and some useful advice along the way.

My thanks also go to Mike Shepard, my technical editor, for telling me when my writing was crap.

I’d also like to thank Samer Alameer for his help with the localization chapter. He not only helped me with the Arabic, but also taught me some important points about localization.

Finally, thank you to all who bought the early access version of this book, to Ricardo Peres, for his technical proofread, and to the team of reviewers who provided invaluable feedback along the way, including Andrew Eleneski, Angelo Simone Scotto, Bruno Figueiredo, Daniel Vásquez, Daut Morina, Eddy Vluggen, Eric Potter, Eric Sweigart, George Marinos, Hari Khalsa, Igor Kokorin, Jeff Smith, Jürgen Hötzel, Mikkel Arentoft, Oscar Vargas, Renil Abdulkader, Rudi Steinbach, Srihari Sridharan, Tiklu Ganguly, and Viorel Moisei.

About this book

.NET Core in Action was written to help you build libraries and applications in .NET Core. It takes you through many important aspects of developing high-quality software for release. Concepts are introduced in action with examples to show their practical application.

Who should read this book

Whether you’re new to .NET and C# or a seasoned .NET Framework developer, this book has plenty of useful information for you. While all this information may be available online through documentation, blogs, and so on, this book compiles and organizes everything into a format that’s clear and easy to follow. The book assumes that you have a working knowledge of imperative, object-oriented programming languages, such as C++ or Java. Although this isn’t an instruction guide on C#, key concepts are explained to aid you. The book also assumes some proficiency with terminals or command lines and text editors.

How this book is organized: a roadmap

This book has 12 chapters:

Chapter 1 introduces .NET Core and .NET Standard—what they’re for and why you should learn them.

Chapter 2 gets you started creating .NET Core applications.

Chapter 3 explores the MSBuild build system and how to edit project files.

Chapter 4 covers unit testing with xUnit. xUnit documentation online tends to be scattered, so this chapter will be useful as a reference later on.

Chapter 5 introduces working with relational databases, a common thing for developers to do. .NET Framework developers familiar with relational databases may want to move on to chapter 6.

Chapter 6 covers object-relational mappers (ORMs). It introduces two different types of ORMs: Dapper, a micro-ORM, and Entity Framework Core, a full-featured ORM.

Chapter 7 explores building a REST endpoint with ASP.NET Core, as well as how to make HTTP calls to other services.

Chapter 8 explores different options for debugging, from IDEs to command line.

Chapter 9 introduces performance testing with xUnit.Performance and profiling with PerfView.

Chapter 10 covers the internationalization process and how to make applications world-ready.

Chapter 11 looks at how to build .NET Core libraries and applications that rely on framework- or operating system–specific constructs.

Chapter 12 covers how to prepare your .NET Core library for release and distribution.

The appendixes contain specific details useful for writing .NET Core applications, such as target framework monikers and what’s in each version of the .NET Standard.

About the code

This book contains many examples of source code, both in numbered listings and inline with normal text. In both cases, source code is formatted in a fixed-width font like this to separate it from ordinary text. Sometimes code is also in bold to highlight changes from previous steps in the chapter, such as when a new feature adds to an existing line of code.

In many cases, the original source code has been reformatted; we’ve added line breaks and reworked indentation to accommodate the available page space in the book. In rare cases, even this was not enough, and listings include line-continuation markers ( ). Additionally, comments in the source code have often been removed from the listings when the code is described in the text. Code annotations accompany many of the listings, highlighting important concepts.

The source code for the book is located at https://github.com/dmetzgar/dotnetcoreinaction. This GitHub repository contains source for examples in all chapters except chapters 1, 8, and 12, which aren’t focused on particular examples.

The source code is also available from the publisher’s website at www.manning.com/books/dotnet-core-in-action.

Book forum

Purchase of .NET Core in Action includes free access to a private web forum run by Manning Publications where you can make comments about the book, ask technical questions, and receive help from the author and from other users. To access the forum, go to https://forums.manning.com/forums/dotnet-core-in-action. You can also learn more about Manning’s forums and the rules of conduct at https://forums.manning.com/forums/about.

Manning’s commitment to our readers is to provide a venue where a meaningful dialogue between individual readers and between readers and the author can take place. It is not a commitment to any specific amount of participation on the part of the author, whose contribution to the forum remains voluntary (and unpaid). We suggest you try asking the author challenging questions lest his interest stray! The forum and the archives of previous discussions will be accessible from the publisher’s website as long as the book is in print.

Online resources

At the end of each chapter, you’ll find a section called Additional Resources with references to books and online resources related to the contents of that chapter.

About the author

DUSTIN METZGAR has been developing software professionally since 2003. His industry experience includes building software in areas such as enterprise resource planning, supply chain management, insurance, and loan origination. He joined the .NET team at Microsoft around the time of the .NET 4.0 release and later worked on Azure services. Currently, Dustin and his team own a few libraries in the .NET Framework and .NET Core, an Azure service, and some parts of Visual Studio.

Dustin lives near Redmond, Washington. When not spending time with his son, he’s either bicycling or trying to weld sheet metal. You can find Dustin online through Twitter (@DustinMetzgar) or his blog at http://mode19.net.

About the cover illustration

The figure on the cover of .NET Core in Action bears the caption A Turk in a pelise. The members of the Turkish court would wear certain outer robes linked to the season; of course, it was the sultan who decided when the season had changed and so the robes should too. The illustration is taken from a collection of costumes of the Ottoman Empire published on January 1, 1802, by William Miller of Old Bond Street, London. The title page is missing from the collection, and we’ve so far been unable to track it down. The book’s table of contents identifies the figures in both English and French, and each illustration also bears the names of two artists who worked on it, both of whom would no doubt be surprised to find their art gracing the front cover of a computer programming book 200 years later.

The collection was purchased by a Manning editor at an antiquarian flea market in the Garage on West 26th Street in Manhattan. The seller was an American based in Ankara, Turkey, and the transaction took place just as he was packing up his stand for the day. The Manning editor didn’t have on his person the substantial amount of cash that was required for the purchase, and a credit card and check were both politely turned down. With the seller flying back to Ankara that evening, the situation seemed hopeless. What was the solution? It turned out to be nothing more than an old-fashioned verbal agreement sealed with a handshake. The seller proposed that the money be transferred to him by wire, and the editor walked out with the bank information on a piece of paper and the portfolio of images under his arm. Needless to say, we transferred the funds the next day, and we remain grateful and impressed by this unknown person’s trust in one of us. It recalls something that might have happened a long time ago.

The pictures from the Ottoman collection, like the other illustrations that appear on Manning’s covers, bring to life the richness and variety of dress customs of two centuries ago. They recall the sense of isolation and distance of that period—and of every other historic period except our own hyperkinetic present. Dress codes have changed since then, and the diversity by region, so rich at the time, has faded away. It’s now often hard to tell the inhabitant of one continent from that of another. Perhaps, viewed optimistically, we’ve traded a cultural and visual diversity for a more varied personal life. Or a more varied and interesting intellectual and technical life.

We at Manning celebrate the inventiveness, the initiative, and, yes, the fun of the computer business with book covers based on the rich diversity of regional life as it was two centuries ago, brought back to life by the pictures from this collection.

1. Why .NET Core?

This chapter covers:

What is .NET Core?

The advantages of .NET Core

Differences from the .NET Framework

Learning a new development framework is a big investment. You need to learn how to write, build, test, deploy, and maintain applications in the new framework. For developers, there are many frameworks to choose from, and it’s difficult to know which is the best for the job. What makes .NET Core worth the investment?

To answer this question, it helps to know where you’re starting from. If you’re completely new to .NET, welcome! If you’re already a .NET developer, I’ll provide some guidance as to whether .NET Core is right for you at this time. .NET Core is still evolving to meet customer demands, so if there’s a critical piece of the .NET Framework that you need, it may be good to wait a few releases. Whether you’re already familiar with .NET or are just learning about it, this book will get you writing professional applications with .NET Core in no time.

1.1. Architecting enterprise applications before .NET Core

Early in my career, I worked for a car insurance company. Its developers were attempting to improve the efficiency of claims adjusters. When you get into a car accident, a representative of the insurance company—a claims adjuster—will sometimes go directly to the scene of the accident and assess the damage. Adjustors would collect information, usually on paper, and then head back to the office where they could enter the data into an application on a desktop or laptop computer. The process was slow and required a lot of manual work.

The insurance company wanted to enable claims adjusters to enter the data directly into the claims system from the scene. They would then be able to get cost estimates and access the car owner’s insurance policy on the spot. For the insurance company, this meant quicker claim resolution and less cost. One of the secrets I learned about the car insurance industry is that they want to get a disbursement to the claimant quickly. The less time the claimant has to reflect on the estimate, the less likely they are to negotiate for a higher payout.

Accessing the claims system from the scene meant changing the architecture to incorporate mobile devices. Figure 1.1 shows the high-level design.

Figure 1.1. Claims application high-level diagram

In the past, implementing this kind of architecture equated to substantial costs. Creating cell phone and tablet applications required either hiring developers for both iOS and Android ports or standardizing on hardware to limit the number of platforms. An adjuster might travel to a remote location with poor or nonexistent cellular service, so the application needed to operate offline. The different languages and platforms used in each piece of the architecture made integration and maintenance difficult. Changes in business logic meant rewriting the logic in several languages. At the time, scaling was too slow to adjust for demand during the workday, so the hardware requirements were based on peak load. The expenses kept piling up.

What if you could use not just the same code but the same libraries across the applications, website, and services? What if you built one app and it worked on iOS, Android, and Windows? What if your website and services could fit into small containers and elastically scale in response to demand? If all that were possible, it would dramatically reduce the cost of building and maintaining systems like the claims architecture.

These questions are no longer hypothetical. .NET Core is a software framework that makes all of this possible. Developers aren’t confined to a particular language, operating system, or form factor. .NET Core is engineered to be small and modular, making it perfect for containers. It’s built and supported by Microsoft but is also open source, with an active community. Having participated in software projects like the claims application, I’m excited about the possibilities introduced by .NET Core.

1.2. If you’re a .NET Framework developer

For some .NET Framework components, .NET Core is a reboot, and for others, it’s a chance to work cross-platform. Because the .NET Framework was built mostly in managed (C#) code, those portions didn’t need code changes to move to .NET Core. But there are libraries that depend on Windows-specific components, and they