Repository navigation
NetWasm 0.14.0: .NET Standard libraries, the framework in the box
NetWasm 0.14.0: .NET Standard libraries, the framework in the box
NetWasm 0.14.0 is available on NuGet.org.
A netwasm0.1 project now references the whole framework, as a .NET project
references Microsoft.NETCore.App, and NuGet packages built for .NET Standard
restore and compile against it. The in-box NetWasm.System.* packages retire,
since their assemblies ship with the SDK. More of .NET's own code runs
unchanged: date and time text, floating-point formatting, cookies and
type-level attributes are upstream's. Expression trees run nested lambdas,
closures, Quote and Invoke, and .NET's feature switches fold at compile time.
The framework in the box
- Every
netwasm0.1project references NetWasm.App: NetWasm.App.Ref for
compiling and NetWasm.App.Runtime for linking, chosen by the SDK's version.
It holds the framework's assemblies beyond CoreLib (collections, LINQ,
System.Text.Json, regular expressions, System.Xml, HttpClient and the rest
of networking, compression, cryptography and more), and reference facades
such asSystem.Runtimeandnetstandard. - The compiler links only what a program reaches, so a program pays nothing
for the assemblies it does not use. System.LinqandSystem.Net.Httpare ordinary implicit usings.- Breaking: these packages retire, and the SDK prunes references to them, every
version:NetWasm.System.Data.Common,NetWasm.System.IO.Pipelines,
NetWasm.System.Linq,NetWasm.System.Linq.AsyncEnumerable,
NetWasm.System.Memory,NetWasm.System.Net.Http,
NetWasm.System.Net.Http.Json,NetWasm.System.Net.Requests,
NetWasm.System.Runtime.Serialization.Xml,
NetWasm.System.Text.Encodings.Web,NetWasm.System.Text.Json,
NetWasm.System.Text.RegularExpressionsandNetWasm.System.Xml. Their last
versions stay on NuGet.org. The SDK also prunes Microsoft's packages for
assemblies NetWasm.App provides (System.Text.Json, System.Memory and the
like), as the .NET SDK does for Microsoft.NETCore.App. - The HTTP service generator moved into the SDK, so a
serviceworld project
needs no package, and thenetwasm-serverlesstemplate has none. - Out-of-band libraries (dependency injection, logging, configuration, options,
caching,System.IO.Hashing,System.Formats.Cbor) stay separate packages,
released for 0.14.
.NET Standard libraries
- NuGet picks a package's
netwasm0.1asset when it has one, otherwise its .NET
Standard 2.1, 2.0 or earlier asset. Libraries built against .NET's reference
assemblies bind to NetWasm.App without changes. - Most unsupported operations still compile, and throw a
PlatformNotSupportedExceptionthat names the operation when they run.
.NET Standard libraries lists the families
libraries meet most often (runtime reflection, manifest resources, file
watching) and how authors avoid them. - A P/Invoke whose library no
NativeLibraryitem provides compiles to a stub
that throwsDllNotFoundExceptionwhen called, as Mono's WebAssembly build
does, and the build warns NW1017 for each one a program reaches.
Feature switches
- A project sets .NET's feature switches as on .NET: with properties such as
<InvariantGlobalization>or withRuntimeHostConfigurationOptionitems.
AppContextreads them as .NET readsruntimeconfig.json. - A switch marked
Trim="true", as every switch the SDK sets from a property
is, is also folded when the program compiles, so the code it turns off leaves
the program, as trimming removes it. Method stubs in an assembly's embedded
ILLink.Substitutions.xmlapply the same way, the framework's included:
whileEventSourceSupportis false, everyEventSource.IsEnabledcheck is
false, so event logging, a program's ownEventSourcetypes included, leaves
the program. - NetWasm's defaults keep no more than Blazor WebAssembly's, and diagnostics
are off, as in .NET's own WebAssembly runtime. UseSizeOptimizedLinqfollows the optimization preset: LINQ takes its
speed-optimized iterators atO1,O2andO3, and its size-optimized ones
otherwise, including the Release defaultOz. A project can set it either
way.- Breaking:
UseSystemResourceKeysis true unless a project sets it. NetWasm
deploys no manifest resources, so a package that formats messages from
resources reports the resource key instead of the sentence; exception types
are unchanged. - Breaking:
MetricsSupport,HttpActivityPropagationSupportand
EventSourceSupportare false. A project that wants HttpClient's distributed
tracing or metrics sets the first two to true.
Expression trees
- The interpreter runs nested lambdas that capture variables,
Quote,
Invokeof a lambda expression,Powerand lifted user-defined operators,
along with type tests and conversions, arrays, loops, labels, switches,
throws, try blocks, members of structs, statics, constructors including
New(typeof(C)), member assignment, andListInitandMemberInit. Compile()returns a delegate that interprets the tree.- Catch filters and multidimensional
NewArrayBoundsstill throw
PlatformNotSupportedException.
More of .NET's own code
DateTime,DateTimeOffset,DateOnly,TimeOnlyandTimeSpanformat
and parse with upstream's code and match .NET 11 in invariant mode. The
standard formatsd,D,f,F,m,t,T,Uandyno longer
throw, and parsing accepts what .NET 11 accepts in invariant mode.double,floatandHalfformat with upstream's Grisu3 and Dragon4, which
allocate nothing.ArrayPool<T>.SharedandArrayPool<T>.Createare .NET's pools. In a world
withoutwasi:clocks/monotonic-clock(a custom WIT world or a plain core
module), the shared pool keeps the arrays returned to it instead of releasing
them over time.- HttpClient keeps cookies whose
Set-Cookieheader has anExpires
attribute; before, they were dropped. MD5andHMACMD5are managed and pay for use, and
CryptoConfig.CreateFromNameknows the algorithms NetWasm implements.- Framework types carry the attributes upstream declares on them, such as
[Flags],[AttributeUsage],[Conditional]and[Serializable]. TypedReferenceworks:__makeref,__refvalue,__reftypeand
TypedReference.ToObject.
Fixes
- A loop whose catch handler holds a
try/finallythat continues or breaks
out of the loop compiles, insideforeachand in async methods (AWSSDK.S3's
credential refresh has this shape). Before, the build stopped withNW1014: Executing leave block N has no active structured continuation. - Branches that test a static field no code writes are folded before the
program is assembled, null tests included, so the types only those branches
reach are no longer registered in the program. - Arrays of pointers (
void*[],int*[]) compile and run. Before, the build
stopped withNW1003: type identity 'primitive:void*' does not name a type definition(#235). - A program with hundreds of P/Invokes into a native library links on Windows:
wasm-ldreads its arguments from a response file, so its command line no
longer passes Windows' 32,767-character limit.NWPACK001now says which
tool could not be started and why
(#236). - A method marked
[MethodImpl(MethodImplOptions.NoInlining)]stays a call.
Before, it could be inlined when an identical function had been merged into
it, which made benchmarks that rely on the call measure less than they ask. - A build prints when the final
wasm-optpass starts, with the module's size
and optimization level, and how long it took, so a long pass no longer looks
like a stopped build (#237).
Size and speed
- The program that prints 42 is 28,383 bytes (0.13.0: 28,377), although the
whole framework is now referenced. - With
EventSourceSupportfalse, programs that use HttpClient, sockets, DNS,
PLINQ, transactions or XML serialization no longer carry event logging. A
program that makes one HttpClient request is about 62 KB smaller than with
the logging in. - Speed matches 0.13.0: across 2,213 micro-benchmarks the geometric mean of
0.14.0's times over 0.13.0's is 1.001, with 34 benchmarks more than 5% faster.
What still throws
Marshal.GetFunctionPointerForDelegateand
GetDelegateForFunctionPointerthrowPlatformNotSupportedException; use
UnmanagedCallersOnlymethods and function pointers instead.GC.TryStartNoGCRegionand full-collection notifications throw, as Mono's
do.
Known problems
- A Release build of a large program can need a lot of memory in
wasm-opt,
which starts one thread per core. Where memory is short, set the environment
variableBINARYEN_CORES=4for the build. wasm-optcan take a very long time on a large module, at-Oz(the Release
default) most of all, and much longer on Windows than on Linux. This is in
Binaryen (binaryen#7705,
binaryen#1338). Set
<NetWasmOptimization>O2</NetWasmOptimization>for a much faster build with
a somewhat larger module, or build Release on Linux or under WSL.
Upgrading
- Remove
PackageReferenceitems for the retiredNetWasm.System.*packages.
The SDK prunes them, so a project that still has one builds against
NetWasm.App's assembly. - Update the out-of-band library packages (
NetWasm.Microsoft.Extensions.*,
NetWasm.System.IO.Hashing,NetWasm.System.Formats.Cbor) and
NetWasm.TUnitto their 0.14 releases. - Rebuild
netwasm0.1libraries against 0.14. Some public types moved out of
NetWasm.CoreLib into the assembly .NET defines them in (for example
Stack<T>,SortedDictionary<TKey, TValue>,LinkedList<T>,
PriorityQueue<TElement, TPriority>, the immutable and frozen collections and
NameValueCollection), so a library compiled against an earlier release that
uses one fails to compile into a program with NW1004. - A project that must compile against CoreLib alone sets
DisableImplicitNetWasmAppReferenceto true. - Code that matches exception messages from packages: expect resource keys, or
match on the exception's type.