Add additional .NET Primer documents

docs/concepts/assembly-format.rst

@@ -0,0 +1,66 @@
+.NET Assembly File Format
+=========================
+
+The .NET platform defines a binary file format - "assembly" - that is
+used to fully-describe and contain .NET programs. Assemblies are used
+for the programs themselves as well as any dependent libraries. A .NET
+program can be executed as one of more assemblies, with no other
+required artifacts, beyond the appropriate .NET runtime. Native
+dependencies, including operating system APIs, are a separate concern
+and are not contained within the .NET assembly format, although are
+sometimes described with this format (e.g. WinRT).
+
+    Each CLI component carries the metadata for declarations,
+    implementations, and references specific to that component.
+    Therefore, the component-specific metadata is referred to as
+    component metadata, and the resulting component is said to be
+    self-describing -- from ECMA 335 I.9.1, Components and assemblies.
+
+The format is fully specified and standardized as `ECMA
+335 <dotnet-standards.md>`__. All .NET compilers and runtimes use this
+format. The presense of a documented and infrequently updated binary
+format has been a major benefit (arguably a requirement) for
+interoperatibility. The format was last updated in a substantive way in
+2005 (.NET 2.0) to accomodate generics and processor architecture.
+
+The format is CPU- and OS-agnostic. It has been used as part of .NET
+runtimes that target many chips and CPUs. While the format itself has
+Windows heritage, it is implementable on any operating system. It's
+arguably most significant choice for OS interopertability is that most
+values are stored in little-endian format. It doesn't have a specific
+affinity to machine pointer size (e.g. 32-bit, 64-bit).
+
+The .NET assembly format is also very descriptive about the structure of
+a given program or library. It describes the internal components of an
+assembly, specifically: assembly references and types defined and their
+internal structure. Tools or APIs can read and process this information
+for display or to make programmatic decisions.
+
+Format
+------
+
+The .NET binary format is based on the Windows `PE
+file <http://en.wikipedia.org/wiki/Portable_Executable>`__ format. In
+fact, .NET class libraries are conformant Windows PEs, and appear on
+first glance to be Windows dynamic link libraries (DLLs) or application
+executables (EXEs). This is a very useful characteristic on Windows,
+where they can masquerade as native executable binaries and get some of
+the same treatment (e.g. OS load, PE tools).
+
+.. image:: primer/_static/assembly-headers.png
+
+Assembly Headers
+Assemblies headers from ECMA 335 II.25.1, Structure of the runtime file
+format.
+
+Processing the Assemblies
+-------------------------
+
+It is possible to write tools or APIs to process assemblies. Assembly
+information enables making programmatic decisions at runtime, re-writing
+assemblies, providing API intellisense in an editor and generating
+documentation.
+`System.Reflection <https://msdn.microsoft.com/library/system.reflection.aspx>`__
+and
+`Mono.Cecil <http://www.mono-project.com/docs/tools+libraries/libraries/Mono.Cecil/>`__
+are good examples of tools that are frequently used for this purpose.

docs/concepts/class-libraries.rst

