dotnet/training-tutorials

Getting started tutorials for C# and ASP.NET

.NET Training and Tutorials

This repository holds the content used to build the .NET getting started tutorials hosted at http://dot.net

Organization

The content is broken up into high level groups by topic, initially covering

• C#
• ASP.NET
• F#

Within each content area, there are one or more tutorials.

Each tutorial consists of lessons. Each lesson should be a page detailing the concept being taught, along with sample code. Lesson and page may be used interchangeably when describing the tutorials. Lessons may be broken up into several steps. Each step and lesson should end with working code the user can run using a REPL, Visual Studio, or Visual Studio Code.

You can view the C# content as a model for other content areas. Note that URLs/links should use 'csharp' in place of C# because GitHub will convert the latter to C%23 resulting in broken links. Also note, links to README.md files are case-sensitive within GitHub's web view.

Lessons will include tips that will be tagged according to reader background, and eventually these will be displayed to readers who have indicated they have that background. For example:

Tip {.tip .vb} The static keyword in C# is equivalent to Shared in Visual Basic .NET

Lessons will also include notes, which will receive special formatting when displayed to readers. For example:

Note {.note}

It is common to log exceptions that occur, so that you can review them later and improve the program to avoid them, if possible.

Lessons will be written using markdown (Github variant). Lessons should link to other documents for specific tasks and API references. These should focus on helping the user follow through and understand the tutorial.

Includes / Shared Elements

The ultimately publishing platform capabilities and requirements aren't yet known. Until they are, we don't have a system in place for includes or for sharing common elements across tutorials/pages. For now, we'll need to copy/paste.

Branching Strategy

The master branch will contain the latest approved content. In the short term, approved content authors will be permitted to push directly to master. Once there is a significant amount of content, however, authors will be expected to work in their own feature branch before submitting a pull request and awaiting a from another team member.

Contributing

We welcome contributions and corrections to these tutorials. We will build out a roadmap shortly on the areas that we are looking to address next but send us your ideas. When contributing the steps are:

1. Fork this repo and clone your fork locally
2. Create a new branch for your contribution
3. Do your awesomeness, commit and push to your fork
4. Create a pull request from it to the master branch of https://github.com/dotnet/training-tutorials
5. Leave some handy comments

We ask that authors of significant changes sign the .NET Foundation Contribution License Agreement. This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. For more information see the .NET Foundation Code of Conduct.

.NET Foundation

This project is supported by the .NET Foundation.

training-tutorials's Issues

Using Basic Middleware to Output Responses

ASPNET > Getting Started

Show how to use basic middleware. Start with Hello World response to everything, then show how to generate different responses based on the request. Don't get into routing or custom middleware here - keep it simple.

At this point we should be driving toward a sample that we will continue to build on until we introduce MVC (when we will start a new, separate sample). Come up with something that will either continue to be useful or that can be easily modified in the next few lessons into something useful.

Configuring and Requesting App Services

ASPNET > Getting Started

Briefly describe the purpose of dependency injection and the services container ASPNET provides.

• Create a custom service - perhaps one that reads a value from configuration and returns it.
• Register the service in ConfigureServices
• Request and use the service in Configure in some middleware to display the value
• The service itself might request services, like Logging or Options to access configuration

Describe Extension Methods

We mention extension methods in the lesson about collections and in the lesson about linq, however, we never tell our readers anything about extension methods.

Introducing Routing

ASPNET > Getting Started

• Add Routing dependency and middleware
• Configure routing with existing middleware.
• Show how to access route variables from middleware.

This is the last article that is working on the sample started at the beginning of the tutorial. At the end of this article, there should be a demo application in a working state that does something useful.

Adding Diagnostics to the App

ASPNET > Getting Started

