After the initial excitement of .NET Core wore off (Cross platform! Open source!), we realised there were a few things missing. APIs, mostly. Oh, and compatibility with a lot of your favourite libraries and packages. Fortunately, the .NET Standard is here to fix all of this, adding back APIs, restoring compatibility and even replacing PCLs. This talk is all about the How and the Why, mixed in with a healthy dose of Why Should I Care. We'll even have a little geek out over the technical details. If type forwarding can't restore your excitement levels to fever pitch, I don’t know what will! (Slides from NDC London 2017)

2. What is the .NET Standard?
A specification defining a versioned set of APIs that
are guaranteed to be implemented by a .NET platform
If a library targets the standard, it runs on all
supporting platforms

3. Not the whole story
What APIs are included?
What are the different versions?
What about compatibility with existing frameworks and
libraries?
How does it relate to .NET Core? Portable Class Libraries?
How does it work?
What’s the deal with .NET Standard 2.0?

4. What are we trying to solve?What are we trying to solve?

5. History lesson
.NET is multiple frameworks
.NET Framework, .NET Core, Silverlight, Windows Store, Windows Phone, Xbox,
Mono, Xamarin, .NET Compact Framework, .NET Micro Framework, …
Different implementations over time
(15 years…)
API Incompatibilities

6. So how do we share libraries
across .NET implementations?

7. .NET Standard
Defines the APIs that all platforms must implement
Libraries target the specification, run on supporting
platforms

8. Isn’t that just Portable Class Libraries?
WAITWAIT
Isn’t that just Portable Class Libraries?

9. Portable Class Libraries
Libraries that target “profiles”, not frameworks
Profiles are API subsets
Intersection of targeted frameworks and versions
But, arcane - profile numbers? ¯_(ツ)_/¯
Not scalable - new APIs, versions or frameworks
require new profiles

10. .NET Standard flips the PCL model
PCLs find common ground between implementations
.NET Standard defines the minimum requirements
of an implementation

11. Libraries target the standard,
run on supporting platforms
Even NEW platforms

12. .NET Standard is a specification.NET Standard is a specification

13. Not a Word document
Binary specification - a set of reference assemblies to
compile against
Versioned NuGet package - NETStandard.Library
New versioned target framework - “netstandard”
netstandard1.x, netstandard2.0

14. Target frameworks
NuGet has Target Framework Monikers - net46,
netcoreapp1.0, win8, etc.
Depend on NuGet package, but target a version of a
framework (net46, net35, net20)
TFM decides what is referenced
Target framework specified in project settings

15. Target framework as
“platform”
.NET Framework and .NET Core are concrete platforms
Apps run on these platforms
.NET Standard is an abstract platform
Cannot run code on .NET Standard

16. Libraries target:
netstandard as an abstract platform
Run on any supporting concrete platform
Concrete platforms
Superset of .NET Standard, with platform specific APIs
Apps target:
Concrete platforms
Implements the abstract platform

18. VersioningVersioning

19. Versioning is additive
.NET Standard only adds APIs
No process for removing APIs
Adds assemblies, types and type members

20. 2.0
1.6
1.5
1.4
1.3
1.2
1.1
New versions are supersets of
all previous versions
Newer platforms can
consume libraries targeting
older standard versions
1.0

21. How did we get so many versions so quickly?How did we get so many versions so quickly?
WAITWAIT

22. .NET Standard introduced with .NET Core 1.0
Back ported to earlier platforms for compatibility

24. What version of .NET
Standard should I use?
A higher version will have more APIs
A lower version will have more platforms

25. Target the lowest version you can

26. API availability
github:dotnet/standard - docs/versions.md
apiport/portability analyser

28. How do APIs get added?
Review board - .NET Team, Xamarin and Unity
Platform implementers
Not everything will be added to standard
Out of band packages
Pure IL, based on .NET Standard
Criteria - ubiquitous, mature, runtime specific (SIMD)

29. Packaging the standardPackaging the standard

30. NETStandard.Library package
v1.5, v1.6, v1.6.1 - package version, not standard
version!
New TFMs - netstandard1.x, netstandard2.x
Target framework decides what version of reference
assemblies are referenced

31. Demo
NuGet Package Explorer
Package version vs TFM version
Meta-package - all in the dependencies
1.x - fine grained package dependencies

32. What about
.NET Standard 2.0?
What about
.NET Standard 2.0?

33. Work in progress - shipping with VS2017
Loads more APIs
Consolidating reference assemblies
netstandard.dll
Consolidating packages
No dependencies for NETStandard.Library

34. SAME GOALSSAME GOALS

35. “100% source and binary compatibility for
classic .NET Framework and Xamarin assemblies
and existing PCLs"
–dotnet/standard/docs/netstandard-20/README.md

36. What was wrong with 1.x?
Not enough libraries targeting .NET Standard or PCLs
Majority of NuGet packages target .NET Framework
Tightly coupled to .NET Core
Cannot evolve .NET Core separately
Not enough APIs - “API cleanup went a bit overboard”