@@ -0,0 +1,105 @@
+.NET Class Libraries
+====================
+
+Class libraries are the `shared
+library <http://en.wikipedia.org/wiki/Library_(computing)#Shared_libraries>`_
+concept for .NET. They enable you to componentize useful functionality
+into modules that can be used by multiple applications. They can also be
+used as a means of loading functionality that is not needed or not known
+at application startup. Class libraries are described using the `.NET
+Assembly file format <assembly*format.md>`_.
+
+There are three types of class libraries that you can use:
+
+*  **Platform*specific** class libraries have access to all the APIs in
+   a given platform (e.g. .NET Framework, Xamarin iOS), but can only be
+   used by apps and libraries that target that platform.
+*  **Portable** class libraries have access to a subset of APIs, and can
+   be used by apps and libraries that target multiple platforms.
+*  **.NET Core** class libraries are a merger of the platform*specific
+   and portable library concept into a single model that provides the
+   best of both.
+
+Platform*specific Class Libraries
+*********************************
+
+Platform*specific libraries are bound to a single .NET platform (e.g.
+.NET Framework on Windows) and can therefore take significant
+dependencies on a known execution environment. Such an environment will
+expose a known set of APIs (.NET and OS APIs) and will maintain and
+expose expected state (e.g. Windows registry).
+
+Developers who create plaform specific libraries can fully exploit the
+underlying platform. The libraries will only ever run on that given
+platform, making platform checks or other forms of conditional code
+unnecessary (modulo single sourcing code for multiple platforms).
+
+Platform*specific libraries have been the primary class library type for
+the .NET Framework. Even as other .NET platforms emerged,
+platform*specific libraries remained the dominant library type.
+
+Portable Class Libraries
+************************
+
+Portable libraries are supported on multiple .NET platforms. They can
+still take dependencies on a known execution environment, however, the
+environment is a synthetic one that is generated by the intersection of
+a set of concrete .NET platforms. This means that exposed APIs and
+platform assumptions are a subset of what would be available to a
+platform*specific library.
+
+You choose a platform configuration when you create a portable library.
+These are the set of platforms that you need to support (e.g. .NET
+Framework 4.5+, Windows Phone 8.0+). The more platforms you opt to
+support, the fewer APIs and fewer platform assumptions you can make, the
+lowest common denominator. This characteristic can be confusing at
+first, since people often think "more is better", but find that more
+supported platforms results in fewer available APIs.
+
+Many library developers have switched from producing multiple
+platform*specific libraries from one source (using conditional
+compilation directives) to portable libraries. There are `several
+approaches <http://blog.stephencleary.com/2012/11/portable*class*library*enlightenment.html>`__
+for accessing platform*specific functionality within portable libraries,
+with
+`bait*and*switch <http://log.paulbetts.org/the*bait*and*switch*pcl*trick/>`__
+being the most widely accepted technique at this point.
+
+.NET Core Class Libraries
+-------------------------
+
+.NET Core libraries are a replacement of the platform*specific and
+portable libraries concepts. They are platform*specific in the sense
+that they expose all functionality from the underlying platform (no
+synthetic platforms or platform intersections). They are portable in the
+sense that they work on all supporting platforms.
+
+.NET Core exposes a set of library *contracts*. .NET platforms must
+support each contract fully or not at all. Each platform, therefore,
+supports a set of .NET Core contracts. The corollary is that each .NET
+Core class library is supported on the platforms that support it's
+contract dependencies.
+
+.NET Core contracts do not expose the entire functionality of the .NET
+Framework (nor is that a goal), however, they do expose many more APIs
+than Portable Class Libraries. More APIs will be added over time.
+
+The following platforms support .NET Core class libraries:
+
+*  .NET Core 5
+*  ASP.NET 5
+*  .NET Framework 4.5+
+*  Windows Store Apps
+*  Windows Phone 8+
+
+Mono Class Libraries
+--------------------
+
+Class libraries are supported on Mono, including the three types of
+libraries described above. Mono has often been seen (correctly) as a
+cross*platform implementation of the Microsoft .NET Framework. In part,
+this was because platform*specific .NET Framework libraries could run on
+the Mono runtime without modification or re*compilation. This
+characteristic was in place before the creation of portable class
+libraries, so was an obvious choice to enable binary portability between
+the .NET Framework and Mono (although it only worked in one direction).

docs/concepts/framework-libraries.rst

