ycrumeyrolle / corefxlab

This repo is for experimentation and exploring new ideas that may or may not make it into the main corefx repo.

.NET Core Lab

This repo is for experimentation and exploring new ideas that may or may not make it into the main corefx repo.

Build & Test Status

	x64 Debug	x64 Release
Windows NT
Ubuntu 16.04
OSX 10.12

Roadmap

While this repo is meant for experimentation, we still want to focus our efforts in a particular direction, specifically to work on areas aligned with our roadmap.

The general idea is that we mature our thinking in this repo and either decide not to pursue it or that we want to productize in which case we'll eventually migrate the code to the appropriate location, usually the dotnet/corefx repository.

Of course, this doesn't mean we're not willing to explore areas that aren't part of our roadmap, but we'd prefer if these would start with a document, and not with code. This allows us to collaborate on how we want to approach specific holes or issues with our platform without being drowned in large PRs.

Components

Currently, this repo contains the following experimental components:

• System.Slices These APIs moved to System.Memory (a component in the CoreFx repo) and to System.Buffers.Primitives (a component in this repo)

• System.Buffers.Primitives A set of features for representing and manipulating managed, native buffers. The package complements Span<T> and ReadOnlySpan<T> primitives of System.Memory package. See more information about the features at span.md and memory.md.

• System.Text.Formatting. System.Text.Formatting APIs are similar to the existing StringBuilder and TextWriter APIs. They are designed to format values into text streams and to build complex strings. But these APIs are optimized for creating text for the Web. They do formatting with minimum GC heap allocations (1/6 of allocations in some scenarios) and can format directly to UTF8 streams. This can result in significant performance wins for software that does a lot of text formatting for the Web, e.g. generating HTML, JSON, XML. See more information on this component and code samples at the Wiki.

• System.Text.Primitives The System.Text.Primitives library contains fast, non-allocating integral parsing APIs. They are designed for scenarios in which a byte buffer and an index are accepted as input and a parsed value is desired as output (e.g. in a web server). These APIs present significant performance gains over converting the buffer to a string, indexing into the string, and then parsing.

• System.IO.FileSystem.Watcher.Polling. .NET's FileSystemWatcher has low overhead, but it can miss some changes. This is acceptable in many scenarios, but in some, it might be not. This component, PollingWatcher, allows to monitory directory changes by polling, and so will never miss a change. It is optimized to minimize allocations, when no changes are detected. In fact, it does not allocate anything on the GC heap when there are no changes detected.

• System.Threading.Tasks.Channels. The System.Threading.Tasks.Channels library provides a set of synchronization data structures for passing data between producers and consumers. Whereas the existing System.Threading.Tasks.Dataflow library is focused on pipelining and connecting together dataflow "blocks" which encapsulate both storage and processing, System.Threading.Tasks.Channels is focused purely on the storage aspect, with data structures used to provide the hand-offs between participants explicitly coded to use the storage. The library is designed to be used with async/await in C#. See the README.md for more information.

• System.Time. This project augments the date and time APIs in .NET. It adds two new core types: Date and TimeOfDay. It also provides extension methods to enhance the functionality of the existing DateTime, DateTimeOffset and TimeZoneInfo types.

• System.Collections.Generic.MultiValueDictionary. The MultiValueDictionary is a generic collection that functions similarly to a Dictionary<TKey, ICollection<TValue>> with some added validation and ease of use functions. It can also be compared to a Lookup with the exception that the MultiValueDictionary is mutable. It allows custom setting of the internal collections so that uniqueness of values can be chosen by specifying either a HashSet<TValue> or List<TValue>. Some of the design decisions as well as introductions to usage can be found in the old blog posts introducing it here and here.

• System.CommandLine. The purpose of this library is to make command line tools first class by providing a command line parser. Here are the goals: designed for cross-platform usage, lightweight with minimal configuration, optional but built-in support for help, validation, and response files, support for multiple commands, like version control tools. See the README.md for more information.

More libraries are coming soon. Stay tuned!

Related Projects

For an overview of all the .NET related projects, have a look at the .NET home repository.

How to Use

You can get the .NET Core Lab packages from dotnet-corefxlab MyGet feed:

https://dotnet.myget.org/F/dotnet-corefxlab/

or

https://dotnet.myget.org/F/dotnet-corefxlab/api/v3/index.json (preview support)

Symbols:

https://dotnet.myget.org/F/dotnet-corefxlab/symbols/

You can add this feed among your NuGet sources and install the packages (keep in mind that packages are pre-release packages).

License

This project is licensed under the MIT license.

.NET Foundation

This project is a part of the .NET Foundation.

There are many .NET related projects on GitHub.

• .NET home repo - links to 100s of .NET projects, from Microsoft and the community.
• ASP.NET Core home - the best place to start learning about ASP.NET Core.

Building and Testing

To build the projects in this repo, you have a few options:

• Download or install a new version of the .NET CLI for your operating system. Then, simply invoke the tool to build individual projects (dotnet restore and then dotnet build).
• (On Windows) Invoke build.cmd. This will download an acceptable version of the .NET CLI automatically and use it to build the entire repository. NOTE: Don't invoke scripts/build.ps1 directly. It requires that some environment be set in order for it to work correctly. build.cmd does this.
• (On Windows) Open the solution file in Visual Studio 2015. NOTE: This requires unreleased plugins to work at this point in time. Using VS Code, see https://aka.ms/vscclrdogfood.

Measuring Performance

For details, please refer to the PerfHarness documentation.