Add a developer exception page
Add Status Code pages (https://docs.asp.net/en/latest/fundamentals/error-handling.html#configuring-status-code-pages)

Create code sample / repo for C#-GettingStarted-Lesson 01

Need to create a ZIP file (and possibly a repo) with the Hello World program from lesson 1.

Describe Property Initializers

In https://github.com/dotnet/training-tutorials/blob/master/content/csharp/getting-started/lesson-13.md when properties are described.

Create Outline for ASP.NET Core Getting Started Tutorial

Update Lesson 2 for REPL/Tips

Update C# Getting Started:

• Examples use REPL format
• Add tips for newLanguage

Syntax:

Tip {.tip .newLanguage }

This the tip.
This is some more of the tip

Understanding Namespaces, Projects, and Assemblies

• Namespaces
• using statements
• Projects
• Assemblies
• Nuget packages (maybe?)

Getting Started - Testing Your Code

C# > Getting Started

Add to TOC in intro.md, at the end.
Cover using xunit to write simple unit tests.

Looping a Known Number of Times

This lesson should focus on the C# for loop. Note that the "known number of times" isn't necessarily always true, but typically the at least at runtime the condition where the loop will end should be known before the loop begins. Focus primarily on the typical loop from 1 to N incrementing by 1 scenario, but show more advanced scenarios at the end.

• Basic syntax
• Starting from different values
• Counting up by different increments
• Counting down
• Nested Loops

Understanding Controllers and Actions

ASPNET > Getting Started

• What is a controller?
• What is an action?
• How are actions chosen (routing)?
• Attribute routes
• Controller helpers
  • View
  • RedirectToAction
  • RedirectResult
  • Ok
  • NotFoundResult
  • BadRequest

Explain Lambda Expressions

We should explain these somewhere as they're very relevant to explaining LINQ. Should this be the lesson on Defining and Calling Methods or directly in Introducing LINQ?

Sending Data to Controllers

ASPNET > Getting Started

Getting data to Controllers would be things like DI and configuration. Reference this and mention that DI is coming in next article.

More specifically, this lesson is about getting data to actions within a controller, and as such should focus primarily on Model Binding. Discuss how the action can get access (either through its model bound parameters, or otherwise) to request data from any of these:

• Querystring
• POST data
• URL/routing tokens (e.g. /{id?} )

Also talk about things like [FromBody] attribute and when it's required. Should be scenario-based, not just a repeat of the docs on model binding, though.

Understanding Required ASP.NET Core Files

ASPNET > Getting Started

• Program.cs
• Startup.cs
• (project.json) - leave out for now since it's changing

Spend most of the time on Startup.cs and cover the 3 methods that one typically uses:

• constructor (optional)
• ConfigureServices
• Configure

See https://docs.asp.net/en/latest/fundamentals/startup.html

Injecting Dependencies into Controllers

ASPNET > Getting Started

• Show how Controllers can follow Explicit Dependencies Principle and request their dependencies via their constructor.
• Show how to configure services in ConfigureServices (going beyond what's in lesson 8).
• Demonstrate how to use a configured service to perform some work for a view-based controller and for an API method.
• Note that dependencies should be small and focused on only UI concerns. Business logic should go into other classes and should be injected. This makes both controllers and business classes easier to test (see next lesson).

Configuring Different Environments

ASPNET > Getting Started

Describe environment variable support in ASP.NET. Focus mainly on the Environment environment variable, which is exposed via IsDevelopment in Startup's methods.

• Show how to use the environment to request a different configuration settings file (e.g. settings.development.json).
• Show how to only show developer error page if IsDevelopment
• Show how to use launchSettings to set the environment (in Visual Studio, anyway)
• Show how to manually set environment variables in Windows and Mac
• Show how to use environment-specific methods in Startup (e.g. ConfigureDevelopment)

See https://docs.asp.net/en/latest/fundamentals/environments.html#id3

When and How to Use Exceptions

• try-catch-finally usage
• throw usage
• Don't throw new exceptions from catch blocks - instead just throw; unless you're creating a program-specific exception, in which case keep the current one in an innerException
• Don't use exceptions for control flow
• Common built-in exceptions and when to use them
• How to create your own custom exception types

Looping Based on a Logical Expression

Show how to use loops with logical expressions (see #5). This should focus mainly on the while() loop construct - other loops (for, foreach) are covered in later lessons.

Understanding Events and Event-Driven Programming

• C# event keyword
• Creating and registering event handlers
• Examples of UI-based event programming (click handler)

Implementing Logical Expressions

Describe how to create logical expressions and use them with if statements, using only concepts covered up to this point in the tutorial.

Add REPL Instructions to Getting Started with C#

Add REPL instructions, once we know how we'll be implementing it, to https://github.com/dotnet/training-tutorials/blob/master/content/csharp/getting-started/lesson-01.md

Understanding ASP.NET Core MVC Filters

ASPNET > Getting Started

Review some controller code we've built so far. Identify some duplicate logic.

• Introduce Filters
• Show how to use a built-in filter to reduce some duplication / perform some work (if we can)
• Show how to create and use a custom filter

Reference:
https://docs.asp.net/en/latest/mvc/controllers/filters.html
Steve has a Filters article that will be in August MSDN he can share

Working with Arrays and Collections

Start with the args array on a console app; these have already been covered.

• How to declare arrays
• Common operations on arrays (setting/getting element values, etc.)
• Split, Join
• ToList()

Lists (just show List)

• How to declare
• Add, Remove, Clear
• ToArray()

LINQ isn't covered until later, but you can show the extension methods for going to/from arrays and lists. Also maybe show the constructors that take in arrays as list initializers. Don't show iterating through or looping over arrays/lists - that's in the next lesson.

Encapsulation and Object-Oriented Design

• What is encapsulation?
• How to model a real-world problem using objects?
• Single Responsibility Principle
• Tell, Don't Ask Principle
• Reinforce composition over inheritance; show providing dependencies via constructor
• Explicit Dependencies Principle

Defining and Calling Methods

• General structure of a method
• Naming guidelines (briefly)
• static or not?
• Don't get into scope and accessibility (public, protected, etc.) here, or virtual - those are covered later
• void vs. return types
• What happens in the calling code if a parameter is modified within a method?
• out parameters
• optional parameters
• default parameters
• params arrays
• overloads

Serving Static Files

ASPNET > Getting Started

Show how to add support for serving static files.

Add some static files. Maybe a favicon and/or some CSS that will be used by responses. Maybe an index.html.

REPL support for inline code samples

Code samples should have a button that will load the code into the REPL. In many cases, additional context will need to be added. For example, a single line of code saying
Console.WriteLine("Hello World!");

would need to be added to an existing Main() method in order to run properly. Another line of code added later as its own code block might need to be added to the existing code in the REPL, rather than replacing it.

Research how to embed the necessary code and instructions within the markdown to support this behavior.

See http://www.tryfsharp.org/Learn/getting-started#bindings-values for an example of desired behavior.

Testing ASP.NET Core Apps

ASPNET > Getting Started

• Show setting up xUnit
• Show how to unit test a business service created in last lesson.
• Show how to unit test a controller action (if appropriate)
• Show how to configure a TestHost for integration testing
• Show how to write integration tests using TestHost

Reference: https://docs.asp.net/en/latest/mvc/controllers/testing.html

Update Lesson 1 For REPL / Tips

Update C# Getting Started Lesson 1:

• Examples use REPL format
• Add tips for newLanguage

Syntax:

Tip {.tip .newLanguage }

This the tip.
This is some more of the tip

Returning Data or Views from Controllers

ASPNET > Getting Started

Expand on previous article regarding Controller helpers for creating views. Talk about how to refer to views (empty string, by name, by filename).

For Web API, talk about returning simple types, but then show that returning an IActionResult is better. See dotnet/AspNetCore.Docs#1327 (which will be on docs.asp.net soon) for reference.

Your First ASP.NET Core App

ASPNET > Getting Started

Introduce ASP.NET
Create a new ASP.NET app from a console app.

• Add dependencies
• Add Startup.cs
• Create a new WebHostBuilder in Main
• Run it

Understanding Classes and Objects

Brief intro to OOP for beginners

• What is a class?
• What is an object?
• Everything in C#/.NET is an object/inherits from System.Object
• What are properties and fields? Define composition
• Basic inheritance
• Virtual keyword; Overrides keyword
• Prefer composition to inheritance
• Reference vs. Value types (unless there's a better place to cover this)

Adding Basic Configuration Support

ASPNET > Getting Started

Show how to set up configuration.

Add a Configuration property in Startup. Build it to use a fixed settings.json or similar file. Display something based on the configuration, such as the application name.

Configuring Different Hosts

ASPNET > Getting Started

The app should already be configured to work with Kestrel. In this article, show how to add support for IIS and/or WebListener.

Working with Data in your ASP.NET Core App

Introduce Entity Framework Core

• Show how to add to project
• Show how to configure In Memory provider
• Show how to configure for SQL Server (but don't put this in our demo)
• Show how request EF directly from Controller
  • Talk about why this is a bad idea due to directly coupling to implementation details
• Show how to pull EF code into a Repository and request the IRepository from Controller
• Show how to use some LINQ with EF to query data

Possible source of data - 404s to the application. See:
https://msdn.microsoft.com/en-us/magazine/mt707525.aspx

Wrap up and clean up the MVC sample and make sure there is a final version that students can download and immediately run successfully.

Introducing ASP.NET Core MVC

ASPNET > Getting Started

Start with a new web project template in Visual Studio. Don't include authorization/account bits.

Review and discuss

• How MVC is configured in Startup
• Folder structure
  • Controllers
  • Views
• What is a model. Considerations for using your application model as your client/view model (and when to avoid this)
• Default route (/controller/action/id?)

Working with ASP.NET Core MVC Views

ASPNET > Getting Started

Enhance the application that's being built by leveraging some view features:

• ViewStart
• ViewImports
• Layout
• Partials
• Passing viewmodels into views (@model attribute in view)

No need to go into huge depth with these. Refer to docs for more.
https://docs.asp.net/en/latest/mvc/views/index.html

Working with the dotnet Command Line Interface (CLI)

ASPNET > Getting Started

Show dotnet commands related to asp.net development:

• dotnet new
• dotnet restore
• dotnet build
• dotnet run

Repo Access

@martinwoodward I need to add more committers in order to deliver this content. Can you give me permission to do so? Also, I would like to add a second repo that will contain the first tutorial's code samples. Let me know if I can get that access to do so, or if I need to work through someone else. Note that I'm already a committer in the aspnet organization on GitHub, if that helps.

Common Patterns and Anti-Patterns

Patterns

• Factory
• Strategy
• Adapter
• Repository

Anti-Patterns

• Static Cling
• new is Glue
• Singleton

Enable show/hide sections within lessons

Some lessons, like https://github.com/dotnet/training-tutorials/blob/master/content/csharp/getting-started/lesson-01.md have content that may not apply to the user. Later, if we recognize that the user is going through the lesson using REPL, or VSCode+CLI, or Visual Studio, we may want to show or hid certain sections from them.

Figure out a convention that will work with the current Markdown-based solution for enabling this. Consider custom Markdown attributes and inline HTML as possible options.

Add 'Next Steps' For Students

Most of the lessons should include some kind of next steps that offer some ideas for students to try on their own.

Remove/Hide Project.Json from C# Getting Started Lesson 2

https://github.com/dotnet/training-tutorials/blob/master/content/csharp/getting-started/lesson-02.md

The project format is changing and the syntax won't matter to viewers trying out the code in the REPL or working strictly through the CLI (once it better supports managing dependencies).

Introducing LINQ

Briefly introduce LINQ

Cover common extension methods:

• Where
• Select
• FirstOrDefault
• Any
• ToList
• ToArray

Mention usage with some ORMs like Entity Framework but don't go into detail.

Adding more committers

@martinwoodward can I add additional committers to this repo, or do I need to have you invite them?

Thanks!
Steve

Looping Through Members of a Collection

Focus mainly on foreach. Demonstrate its use with arrays and lists. Mention that arrays and lists are both examples of collections. Demonstrate other ways to loop through collections (e.g. for loop, while loop).

Building Your Own Middleware

ASPNET > Getting Started

• Convert a custom middleware statement from Configure in Startup to its own class
• Create an extension method as a convenient way to add the middleware
• Use the extension method to add the middleware in Configure

Working with Scope and Accessibility Modifiers

• Local variable scoping rules
• public/private/internal/protected keywords and access impact

internal can be covered briefly since multiple projects aren't covered yet.