@@ -0,0 +1,121 @@
+Framework Libraries
+===================
+
+.NET has an expansive standard set of class libraries, referred to as
+either the base class libraries (core set) or framework class libraries
+(complete set). These libraries provide implementations for many general
+and app-specific types, algorithms and utility functionality. Both
+commercial and community libraries build on top of the framework class
+libraries, providing easy to use off-the-shelf libraries for a wide set
+of computing tasks.
+
+A subset of these libraries are provided with each .NET implementation.
+Base Class Library (BCL) APIs are expected with any .NET implementation,
+both because developers will want them and because popular libraries
+will need them to run. App-specific libraries above the BCL, such as
+ASP.NET, will not be available on all .NET implementations.
+
+Base Class Libraries
+--------------------
+
+The BCL provides the most foundational types and utility functionality
+and are the base of all other .NET class libraries. They aim to provide
+very general implementations without any bias to any workload.
+Performance is always an important consideration, since apps might
+prefer a particular policy, such as low-latency to high-throughput or
+low-memory to low-CPU usage. These libraries are intended to be
+high-performance generally, and take a middle-ground approach according
+to these various performance concerns. For most apps, this approach has
+been quite successful.
+
+Primitive Types
+---------------
+
+.NET includes a set of primitive types, which are used (to varying
+degrees) in all programs. These types contain data, such as numbers,
+strings, bytes and arbitrary objects. The C# language includes keywords
+for these types. A sample set of these types is listed below, with the
+matching C# keywords.
+
+*  `System.Object <https://msdn.microsoft.com/library/system.object.aspx>`__
+   (`object <https://msdn.microsoft.com/library/9kkx3h3c.aspx>`__) - The
+   ultimate base class in the CLR type system. It is the root of the
+   type hierarchy.
+*  `System.Int16 <https://msdn.microsoft.com/library/system.int16.aspx>`__
+   (`short <https://msdn.microsoft.com/library/ybs77ex4.aspx>`__) - A
+   16-bit signed integer type. The unsigned
+   `UInt16 <https://msdn.microsoft.com/en-us/library/system.uint16.aspx>`__
+   also exists.
+*  `System.Int32 <https://msdn.microsoft.com/library/system.int32.aspx>`__
+   (`int <https://msdn.microsoft.com/library/5kzh1b5w.aspx>`__) - A
+   32-bit signed integer type. The unsigned
+   `UInt32 <https://msdn.microsoft.com/library/x0sksh43.aspx>`__ also
+   exists.
+*  `System.Single <https://msdn.microsoft.com/library/system.single.aspx>`__
+   (`float <https://msdn.microsoft.com/library/b1e65aza.aspx>`__) - A
+   32-bit floating-point type.
+*  `System.Decimal <https://msdn.microsoft.com/library/system.decimal.aspx>`__
+   (`decimal <https://msdn.microsoft.com/library/364x0z75.aspx>`__) - A
+   128-bit decimal type.
+*  `System.Byte <https://msdn.microsoft.com/en-us/library/system.byte.aspx>`__
+   (`byte <https://msdn.microsoft.com/library/5bdb6693.aspx>`__) - An
+   unsigned 8-bit integeger that represents a byte of memory.
+*  `System.Boolean <https://msdn.microsoft.com/library/system.boolean.aspx>`__
+   (`bool <https://msdn.microsoft.comlibrary/c8f5xwh7.aspx>`__) - A
+   boolean type that represents 'true' or 'false'.
+*  `System.Char <https://msdn.microsoft.com/library/system.char.aspx>`__
+   (`char <https://msdn.microsoft.com/library/x9h8tsay.aspx>`__) - A
+   16-bit numeric type that represents a Unicode character.
+*  `System.String <https://msdn.microsoft.com/library/system.string.aspx>`__
+   (`string <https://msdn.microsoft.com/library/362314fe.aspx>`__) -
+   Represents a series of characters. Different than a ``char[]``, but
+   enables indexing into each individual ``char`` in the ``string``.
+
+Data Structures
+---------------
+
+.NET includes a set of data structures that are the workhorses of almost
+any .NET apps. These are mostly collections, but also include other
+types.
+
+*  `Array <https://msdn.microsoft.com/library/system.array.aspx>`__ -
+   Represents an array of strongly types objects that can be accessed by
+   index. Has a fixed size, per its construction.
+*  `List <https://msdn.microsoft.com/library/6sh2ey19.aspx>`__ -
+   Represents a strongly typed list of objects that can be accessed by
+   index. Is automatically resized as needed.
+*  `Dictionary <https://msdn.microsoft.com/library/xfhwa508.aspx>`__ -
+   Represents a collection of values that are indexed by a key. Values
+   can be accessed via key. Is automatically resized as needed.
+*  `Uri <https://msdn.microsoft.com/library/system.uri.aspx>`__ -
+   Provides an object representation of a uniform resource identifier
+   (URI) and easy access to the parts of the URI.
+*  `DateTime <https://msdn.microsoft.com/library/system.datetime.aspx>`__
+   - Represents an instant in time, typically expressed as a date and
+   time of day.
+
+Utility APIs
+------------
+
+.NET includes a set of utility APIs that provide functionality for many
+important tasks.
+
+*  `HttpClient <https://msdn.microsoft.com/library/system.net.http.httpclient.aspx>`__
+   - An API for sending HTTP requests and receiving HTTP responses from
+   a resource identified by a URI.
+*  `XDocument <https://msdn.microsoft.com/library/system.xml.linq.xdocument.aspx>`__
+   - An API for loading, and querying XML documents with LINQ.
+*  `StreamReader <https://msdn.microsoft.com/library/system.io.streamreader.aspx>`__
+   - An API for reading files
+   (`StreamWriter <https://msdn.microsoft.com/library/system.io.stringwriter.aspx>`__)
+   Can be used to write files.
+
+App-Model APIs
+--------------
+
+There are many app-models that can be used with .NET, provided by
+several companies.
+
+*  `ASP.NET <http://asp.net>`_ - Provides a web framework for building
+   Web sites and services. Supported on Windows, Linux and OS X (depends
+   on ASP.NET version).