37. Adding missing APIs
Porting applications to .NET Core was too hard
Intersection of .NET Framework and Mono/Xamarin
Platform specific APIs?
Most excluded
Some APIs included: emulate or throw at runtime

39. netstandard.dll
Single reference assembly
Contains ALL APIs
The specification is monolithic, why are the reference
assemblies fine grained?
Implications on packaging, implementation and
backwards compatibility

40. Split with .NET Core
Previously built from .NET Core source
Now has own repo - dotnet/standard
.NET Core implements standard
No longer “special”
Deprecating fine grained packages
Implications for deployment

41. How does it work?How does it work?

42. Reference assemblies
Type forwarding

43. Reference assemblies
Passed to compiler to define available APIs
Compiler error if API is missing
Compiler not interested in implementation
Reference assemblies use empty types
Empty methods, return null/default(T)

44. Implementation assemblies
Resolved at runtime
Contains the actual implementation
Must contain AT LEAST referenced types and members
Can contain more APIs

45. Assemblies in the Microsoft.NET folder are
implementation assemblies
Visual Studio uses reference assemblies to target 4.0,
4.5, 4.6.1, 4.6.2, etc.
E.g. C:Program FilesReference AssembliesMicrosoftFramework.NETFrameworkv4.5.2
.NET Standard uses reference assemblies in NuGet
package(s)

46. Assembly qualified names
Compiler embeds type reference as assembly qualified
name
E.g. System.Threading!System.Threading.Timer
Runtime uses assembly name to resolve type
How to deal with platform implementation differences?
E.g. mscorlib!System.Object, System.Runtime!System.Object

47. Type forwarding
Assembly attribute redirecting type implementation to
another assembly
[assembly: TypeForwardedTo(typeof(MyNamespace.MyType))]
Cannot rename, only redirect
Must be in same namespace
Redirects at runtime
Also redirects at compile time

48. Type forwarding
Allows referencing type in one assembly
But implementing in another
Useful for platform differences, or refactoring the
platform

49. .NET Standard
API is defined in reference assemblies included in
NuGet package
1.x libraries will reference types in System.*.dll
Each platform can type forward to implementation

50. What can reference what?

51. .NET Standard 1.x

52. References embedded
as System.*.dll
Compile time (library)

53. References embedded
as System.*.dll
no compile errors
Compile time (library)

54. References embedded
as System.*.dll
no compile errors
Compile time (library)
Possibly more APIs than .NET Standard 1.x
Microsoft.NETCore.Portable.Compatibility
package adds reference assemblies

55. NuGet understands
mapping between
platform and net
standard, e.g. net46
and netstandard1.3
Compile time (app)

56. Everything references
System.*.dll
no compile errors
Compile time (app)

57. Platform includes
System.*.dll reference
assemblies. Forward to
mscorlib.dll
No compile errors
Compile time (app)

58. .NET Core
implementation
assemblies match .NET
Standard references
Run time

59. Runtime assemblies
type forward .NET
Standard System.*.dll
references to real
implementation
Run time

60. .NET Standard 2.0

61. Types referenced as
netstandard.dll
Compile time (library)

62. For 2.0, references
match (netstandard.dll)
No compile errors
Compile time (library)

63. For 1.x, types
embedded as
System.*.dll
Compile time (library)
NETStandard.Library includes System.*.dll facades that
type forward to netstandard.dll - no compile errors

64. System.*.dll
references forwarded
to netstandard.dll
Additional package no longer necessary as types added back
Compile time (library)

65. References embedded
as mscorlib.dll
NETStandard.Library includes mscorlib.dll facade that
type forwards to netstandard.dll - no compile errors
Compile time (library)

66. References are to
netstandard.dll - no
compile error
Compile time (app)

67. Transient references to
mscorlib.dll
Compile time (app)
NETCoreApp package includes NETStandard.Library
mscorlib.dll facade forwards to netstandard.dll
- no compile errors

68. netstandard.dll
references forward to
mscorlib.dll!
Compile time (app)

69. Transient mscorlib.dll
and System.*.dll
references provided by
platform
Compile time (app)

70. Runtime
netstandard.dll
forwards to
implementation
Run time
.NET Core 2.0 includes own netstandard.dll
type forwards to real implementation

71. Requires
netstandard.dll to
forward to mscorlib.dll
Run time

72. .NET Standard 1.x can reference:
.NET Standard 1.x assembly
PCL assembly

73. .NET Standard 2.0 can reference:
.NET Standard assembly
PCL assembly
.NET Framework assembly

74. NuGet knows mapping between platforms and .NET
Standard versions
Allows referencing .NET Framework libraries
from .NET Standard platforms

75. .NET Standard
Specification for available APIs across platforms
Replacement for PCLs
2.0 is adding back APIs, adding compatibility shims

76. Links
github: dotnet/standard
@terrajobst’s videos on YouTube
http://bit.ly/netstandard_videos
myget: dotnet-core
NETStandard.Library2
@citizenmatt