<!-- TODO: Chapters in "Ian Griffiths - Programming C# 8.0 - Build Cloud, Web, and Desktop Applications.pdf"
7. Object Lifetime
10. LINQ
11. Reactive Extensions
12. Reflection
13. Multithreading
14. Asyncronous Language Features
16. Memory Efficiency
Current Page: 423/761
-->
**.NET** Core is a development platform that includes a **Common Language Runtime** (**CoreCLR**), which manages the execution of code, and a **Base Class Library** (**BCL**), which provides a rich library of classes to build applications from.
The C# compiler (named **Roslyn**) used by the dotnet CLI tool converts C# source code into **intermediate language** (**IL**) code and stores the IL in an _assembly_ (a DLL or EXE file).
At runtime, CoreCLR loads the IL code from the assembly, the **just-in-time** (JIT) compiler compiles it into native CPU instructions, and then it is executed by the CPU on your machine.
The benefit of this three-step compilation process is that Microsoftis able to create CLRs for Linux and macOS, as well as for Windows.
The same IL code runs everywhere because of the second compilation process, which generates code for the native operating system and CPU instruction set.
Regardless of which language the source code is written in, for example, C#, Visual Basic or F#, all .NET applications use IL code for their instructions stored in an assembly.
Another .NET initiative is called _.NET Native_. This compiles C# code to native CPU instructions **ahead of time** (**AoT**), rather than using the CLR to compile IL code JIT
.NET Native improves execution speed and reduces the memory footprint for applications because the native code is generated at build time and then deployed instead of the IL code.
## Basics
### Comments
```cs
// comment
/* multi line comment */
// / single line xml comment (docstring)
/** multi line xml string (docsting) */
```
### Docstring Structure
`/** <tag> content </tag> **/`
### Naming Convention
| Element | Case |
| ------------------------ | ---------- |
| Namespace | PascalCase |
| Class, Interface | PascalCase |
| Method | PascalCase |
| Field, Property | PascalCase |
| Event, Enum, Enum Value, | PascalCase |
| Variables, Parameters | camelCase |
### Namespaces & Imports
Hierarchic organization of programs an libraries.
```cs
using System; // import the System Namespace
using Alias = Namespace; // set an alias for a specific namespace
using static System.Console; // statically import a class to use its static methods w/o qualification
namespace Namespace // dichiarazione namespace di appartenenza (classi e librerie)
`$"{number:X}"` formats the number as a _hexadecimal_.
## Variable Types
### Value Type
A value type variable will store its values directly in an area of storage called the _STACK_.
The stack is memory allocated to the code that is currently running on the CPU.
When the stack frame has finished executing, the values in the stack are removed.
### Reference Type
A reference type variable will store its values in a separate memory region called the _HEAP_.
The heap is a memory area that is shared across many applications running on the operating system at the same time.
The .NET Runtime communicates with the operating system to determine what memory addresses are available, and requests an address where it can store the value.
The .NET Runtime stores the value, then returns the memory address to the variable.
When your code uses the variable, the .NET Runtime seemlessly looks up the address stored in the variable and retrieves the value that's stored there.
### Integral Numeric Types
| Keyword | System Type | Example | Bit/Byte | Min Value | Max Value |
The static fields and methods of the `MathF` class correspond to those of the `Math` class, except that their parameters are of type `Single` rather than `Double`, and they return `Single` rather than `Double` values.
To be considered equal, two tuples must have the same shape and each value in the first tuple must be equal to its counterpart in thesecond tuple.
```cs
(Type Var1, Type Var2, ...) variable = (value1, value2, ...);
var variable = (Var1: value1, Var2: value2, ...); // if name are not supplied they default to Item1, Item2, ...
var variable = (var1, var2); // constructed w/ pre-existing values, tuple attributes named after the variables
```
Since the names of the attributes of a tuple do not matter (a tuple is an instance of `ValueTuple<Type, Type, ...>`) it's possible to assign any tuple to another tuple with the same structure.
```cs
(int X, Int Y) a = (1 , 0);
(int Width, int Height) b = a;
```
### Tuple Deconstruction
```cs
(int X, int Y) point = (10, 35);
(int a, int b) = point; // extract data based on position into two variables
```
## Records (C# 9)
```cs
// mutable record
public record RecordName
{
public Type Property1 { get; init; }
public Type Property2 { get; init; }
// Equals(), Equaliy Operators, GetHashCode(), ToString() generated by .NET
}
// immutable record
public record RecordName ( Type Property1, Type Property2, ...);
With-expressions use object initializer syntax to state what’s different in the new object from the old object. it's possible to specify multiple properties.
A record implicitly defines a protected “copy constructor” – a constructor that takes an existing record object and copies it field by field to the new one.
All objects inherit a virtual `Equals(object)` method from the object class. This is used as the basis for the `Object.Equals(object, object)` static method when both parameters are non-null.
Structs override this to have “value-based equality”, comparing each field of the struct by calling `Equals` on them recursively. Records do the same.
Records have a hidden virtual method that is entrusted with “cloning” the whole object.
Every derived record type overrides this method to call the copy constructor of that type, and the copy constructor of a derived record chains to the copy constructor of the base record.
A with-expression simply calls the hidden “clone” method and applies the object initializer to the result.
.NET strings are _immutable_. The downside of immutability is that string processing can be inefficient.
If a work performs a series of modifications to a string it will end up allocating a lot of memory, because it will return a separate string for each modification.
C# 8.0 introduces nullable reference types and non-nullable reference types that enable to make important statements about the properties for reference type variables:
- **A reference isn't supposed to be null**. When variables aren't supposed to be null, the compiler enforces rules that ensure it's safe to dereference these variables without first checking that it isn't null:
- The variable must be initialized to a non-null value.
- The variable can never be assigned the value null.
- **A reference may be null**. When variables may be null, the compiler enforces different rules to ensure that you've correctly checked for a null reference:
- The variable may only be dereferenced when the compiler can guarantee that the value isn't null.
- These variables may be initialized with the default null value and may be assigned the value null in other code.
The `?` character appended to a reference type declares a nullable reference type.
The **null-forgiving operator**`!` may be appended to an expression to declare that the expression isn't null.
Any variable where the `?` isn't appended to the type name is a non-nullable reference type.
#### Nullability of types
Any reference type can have one of four _nullabilities_, which describes when warnings are generated:
- _Nonnullable_: Null can't be assigned to variables of this type. Variables of this type don't need to be null-checked before dereferencing.
- _Nullable_: Null can be assigned to variables of this type. Dereferencing variables of this type without first checking for null causes a warning.
- _Oblivious_: Oblivious is the pre-C# 8.0 state. Variables of this type can be dereferenced or assigned without warnings.
- _Unknown_: Unknown is generally for type parameters where constraints don't tell the compiler that the type must be nullable or nonnullable.
The nullability of a type in a variable declaration is controlled by the nullable context in which the variable is declared.
#### Nullable Context
Nullable contexts enable fine-grained control for how the compiler interprets reference type variables.
Valid settings are:
- _enable_: The nullable annotation context is _enabled_. The nullable warning context is _enabled_.
Variables of a reference type are non-nullable, all nullability warnings are enabled.
- _warnings_: The nullable annotation context is _disabled_. The nullable warning context is _enabled_.
Variables of a reference type are oblivious; all nullability warnings are enabled.
- _annotations_: The nullable annotation context is _enabled_. The nullable warning context is _disabled_.
Variables of a reference type are non-nullable; all nullability warnings are disabled.
- _disable_: The nullable annotation context is _disabled_. The nullable warning context is _disabled_.
Variables of a reference type are oblivious, just like earlier versions of C#; all nullability warnings are disabled.
var variable = var ?? value // return var if var != null, return value otherwise
variable = variable?.property ?? value // if (variable == null) -> variable = value -- null coalescing
// same as
variable ??= value; // if (variable == null) -> variable = value -- null coalescing
```
### Nullable Attributes
It's possible to apply a number of attributes that provide information to the compiler about the semantics of APIs.
That information helps the compiler perform static analysis and determine when a variable is not null.
-`AllowNull`: A non-nullable input argument may be null.
-`DisallowNull`: A nullable input argument should never be null.
-`MaybeNull`: A non-nullable return value may be null.
-`NotNull`: A nullable return value will never be null.
-`MaybeNullWhen`: A non-nullable input argument may be null when the method returns the specified bool value.
-`NotNullWhen`: A nullable input argument will not be null when the method returns the specified bool value.
-`NotNullIfNotNull`: A return value isn't null if the argument for the specified parameter isn't null.
-`DoesNotReturn`: A method never returns. In other words, it always throws an exception.
-`DoesNotReturnIf`: This method never returns if the associated bool parameter has the specified value.
---
## Type Conversion
```cs
variable.GetType(); // System type of variable
(type) variable // ecplicit conversion
numericalType.ToSting(); // convert numerical value to a string
numericalType variable = <SystemType/Type>.Parse(); // convert string to numerical datat type (can cause exceptio at runtime)
<SystemType/Type>.TryParse(value, out variable); // improved version of Parse()
/* attempts to parse a string into the given numeric data type.
If successful, it will store the converted value in an OUT PARAMETER.
It returns a bool to indicate if it was successful or not */
Convert.To<SystemType>(variable); // proper conversion and round-up of values (no truncation of values)
```
### Converting from any type to a string
The `ToString` method converts the current value of any variable into a textual representation. Some types can't be sensibly represented as text, so they return their namespace and type name.
### Number Downcasting
The rule for rounding (in explicit casting) in C# is subtly different from the primary school rule:
- It always rounds _down_ if the decimal part is less than the midpoint `.5`.
- It always rounds _up_ if the decimal part is more than the midpoint `.5`.
- It will round _up_ if the decimal part is the midpoint `.5` and the non-decimal part is odd, but it will round _down_ if the non-decimal part is even.
It’s common to define compilation symbols through the _compiler build settings_: open up the `.csproj` file and define the values you want in a `<DefineConstants>` element of any `<PropertyGroup>`.
Compilation symbols are typically used in conjunction with the `#if`, `#else`, `#elif`, and `#endif` directives (`#if false` also exists).
C# provides a more subtle mechanism to support this sort of thing, called a _conditional method_.
The compiler recognizes an attribute defined by the .NET class libraries, called `ConditionalAttribute`, for which it provides special compiletime behavior.
Method annotated with this attribute will not be present in a non-Debug release.
C# allows choose to generate _compiler errors_ or warnings with the `#error` and `#warning` directives. These are typically used inside conditional regions.
```cs
#if NETSTANDARD
#error .NET Standard is not a supported target for this source file
The `#pragma` directive provides two features: it can be used to disable selected compiler warnings, and it can also be used to override the checksum values the compilerputs into the `.pdb` file it generates containing debug information.
else if (o is Type t) // test variable to determine if matches a type
{
// t gets the value of o if the test succedes
}
else
{
// code here
}
```
### Switch
The `when` keyword can be used to specify a filter condition that causes its associated case label to be true only if the filter condition is also true.
A pattern describes one or more criteria that a value can be tested against.
```cs
switch(o)
{
case Type t: // type pattern
// code here
break;
case (Type X, Type Y): // positional pattern
// code here
break;
case (Type X, _): // positional pattern + dicard pattern
// code here
break;
case Type {Property : value}: // property patten (check Type and that the property has a certain value)
// code here
break;
case Type {Property : value} p: // property patten with output (variable p is usable in the block)
// code here
break;
case Type {Property: Type variable}: // Property pattern with nested pattern with output
// code here
break;
case value when(condition):
// code here
break;
case <value:
// code here
break;
case <= value and >= value:
// code here
break;
case > value
// code here
break;
}
// is pattern matching
bool isWhatever = value is (Type X, Type Y, ...);
if (value is (Type X, Type Y, ...)){
// can use X & Y
}
```
## Loop Statements
### `While` Loop
```cs
while (condition)
{
// code here
}
```
## `Do`-`While` Loop
Executes at least one time.
```cs
do
{
// code here
}
while (condition);
```
### `For` Loop
```cs
for (initializer; condition; iterator)
{
// code here
}
```
### `Foreach` Loop
Technically, the `foreach` statement will work on any type that follows these rules:
1. The type must have a method named `GetEnumerator` that returns an object.
2. The returned object must have a property named `Current` and a method named `MoveNext`.
3. The `MoveNext` method must return _true_ if there are more items to enumerate through or _false_ if there are no more items.
There are interfaces named `IEnumerable` and `IEnumerable<T>` that formally define these rules but technically the compiler does not require the type to implement these interfaces.
It's possible configure the C# compiler to put everything into a checked context by default, so that only explicitly unchecked expressions and statements will be able to overflow silently.
// Immediately terminate a process after writing a message to the Windows Application event log, and then include the message and optional exception information in error reporting to Microsoft.
Enviroment.FailFast(casuseOfFaliure);
```
### Custom Exceptions
```cs
public class CustomException : Exception // must derive from Excpetion (either directly or indirectly)
{
public CustomException()
{
}
public CustomException(string message)
: base(message)
{
}
public CustomException(string message, Exception inner)
: base(message, inner)
{
}
}
```
---
## Enums
Declare a set of named integer numeric constants (`int`, `long`, `byte`, ...).
Consecutive names increase the value by one.
```cs
[System.Flags] // indicate that the flag can be conbined (best if values are binary)
enum enumType : IntegralNumericType // named values MUST match IntegerNumericType allowed values
{
name1, // if uninitiated values id zero (0)
name2 = 10, // value is 10
name3, // value is name2 + 1
name4, // value is name3 + 1
}
(Type) enumType.name1; // extract the value, will return the name otherwise
(enumType) value; // convert from associated value to enum
Enum.IsDefined(enumType, value); // whether a given integral value, or its name as a string, exists in a specified enumeration.
```
---
## Methods
The method signature is the number & type of the input parameters defined for the method.
C# makes the fairly common distinction between _parameters_ and _arguments_: a method defines a list of the inputs it expects (the parameters) and the code inside the method refers to these parameters by name.
The values seen by the code could be different each time the method is invoked, and the term argument refers to the specific value supplied for a parameter in a particular invocation.
```cs
type MethodName (type parameter, ...)
{
// code here
return <expression>;
}
void MethodName (type parameter, ...) {
// code here
return; // if type is void return can be used to force early termiantion or can be omitted
}
```
### Expression Body Definition
```cs
type MethodName() => <expression>; // expression result type MUST match method type
```
### Arbitrary Number Of Parameter In Methods
```cs
// params keyword must be last parameter and must be an array
type MethodName (type parameter, params type[] args)
type MethodName (type param1, type param2, ...) { }
MethodName(param1: value, param2: value);
MethodName(param2: value, param1: value); // order can be any
// Named arguments, when used with positional arguments, are valid as long as they're not followed by any positional arguments, or they're used in the correct position.
Optional parameters are defined at the end of the parameter list, after any required parameters.
A default value must be one of the following types of expressions:
- a constant expression;
- an expression of the form new ValType(), where ValType is a value type, such as an enum or a struct;
- an expression of the form default(ValType), where ValType is a value type.
```cs
type MethodName (type required, type firstOptional = default_value, type secondOptioanl = default_value, ...) { }
MethodName(value1); // use defaults for optional arguments
MethodName(required: value, secondOptional: value); // use default for first optional but pass second optional
```
**NOTE**: If the caller provides an argument for any one of a succession of optional parameters, it must provide arguments for all preceding optional parameters. Comma-separated gaps in the argument list are not supported.
### Passing Values By Reference (`ref`, `out`, `in`)
The `out`, `in`, `ref` keywords cause arguments to be _passed by reference_. It makes the _formal parameter_ an alias for the argument, which must be a variable.
An argument that is passed to a `ref` or `in` parameter **must be initialized** before it is passed. However `in` arguments _cannot be modified_ by the called method.
Variables passed as `out` arguments do not have to be initialized before being passed in a method call. However, the called method is **required to assign a value** before the method returns.
Use cases:
-`out`: return multiple values from a method (move data into method)
-`ref`: move data bidirectionally between method and call scope
-`in`: pass large value type (e,g, struct) as a reference avoiding copying large amounts of data (must be readonly, copied regardless otherwise)
**NOTE**: use `in` only with readonly value types, because mutable value types can undo the performance benefits. (Mutable value types are typically a bad idea in any case.)
But if a reference type argument is marked with ref, the method has access to the variable, so it could replace it with a reference to a completely different object.
```cs
// method declaration
type MethodName (type param1, ref type param2, out type param3, in type param4, ...)
{
// code here
}
// method call needs REF & OUT keywords, IN keyword is optinal (pass by reference regardless)
MethodName(arg1, ref arg2, out arg3, in arg4);
MethodName(arg1, ref arg2, out arg3, arg4);
type OutMethod(type param1, out type param2){}
OutMethod(arg1, out var arg2); // create out variable on the fly
```
<!-- TODO: ### References to variables
**Constraints**:
```cs
string _string = null; // init string object
ref string referenceToString = ref _string; // referenceToString points to _string, it's a reference
referenceToString = "value"; // data goes through referenceToString and into _string
``` -->
### Returning Multiple Values with Tuples
**Must** be C# 7+.
The retuned tuple MUST match the tuple-type in the intestation
```cs
(type returnedVar1, type returnedVar2, ...) MethodName (type prameter, ...)
It’s just anillusion maintained by the C# compiler, one that it keeps up even in situations where method invocation happens implicitly.
**NOTE**: Extension Method can be declared only inside static classes. Extension methods are avaiable only if their nemaespce is imported with the `using` keyword.
```cs
public static class ExtensionMethods
{
type ExtensionMethod(this type param)
{
// code here
}
}
type var = value;
var.ExtensionMethod(); // use the method on a object as if the method belongs to the object
An iterator method or `get` accessor performs a custom iteration over a collection. An iterator method uses the `yield return` statement to return each element one at a time.
When a `yield return` statement is reached, the current location in code is remembered. Execution is restarted from that location the next time the iterator function is called.
It's possible to use a `yield break` statement or exception to end the iteration.
**NOTE**: Since an iteartor returns an `IEnumerable<T>` is can be used to implement a `GetEnumerator()`.
```cs
// simple iterator
public static System.Collections.IEnumerable<int> IterateRange(int start = 0, int end)
{
for(int i = start; i <end;i++){
yield return i;
}
}
```
---
## Structs (Custom Value Types) & Classes (Custom Reference Types)
**Structure** types have _value semantics_. That is, a variable of a structure type contains an _instance_ of the type.
**Class** types have _reference semantics_. That is, a variable of a class type contains a _reference to an instance_ of the type, not the instance itself.
Typically, you use structure types to design small data-centric types that provide little or no behavior. If you're focused on the behavior of a type, consider defining a class.
Creating a new instance of a value type doesn’t necessarily mean allocating more memory, whereas with reference types, a new instance means anew heap block.
This is why it’s OK for each operation performed with a value type to produce a new instance.
The most important question is : does the identity of an instance matter? In otherwords, is the distinction between one object and another object important?
private // not visible outside of the class (default for members)
protected // visible only to the same class and extending classes
internal // available for use only within the assembly (default for classes)
protected internal // can be accessed by any code in the assembly in which it's declared, or from within a derived class in another assembly
private protected // can be accessed only within its declaring assembly, by code in the same class or in a type that is derived from that class
readonly // value can be read but not modified
static // not of the instance of a class
sealed // cannot be inherited or overridden (dafault case), sealing a virtual class/method prevents further modifications (on methods sealed must always be used with override)
abstract // derived classes MUST implement this
virtual // can be overridden by derived classes (applicable to Properties)
new // hide base's (parent's) method
async // method, lambda expression, or anonymous method is asynchronous
volatile // field might be modified by multiple threads that are executing at the same time
unsafe // unsafe context, required for any operation involving pointers
extern // method is implemented externally
```
`partial` indicates that other parts of the class, struct, or interface can be defined in the namespace.
All the parts must use the partial keyword.
All the parts must be available at compile time to form the final type.
All the parts must have the same accessibility.
If any part is declared abstract, then the whole type is considered abstract.
If any part is declared sealed, then the whole type is considered sealed.
If any part declares a base type, then the whole type inherits that class.
A _property_ is a member that provides a flexible mechanism to read, write, or compute the value of a private field.
The `static` keyword declares that a member is not associated with any particular instance of the class.
```cs
class Class
{
// if static contructor exists the initializer is runned immediately before the static constuctor,
// otherwise is will run no later than the first acces to one on the type's fileds or methods
public static type Field = value; // static (non-instance) public field w/ initializer
// runs before instance's constructor
private type Field = value; // private instance field w/ initializer
private type _field; // private instance field, initialized by consturctor
// static constructor, not called explicitly, has no arguments
// triggered by one of two events, whichever occurs first: creating an instance, or accessing any staticmember of the class.
// since its static and takes no arguments there can be at most one for each class
static Class(){
// place to init static fields
}
// class constructor
public Class(type parameter) {
_field = parameter;
}
// extends an existing constructor adding parameters to the existing ones
public Class(type anotherParametr, type parameter) : this(parameter)
{
this._anotherField = anotherParameter;
}
// called by Console.WriteLine(obj)
public override string ToString(){
return <string>
}
static type Method(arguments) {} // static method, can operate on STATIC VARIABLES
type Method(arguments) {} // instance method, can ONLY operate on INSTANCE VARIABLES
}
```
**NOTE**: creating at least one constructor hides the one provided by default (w/ zero parameters).
### [Object and Collection Initializers](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/object-and-collection-initializers)
**Object initializers** allow to assign values to any accessible fields or properties of an object at creation time without having to invoke a constructor followed by lines of assignment statements.
public Property { get; } // effectively read-only ever without keyword, can only be setted by constructor
// MIXED
public type Property
{
get => field;
set => { ... }
}
Property = value; // set
Property; // get
}
```
### Init-Only Properties
The `init` accessor is a variant of the `set` accessor which can only be called during object initialization.
Because `init` accessors can only be called during initialization, they are allowed to *mutate*`readonly` fields of the enclosing class, just like in a constructor.
```cs
public class ClassName
{
private readonly Type field;
public Type Property
{
get => field;
init => field (value ?? throw new ArgumentNullException(nameof(field)));
Use the `abstract` modifier in a class declaration to indicate that a class is intended only to be a base class of other classes, not instantiated on its own.
Members marked as `abstract` must be implemented by non-abstract classes that derive from the abstract class.
`abstract` classes have the following features:
- An `abstract` class cannot be instantiated.
- An `abstract` class may contain `abstract` methods and accessors.
- It is not possible to modify an `abstract` class with the `sealed` modifier because the two modifiers have opposite meanings.
The `sealed` modifier prevents a class from being inherited and the `abstract` modifier requires a class to be inherited.
- A *non-abstract* class derived from an `abstract` class must include actual implementations of all inherited `abstract` methods and accessors.
**NOTE**: Use the `abstract` modifier in a method or property declaration to indicate that the method or property does not contain implementation.
`abstract` methods have the following features:
- An `abstract` method is implicitly a `virtual` method.
-`abstract` method declarations are only permitted in `abstract` classes.
- Because an `abstract` method declaration provides no actual implementation, there is no method body; the method declaration simply ends with a semicolon and there are no curly braces following the signature.
- The implementation is provided by a method *override*, which is a member of a non-abstract class.
- It is an error to use the `static` or `virtual` modifiers in an `abstract` method declaration.
`abstract` properties behave like `abstract` methods, except for the differences in declaration and invocation syntax.
- It is an error to use the `abstract` modifier on a `static` property.
- An `abstract` inherited property can be overridden in a derived class by including a property declaration that uses the `override` modifier.
```cs
public abstract class Abstract : Interface
{
public abstract Type Property { get; set; }
// interface methods can be mapped to abstract methods
public abstract Type Mehod();
public abstract override Type Method(); // force overriding (derived classes must provide new implemenation)
}
public class Derived : Abstract
{
public override Type Propery
{
// new behaviour
get => <expr>;
set => <expr>;
}
public override Type Mehod() { /* stetements */ } // implementation of abstract method
}
```
### Cloning
```cs
Class obj = new Class()
Object.MemberwiseClone(); // Returns shallow copy of the object
IClonable.Clone(); // Creates a new object that is a copy of the current instance.
```
### Deconstruction
Deconstruction is not limited to tuples. By providing a `Deconstruct(...)` method(s) C# allows to use the same syntax with the users types.
**NOTE**: Types with a deconstructor can also use _positional pattern matching_.
```cs
public readonly struct Size
{
public Size(double w, double h)
{
W = w;
H = h;
}
public void Deconstruct(out double w, out double h)
{
w = W;
h = H;
}
public double W { get; }
public double H { get; }
}
// deconstruction
static double DiagonalLength(Size s)
{
(double w, double h) = s; // w = 1, h = 2
return Math.Sqrt(w * w + h * h);
}
// positional patter matching
static string DescribeSize(Size s) => s switch
{
(0, 0) => "Empty",
(0, _) => "Extremely narrow",
(double w, 0) => $"Extremely short, and this wide: {w}",
Size _ => "Normal",
_ => "Not a shape"
};
```
---
## Operator Overloading
A user-defined type can overload a predefined C# operator. That is, a type can provide the custom implementation of an operation in case one or both of the operands are of that type.
Use the operator keyword to declare an operator. An operator declaration must satisfy the following rules:
- It includes both a public and a static modifier.
- A unary operator has one input parameter. A binary operator has two input parameters.
In each case, at least one parameter must have type `T` or `T?` where `T` is the type that contains the operator declaration.
A type defined at _global scope_ can be only `public`or `internal`.
private wouldn't make sense since that makes something accessible only from within its containing type, and there is no containing type at global scope.
But a nested type does have a containing type, so if a nested type is `private`, that type can be used only from inside the type within which it is nested.
**NOTE**: Code in a nested type is allowed to use nonpublic members of its containing type. However, an instance of a nested type does not automatically get a reference to an instance of its containing type.
**NOTE**: Interfaces are reference types. Despite this, it's possible tp implement interfaces on both classes and structs.
However, be careful when doing so with a struct, because when getting hold of an interface-typed reference to a struct, it will be a reference to a _box_,
which is effectively an object that holds a copy of a struct in a way that can be referred to via a reference.
One reason for this is that value types are not normally used by reference, which removes one of the main benefits of inheritance: runtime polymorphism.
Since a derived class inherits everything the base class has—all its fields, methods, and other members, both public and private—an instance of the derived class can doanything an instance of the base could do.
**NOTE**: When deriving from a class, it's not possible to make the derived class more visible than its base. This restriction does not apply to interfaces.
A `public` class is free to implement `internal` or `private` interfaces. However, it does apply to an interface’s bases: a `public` interface cannot derive from an `internal` interface.
```cs
class BaseClass
{
public virtual Propery { get; set; }
// to be overridden method must be ABSTRACT or VIRTUAL
public virtual Type Method() { }
}
// the base class is ALWAYS the first after the colons
class ChildClass : BaseClass, Interface, Interface<Type>
{
public override Type Method() { } // override base's method (same signature)
public override DerivedType Method() { } // override base's method, can return more specific type (covariant return type, C# 9)
public new Type Method() {} // hide base's method and prevent name conflict warning (hiding method can change signature)
base.Method(); // call base method
type Interface.Method() { } // explicit implementation of an interface member (resolve name conflict between interfaces)
}
```
### Downcasting
Downcasting is the conversion from a base class type to one of it's derived types.
```cs
Base b;
var d = (Derived) b; // explicit casting (if conversion fails throws InvalidCastException)
var d = b as Derived; // as operator (if conversion fails AS will return NULL)
if(b is Derived d) {} // type pattern, d contains converted obj (if conversion fails IS returns FALSE)
if(b is Derived) {} // simple type pattern (if conversion fails IS returns FALSE)
All of a base class’s constructors are available to aderived type, but they can be invoked only by constructors in the derived class.
All constructors are required to invoke a constructor on their base class, and if it's not specified which to invoke, the compiler invokes the base’s zero-argument constructor.
If the base has not a zero-argument constructor the compilation will cause an error. It's possible to invoke a base constructor explicitly to avoid this error.
Initializaton order:
1. Derived class field initializers
2. Base class field initializers
3. Base class constructor
4. Derived class constructor
```cs
public class Base
{
public Base(Type param) {}
}
public class Derived
{
public Derived() : base(value) {} // invoke base constructor explicitly passing a fixed value (base has no zero-arg consturctor)
public Derived(Type param) : base(param) {} // invoke base constructor explicitly
public class NonGenericDerived : GenericBase1<Type> {} // derived is not generc, must use concrete type for base class
public class GenericDerived<T> : GenericBase1<T> {} // derived is generc, can use it's generic type
public class MixedDerived<T> : GenericBase2<T,Type> // derived is generc but base has two types, can use it's generic type but
```
It's allowed to use derived type as a type argument to the base class. And it's also possible to specify a constraint on a type argument requiring it to derive from the derived type.
```cs
public class Derived : base<Derived> {}
public class Derived<T> where T : Derived<T>
```
### Covariance & Contravariance (only for interfaces)
[The theory behind covariance and contravariance in C#](http://tomasp.net/blog/variance-explained.aspx/)
**Covariance** and **Contravariance** are terms that refer to the ability to use a more derived type (more specific) or a less derived type (less specific) than originally specified.
Generic type parameters support covariance and contravariance to provide greater flexibility in assigning and using generic types.
- **Covariance**: Enables to use a more derived type than originally specified.
- **Contravariance**: Enables to use a more generic (less derived) type than originally specified.
- **Invariance**: it's posible to use _only_ the type originally specified; so an invariant generic type parameter is neither covariant nor contravariant.
**NOTE**: annotate generic type parameters with `out` and `in` annotations to specify whether they should behave covariantly or contravariantly.
```cs
public class Base {};
public class Derived : Base {}
// COVARIANCE (supply more specific type)
// method is "read only" since it does not modify its argument
// IEnumerable is covariant (has out parameter) since only "provides" objects
void PrintBase(IEnumerable<Base> bases)
{
foreach(Base base in bases)
{
Console.WritLine(base);
}
}
IEnumerable<Derived> derivedItems = new Derived[] {...}; // array is enumerable of Derived objects
Method(derivedItems); // valid since Derived objects are also Base objects and operation is read only
// CONTRAVARIANCE (supply less specific type)
// IComparer is contravariant (has in parameter) since "takes in" objects
void CompareDerived(IComparer<Derived> comparer)
{
var d1 = new Derived();
var d2 = new Derived();
if(comparer.Compare(d1, d2)) { /* some action */ }
}
IComparator<Base> baseComparator = new BaseComparator();
CompareDericed(baseComparator); // valid since baseComparator can compare Base objects and thus can compare Derived objects
A **delegate** is a type that represents a _reference to a method_ with a particular parameter list and return type. Delegates are used to pass methods as arguments to other methods.
Any method from any accessible class or struct that matches the delegate type can be assigned to the delegate. The method can be either static or an instance method.
Subtraction of a multicast delegate succeeds only if the delegate from which subtract contains all of the methods in the delegate being subtracted _sequentially and in the same order_.
Delegate types do not derive from one another. Any delegate type defined in C# will derive directly from `MulticastDelegate`.
However, the type system supports certain implicit reference conversions for generic delegate types through covariance and contravariance. The rules are very similar to those for interfaces.
Structs and classes can declare events. This kind of member enables a type to provide notifications when interesting things happen, using a subscription-based model.
The class who raises events is called _Publisher_, and the class who receives the notification is called _Subscriber_. There can be multiple subscribers of a single event.
Typically, a publisher raises an event when some action occurred. The subscribers, who are interested in getting a notification when an action occurred, should register with an event and handle it.
```cs
public class Publisher
{
public event Delegate<Type> Event;
// A derived class should always call the On<EventName> method of the base class to ensure that registered delegates receive the event.
The `EventHandler` delegate is used for all events that do not include event data, the `EventHandler<TEventArgs>` delegate is used for events that include data to be sent to handlers.
Occasionally, an assembly will be split into multiple files, but even then it is an indivisible unit of deployment: it has to be wholly available to the runtime, or not at all.
Assemblies are an important aspect of the type system, because each type is identified not just by its *name* and *namespace*, but also by its containing *assembly*.
Assemblies provide a kind of encapsulation that operatesat a larger scale than individual types, thanks to the `internal` accessibility specifier, which works at the assembly level.
To ensure that the loader can find the right components, assemblies have structured names that include version information, and they can optionally contain a globally unique element to prevent ambiguity.
### Anatomy of an Assembly
Assemblies use the **Win32 Portable Executable** (PE) file format, the same format that executables (EXEs) and dynamic link libraries (DLLs) have always used in "modern" (since NT) versions of Windows.
The CLR essentially uses PE files as containers for a .NET-specific data format, so to classic Win32 tools, a C# DLL will not appear to export any APIs.
They also generate an executable file too, but it’s not a .NET assembly. It’s just a bootstrapper that starts theruntime and then loads and executes your application’s main assembly.
**NOTE**: C# compiles to a binary intermediate language (IL), which is not directly executable.
The normal Windows mechanisms for loading and running the code in an executable or DLL won’t work with IL, because that can run only with the help of the CLR.
As well as containing the compiled IL, an assembly contains metadata, which provides a full description of all of the types it defines, whether `public` or `private`.
The CLR needs to have complete knowledge of all the types that the code uses to be able to make sense of the IL and turn it into running code, the binary format for IL frequently refers to the containing assembly’s metadata and is meaningless without it.
It's possible to embed binary resources in a DLL alongside the code and metadata. To embed a file select "Embedded Rersource" as it's *Build Action* in the file prperties.
This compiles a copy of the file into the assembly.
It was possible to split the code and metadata across multiple modules, and it was also possible for some binary streams that are logically embedded in an assembly to be put in separate files.
With a multifile assembly, there’s always one master file that represents the assembly. This will be a PE file, and it contains a particular element of the metadata called the **assembly manifest**.
This is not to be confused with the Win32-style manifest that most executables contain.
The assembly manifest is just a description of what’s in the assembly, including a list of any external modules or other external files; in a multimodule assembly, the manifest describes which types are defined in which files.
### Assembly Resolution
When the runtime needs to load an assembly, it goes through a process called *assembly resolution*.
.NET Core supports two deployment options for applications:
When building this way, assembly resolution is pretty straightforward because everything ends up in one folder.
There are two main advantages to self-contained deployment:
- there is no need to install .NET on target machines
- it's known exactly what version of .NET and which versions of all DLLs are running
With self-contained deployment, unless the application directs the CLR to look elsewhere everything willload from the application folder, including all assemblies built into .NET.
The default build behavior for applications is to create a framework-dependent executable. In this case, the code relies on a suitable version of .NET Core already being installed on the machine.
The chosen runtime version selects not just the CLR, but also the assemblies making up the parts of the class library built into .NET.
### Assembly Names
Assembly names are structured. They always include a **simple name**, which is the name by which normally refer to the DLL.
This is usually the same as the filename but without the extension. It doesn’t technically have to be but the assembly resolution mechanism assumes that it is.
Assembly names always include a **version number**. There are also some optional components, including **the public key token**, a string of *hexadecimal digits*, which is required to have a unique name.
#### Strong Names
If an assembly’s name includes a public key token, it is said to be a **strong name**. Microsoft advises that any .NET component that is published for shared use (e.g: made available via NuGet) should have a strong name.
As the terminology suggests, an assembly name’s public key token has a connection with cryptography. It is the hexadecimal representation of a 64-bit hash of a publickey.
Strongly named assemblies are required to contain a copy of the full public keyfrom which the hash was generated.
The assembly file format also provides space fora digital signature, generated with the corresponding private key.
The uniqueness of a strong name relies on the fact that key generation systems use cryptographically secure random-number generators, and the chances of two people generating two key pairs with the same public key token are vanishingly small.
The assurance that the assembly has ot been tampered with comes from the fact thatastrongly named assembly must be signed, and only someone in possession of the private key can generate a valid signature. Any attempt to modify the assembly aftersigning it will invalidate the signature.
The binary format that IL uses for assembly names and references limits the range of these numbers, each part must fit in a 16-bit unsigned integer (a `ushort`), and the highest allowable value in a version part is actually one less than the maximum value that would fit, making the highest legal version number `65534.65534.65534.65534`.
As far as the CLR is concerned, there’s really only one interesting thing you can do with a version number, which is to compare it with some otherversion number, either they match or one is higher than the other.
The build system tells the compiler which version number to use for the assembly name via an assembly-level attribute.
**NOTE**: NuGet packages also have version numbers, and these do not need to be connected in any way to assembly versions. NuGet does treat the components of a package version number as having particular significance: it has adopted the widely used *semantic versioning* rules.
This is not optional, although the most common value for this is the default `neutral`, indicating that the assembly contains no culture-specific code or data.
The culture is usually set to something else only on assemblies that containculture-specific resources. The culture of an assembly’s name is designed to support localization of resources such as images and strings.
The CLR knows a great deal about the types the programs define and use. It requires all assemblies to provide detailed metadata, describing each member of every type, including private implementation details.
It relies on this information to perform critical functions, such as JIT compilation and garbage collection. However, it does not keep this knowledge to itself.
The **reflection API** grants access to this detailed type information, so the code can discover everything that the runtime can see.
Reflection is particularly useful in extensible frameworks, because they can use it to adapt their behavior at runtime based on the structure of the code.
The reflection API defines various classes in the `System.Reflection` namespace. These classes have a structural relationship that mirrors the way that assemblies and the type system work.
`GetCallingAssembly` walks up the stack by one level, and returns the assembly containing the code that called the method that called `GetCallingAssembly`.
This loads the assembly in such a way that it's poossible to inspect its type information, but no code in the assembly will execute, nor will any assemblies it depends on be loaded automatically.
Attributes can be applied to numerous different kinds of targets.
Specifically, it's possible to apply attributes to *assemblies*, *modules*, *types*, *methods*, *method parameters*, *constructors*, *fields*, *properties*, *events*, and *generic type parameters*.
Since assemblies or modules don't have a single feature that represents them, attributes are applied by stating explicitly he target at the start the attribute.
It's possible to put assembly-level attributes in any file. The sole restriction is that they must appear before any namespace or type definitions.
The only things that should comebefore assembly-level attributes are whichever using directives are needed, comments, and whitespace (all of which are optional).
Methods’ return values can be annotated, and this also requires qualification, because return value attributes go in front of the method, the same place as attributes that apply to the method itself.
The various targets of attribute have a reflection type representing them (`MethodInfo`, `PropertyInfo`, ...) which all implement the interface `ICustomAttributeProvider`.
A .NET **stream** is simply a _sequence of bytes_. That makes a stream a useful abstraction for many commonly encountered features such as a file on disk, or the body of an HTTP response.
Some streams are _read-only_. For example, if input stream for a console app represents the keyboard or the output of some other program, there’s no meaningful way for the program to write to that stream.
Some streams are _write-only_, such as the output stream of a console application.
The `Read` method returns an `int`. This tells how many bytes were read from the stream, the method _does not guarantee_ to provide the amount of data requested.
The reason `Read` is slightly tricky is that some streams are live, representing a source of information that produces data gradually as the program runs.
**NOTE**: If asked for more than one byte at a time, a `Stream` is always free to return less data than requested from Read for any reason. Never presume that a call to `Read` returned as much data as it could.
Streams automatically update their current position each time a read or write operation is completed. The `Position` property can be set to move to the desired location.
This is not guaranteed to work because it's not always possible to support it. Some streams will throw `NotSupportedException` when trying to set the `Position` property.
When a call to `Write` returns, all that is known is that it has copied the data _somewhere_; but that might be a buffer in memory, not the final target.
The Stream class therefore offers a `Flush` method. This tells the stream that it has to do whatever work is required to ensure that any buffered data is written to its target, even if that means making suboptimal use of the buffer.
A stream automatically flushes its contents when calling `Dispose`. Flush only when ity's needed to keep a stream open after writing out buffered data.
**NOTE**: When using a `FileStream`, the `Flush` method does not necessarily guarantee that the data being flushed has made it to disk yet. It merely makes the stream pass the data to the OS.
Before calling `Flush`, the OS hasn’t even seen the data, so if the process terminates suddenly, the data would be lost.
After `Flush` has returned, the OS has everything the code has written, so the process could be terminated without loss of data.
However, the OS may perform additional buffering of its own, so if the power fails before the OS gets around to writing everything to disk, the data will still be lost.
To guarantee that data has been written persistently (rather than merely ensuring that it has been handed it to the OS), use either the `WriteThrough` flag, or call the `Flush` overload that takes a bool, passing `true` to force flushing to disk.
It's possible to constructing them by passing a `Stream` as a constructor argument, or a string containing the path of a file, in which case they will automatically construct a `FileStream` and then wrap that.
The `StringReader` and `StringWriter` classes serve a similar purpose to `MemoryStream`: they are useful when working with an API that requires either a `TextReader` or `TextWriter` (abstract text streams), but you want to work entirely in memory.
Whereas `MemoryStream` presents a Stream API on top of a `byte[]` array, `StringReader` wraps a string as a `TextReader`, while `StringWriter` presents a `TextWriter` API on top of a `StringBuilder`.
### [FileStream](https://docs.microsoft.com/en-us/dotnet/api/system.io.filestream) Class (Binary Files)
The `FileStream` class derives from `Stream` and represents a file from the filesystem.
It' common to use the constructors in which the `FileStream` uses OS APIs to create the file handle. It's possible to provide varying levels of detail on how this si to be done.
At a minimum the file’s path and a value from the `FileMode` enumeration must be provided.
```cs
// overloaded FileStream Constructors
public FileStream(string path, FileMode mode);
public FileStream(string path, FileMode mode, FileAccess access);
public FileStream(string path, FileMode mode, FileAccess access, FileShare share);
public FileStream(string path, FileMode mode, FileAccess access, FileShare share, int bufferSize);
public FileStream(string path, FileMode mode, FileAccess access, FileShare share, int bufferSize, bool useAsync);
public FileStream(string path, FileMode mode, FileAccess access, FileShare share, int bufferSize, FileOptions options);
```
| `FileMode` | Behavior if file exists | Behavior if file does not exist |
| `Append` | Opens existing file, setting Position to end of file | Creates new file |
**`FileAccess` Enumeration**:
-`Read`: Read access to the file. Data can be read from the file. Combine with Write for read/write access.
-`Write`: Write access to the file. Data can be written to the file. Combine with Read for read/write access.
-`ReadWrite`: Read and write access to the file. Data can be written to and read from the file.
**`FileShare` Enumeration**:
-`Delete`: Allows subsequent deleting of a file.
-`None`: Declines sharing of the current file. Any request to open the file (by this process or another process) will fail until the file is closed.
-`Read`: Allows subsequent opening of the file for reading. If this flag is not specified, any request to open the file for reading (by this process or another process) will fail until the file is closed. However, even if this flag is specified, additional permissions might still be needed to access the file.
-`ReadWrite`: Allows subsequent opening of the file for reading or writing. If this flag is not specified, any request to open the file for reading or writing (by this process or another process) will fail until the file is closed. However, even if this flag is specified, additional permissions might still be needed to access the file.
-`Write`: Allows subsequent opening of the file for writing. If this flag is not specified, any request to open the file for writing (by this process or another process) will fail until the file is closed. However, even if this flag is specified, additional permissions might still be needed to access the file.
**`FileOptions` Enumeration**:
-`WriteThrough`: Disables OS write buffering so data goes straight to disk when you flush the stream.
-`AsynchronousSpecifies`: the use of asynchronous I/O.
-`RandomAccessHints`: to filesystem cache that you will be seeking, not reading or writing data in order.
-`SequentialScanHints`: to filesystem cache that you will be reading or writing data in order.
-`DeleteOnCloseTells`: `FileStream` to delete the file when you call `Dispose`.
-`EncryptedEncrypts`: the file so that its contents cannot be read by other users.
**NOTE**: The `WriteThrough` flag will ensure that when the stream is disposed or flushed, all the data written will have been delivered to the drive, but the drive will not necessarily have written that data persistently (drives can defer writing for performance), so data loss id still possible if the power fails.
```cs
// object to read or write to a file (file can be binary)
{
using(FileStream fstream = new FileStream(path, FileMode.OpenOrCreate, FileAcess.ReadWrite))
{
// operations on filestream
}
}
```
### [File](https://docs.microsoft.com/en-us/dotnet/api/system.io.file) Class
The static `File` class provides methods for performing various operations on files.
```cs
File.Create(string path); // Return Read/Write FileStream to file
File.Open(string path, System.IO.FileMode mode); // Open a FileStream on the specified path with read/write access with no sharing.
File.Open(string path, System.IO.FileMode mode, System.IO.FileAccess access); // Opens a FileStream on the specified path, with the specified mode and access with no sharing.
File.OpenRead(string path); // Open an existing file for reading, returns a FileStream
File.OpenText(string path); // Open an existing UTF-8 encoded text file for reading, returns a StreamReader
File.OpenWrite(string path); // Open an existing file for writing, returns a FileStream
File.Delete(string path); // Delete the specified file
File.Move(string sourceFileName, string destFileName, bool overwrite); // Move specified file to a new location (can specify a new filename and to overwrite the destination file if it already exists)
File.Exists(string path); // Whether the specified file exists.
File.GetCreationTime(string path); // Return DateTime set to the creation date and time for the specified file
File.GetLastAccessTime(string path); // Return DateTime set to the date and time that the specified file was last accessed
File.GetLastWriteTime(string path); // Return DateTime set to the date and time that the specified file was last written to
File.GetAttributes(string path); // Return FileAttributes of the file
File.Encrypt(string path); // Encrypt a file so that only the account used to encrypt the file can decrypt it.
File.Decrypt(string path); // Decrypt a file that was encrypted by the current account using the Encrypt() method.
File.ReadAllText(string path); // Return a string containing all the text in the file
File.ReadAllLines(string path); // Returns a string[] containing all lines of the file
File.ReadLines(string path); // Returns IEnumerable<string> containing all the text in the file
File.ReadAllBytes(string path); // Returns a byte[] containing the contents of the file.
File.WriteAllLines(string path, IEnumerable<string> contents); // writes a collection of strings to the file
File.WriteAllLines(string path, string[] contents); // writes a collection of strings to the file
File.AppendAllText(string path, string contents); // appends the specified string to the file
File.AppendAllLines(string path, IEnumerable<string> contents); // appends a collection of strings to the file
// Replace the contents of a specified file with the contents of another file, deleting the original file, and creating a backup of the replaced file.
### [Directory](https://docs.microsoft.com/en-us/dotnet/api/system.io.directory) Class
Exposes static methods for creating, moving, and enumerating through directories and subdirectories.
```cs
Directory.CreateDirectory(string path); // Create directory as specified
Directory.Delete(string path); // Delete an empty directory from a specified path (dir must be writable)
Directory.Delete(string path, bool recursive); // Delete the specified directory and, if indicated, any subdirectories and files in the directory
Directory.Move(string sourceDirName, string destDirName); // Move a file or a directory and its contents to a new location
Directory.Exists (string path); // Whether the given path refers to an existing directory on disk
Directory.GetLogicalDrives(); // string[] of names of the logical drives on the computer in the form "<driveletter>:\"
Directory.GetParent(string path); // DirectoryInfo of parent directory of the specified path, including both absolute and relative paths
Directory.GetCurrentDirectory(); // string of current working directory of the application
Directory.SetCurrentDirectory(string path); // Set the application's current working directory to the specified directory
Directory.GetCreationTime(string path); // DateTime set to the creation date and time for the specified directory
Directory.GetLastAccessTime(string path); // DateTime set to the date and time the specified file or directory was last accessed
Directory.GetLastWriteTime(string path); // DateTime set to the date and time the specified file or directory was last written to
Directory.EnumerateDirectories (string path, string searchPattern, SearchOption searchOption); // IEnumerable<string> of directory full names that match a search pattern in a specified path
Directory.GetDirectories (string path, string searchPattern, System.IO.SearchOption searchOption); // string[] of directory full names that match a search pattern in a specified path
Directory.EnumerateFiles(string path, string searchPattern, SearchOption searchOption); // IEnumerable<string> of full file names that match a search pattern in a specified path
Directory.GetFiles(string path, string searchPattern, SearchOption searchOption); // string[] of full file names that match a search pattern in a specified path
Directory.EnumerateFileSystemEntries(string path, string searchPattern, SearchOption searchOption); // IEnumerable<string> array of file names and directory names that match a search pattern in a specified path
Directory.GetFileSystemEntries (string path, string searchPattern, SearchOption searchOption); // string[] array of file names and directory names that match a search pattern in a specified path
```
### [Path](https://docs.microsoft.com/en-us/dotnet/api/system.io.path) Class
```cs
Combine(string path1, string path2); // Combine two strings into a path
Combine(string[] paths); // Combine strings into a path
GetFullPath(string path); // absolute path for the specified path string
GetFullPath(string path, string basePath); // absolute path from a relative path and a fully qualified base path
GetRelativePath (string relativeTo, string path); // relative path from one path to another
GetPathRoot (string path); // Get the root directory information from the path contained in the specified string
GetDirectoryName (string path); // directory information for the specified path string
GetExtension (string path); // extension (including the period ".") of the specified path string
GetFileName (string path); // file name and extension of the specified path string
GetFileNameWithoutExtension (string path); // file name of the specified path string without the extension
HasExtension (string path); // whether a path includes a file name extension
IsPathFullyQualified (string path); // whether the specified file path is fixed to a specific drive or UNC path
IsPathRooted (string path); // whether the specified path string contains a root
EndsInDirectorySeparator (string path); // true if the path ends in a directory separator; otherwise, false
TrimEndingDirectorySeparator (string path); // Trim one trailing directory separator beyond the root of the specified path
GetInvalidFileNameChar(); // char[] containing the characters that are not allowed in file names
GetInvalidPathChars(); // char[] containing the characters that are not allowed in path names
GetTempPath(); // path of the current user's temporary folder
GetTempFileName(); // Create a uniquely named, zero-byte temporary file on disk and returns the full path of that file
GetRandomFileName(); // random folder name or file name
// get full path from relative
string path = Path.Combine(Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location), @"relative_path.ext"); // path to a file in the project directory
Classes to hold multiple info about a file or directory. If some property changes usig the method `Refresh()` will update the data.
### CLR Serialization
Types are required to opt into CLR serialization. .NET defines a [Serializable] attribute that must be present before the CLR will serialize the type (class).
```cs
[Serializable]
class ClassName{
// class contents
}
```
Serialization works directly with an object’s fields. It uses reflection, which enables it to access all members, whether public or private.
**NOTE**: CLR Serialization produces binary streams in a .NET specific format
match.Groups[index].Captures; // list of string in the matched group
match.Groups[index].Index; // position in the input string of the matched group
```
---
## Unit Testing
[Microsoft Unit Testing Tutorial](https://docs.microsoft.com/en-us/visualstudio/test/walkthrough-creating-and-running-unit-tests-for-managed-code?view=vs-2019)
To test a project add a **MSTest Test Projet** to the solution.
The test runner will execute any methods marked with `[TestInitialize]` once for every test the class contains, and will do so before running the actual test method itself.