docs/concepts/gc-overview.rst

@@ -0,0 +1,61 @@
+Garbage Collection
+==================
+
+Garbage collection is one of most important features of the .NET managed
+code platform. The garbage collector (GC) manages allocating and
+releasing memory for you. You do not need to how to allocate and release
+memory or manage the lifetime of the objects that use that memory. An
+allocation is made any time you *new* an object or a value type is
+boxed. Allocations are typically very fast. When there isn't enough
+memory to allocate an object, the GC must collect and dispose of garbage
+memory to make memory available for new allocations. This process is
+called "garbage collection".
+
+The garbage collector serves as an automatic memory manager. It provides
+the following benefits:
+
+*  Enables you to develop your application without having to free
+   memory.
+*  Allocates objects on the managed heap efficiently.
+*  Reclaims objects that are no longer being used, clears their memory,
+   and keeps the memory available for future allocations. Managed
+   objects automatically get clean content to start with, so their
+   constructors do not have to initialize every data field.
+*  Provides memory safety by making sure that an object cannot use the
+   content of another object.
+
+The .NET GC is generational and has 3 generations. Each generation has
+its own heap that it uses for storage of allocated objects. There is a
+basic principle that most objects are either short lived or long lived.
+Generation 0 is where objects are first allocated. Objects often don't
+live past the first generation, since they are no longer in use (out of
+scope) by the time the next garbage collection occurs. Generation 0 is
+quick to collect because its associated heap is small. Generation 1 is
+really a second chance space. Objects that are short lived but survive
+the generation 0 collection (often based on coincidental timing) go to
+generation 1. Generation 1 collections are also quick because its
+associated heap is also small. The first two heaps remain small because
+objects are either collected or are promoted to the next generation
+heap. Generation 2 is where all long lived objects are. The generation 2
+heap can grow to be very large, since the objects it contains can
+survive a long time and there is no generation 3 heap to further promote
+objects.
+
+The GC has has an additional heap for large objects called the Large
+Object Heap (LOH). It is reserved for objects that are 85,000 bytes or
+greater. A byte array (Byte[]) with 85k elements would be an example of
+a large object. Large objects are not allocated to the generational
+heaps but are allocated directly to the LOH.
+
+Generation 2 and LOH collections can take noticeable time for programs
+that have run for a long time or operate over large amounts of data.
+Large server programs are known to have heaps in the 10s of GBs. The GC
+employs a variety of techniques to reduce the amount of time that it
+blocks program execution. The primary approach is to do as much garbage
+collection work as possible on a background thread in a way that does
+not interfere with program execution. The GC also exposes a few ways for
+developers to influence its behavior, which can be quite useful to
+improve performance.
+
+For more information, see `Garbage
+Collection <http://msdn.microsoft.com/library/0xy59wtx.aspx>`_ on MSDN.