Skip to content

NetWasm 0.14.0: .NET Standard libraries, the framework in the box

Choose a tag to compare

@zion-sati zion-sati released this 14 Nov 20:29
8a04dd3

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.1 project 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 as System.Runtime and netstandard.
  • The compiler links only what a program reaches, so a program pays nothing
    for the assemblies it does not use.
  • System.Linq and System.Net.Http are 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.RegularExpressions and NetWasm.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 service world project
    needs no package, and the netwasm-serverless template 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.1 asset 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
    PlatformNotSupportedException that 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 NativeLibrary item provides compiles to a stub
    that throws DllNotFoundException when 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 with RuntimeHostConfigurationOption items.
    AppContext reads them as .NET reads runtimeconfig.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.xml apply the same way, the framework's included:
    while EventSourceSupport is false, every EventSource.IsEnabled check is
    false, so event logging, a program's own EventSource types 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.
  • UseSizeOptimizedLinq follows the optimization preset: LINQ takes its
    speed-optimized iterators at O1, O2 and O3, and its size-optimized ones
    otherwise, including the Release default Oz. A project can set it either
    way.
  • Breaking: UseSystemResourceKeys is 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, HttpActivityPropagationSupport and
    EventSourceSupport are 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,
    Invoke of a lambda expression, Power and 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, and ListInit and MemberInit.
  • Compile() returns a delegate that interprets the tree.
  • Catch filters and multidimensional NewArrayBounds still throw
    PlatformNotSupportedException.

More of .NET's own code

  • DateTime, DateTimeOffset, DateOnly, TimeOnly and TimeSpan format
    and parse with upstream's code and match .NET 11 in invariant mode. The
    standard formats d, D, f, F, m, t, T, U and y no longer
    throw, and parsing accepts what .NET 11 accepts in invariant mode.
  • double, float and Half format with upstream's Grisu3 and Dragon4, which
    allocate nothing.
  • ArrayPool<T>.Shared and ArrayPool<T>.Create are .NET's pools. In a world
    without wasi: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-Cookie header has an Expires
    attribute; before, they were dropped.
  • MD5 and HMACMD5 are managed and pay for use, and
    CryptoConfig.CreateFromName knows the algorithms NetWasm implements.
  • Framework types carry the attributes upstream declares on them, such as
    [Flags], [AttributeUsage], [Conditional] and [Serializable].
  • TypedReference works: __makeref, __refvalue, __reftype and
    TypedReference.ToObject.

Fixes

  • A loop whose catch handler holds a try/finally that continues or breaks
    out of the loop compiles, inside foreach and in async methods (AWSSDK.S3's
    credential refresh has this shape). Before, the build stopped with NW1014: 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 with NW1003: 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-ld reads its arguments from a response file, so its command line no
    longer passes Windows' 32,767-character limit. NWPACK001 now 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-opt pass 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 EventSourceSupport false, 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.GetFunctionPointerForDelegate and
    GetDelegateForFunctionPointer throw PlatformNotSupportedException; use
    UnmanagedCallersOnly methods and function pointers instead.
  • GC.TryStartNoGCRegion and 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
    variable BINARYEN_CORES=4 for the build.
  • wasm-opt can 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 PackageReference items for the retired NetWasm.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.TUnit to their 0.14 releases.
  • Rebuild netwasm0.1 libraries 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
    DisableImplicitNetWasmAppReference to true.
  • Code that matches exception messages from packages: expect resource keys, or
    match on the exception's type.