What's new in .NET 8 Preview 6 [WIP]

[leecow]

What's new in .NET 8 Preview 6

This issue is for teams to highlight work for the community that will release in .NET 8 Preview 6

To add content, use a new conversation entry. The entry should include the team name and feature title as the first line shown in the template below.

Required

## Team Name: Feature title

[link to the tracking issue or epic item for the work]

Tell the story of the feature and anything the community should pay particular attention 
to be successful in using the feature.

Optional

Below are three additional items to consider. These will help the .NET 8 blog team and the community throughout the release.

• Link to documentation.
  • Where can we send people to learn more about the feature?
• Link to where you'd like people to provide feedback for this feature.
  • Where can people best comment on the direction of this feature?
• Whether you would like assistance from the .NET 8 writers to craft a story for this feature.
  • Please @JonDouglas or @JeremyLikness in your comment if so.

Index of .NET 8 releases

Preview 1: #8133
Preview 2: #8134
Preview 3: #8135
Preview 4: #8234
Preview 5: #8436
Preview 6: #8437
Preview 7: #8438
RC 1: #8439
RC 2: #8440

[vcsjones]

System.Security: SHA-3 Support

dotnet/runtime#20342

In .NET 8 Preview 6, support for the SHA-3 hashing primitives is now available on platforms that offer SHA-3. This is currently Linux with OpenSSL 1.1.1 or later, and Windows 11 Build 25324 or later.

APIs where SHA-2 is available now offer a SHA-3 compliment. This includes SHA3_256, SHA3_384, and SHA3_512 for hashing; HMACSHA3_256, HMACSHA3_384, and HMACSHA3_512 for HMAC; HashAlgorithmName.SHA3_256, HashAlgorithmName.SHA3_384, and HashAlgorithmName.SHA3_512 for hashing where the algorithm is configurable; and RSAEncryptionPadding.OaepSHA3_256, RSAEncryptionPadding.OaepSHA3_384, and RSAEncryptionPadding.OaepSHA3_512 for RSA OAEP encryption.

Using the SHA-3 APIs is similar to SHA-2, with the addition of an IsSupported property to determine if the platform offers SHA-3.

// Hashing example
// Check if SHA-3-256 is supported on the current platform.
if (SHA3_256.IsSupported)
{
    byte[] hash = SHA3_256.HashData(dataToHash);
}
else
{
    // Determine application behavior if SHA-3 is not available.
}

// Signing Example
// Check if SHA-3-256 is supported on the current platform.
if (SHA3_256.IsSupported)
{
     using ECDsa ec = ECDsa.Create(ECCurve.NamedCuves.nistP256);
     byte[] signature = ec.SignData(dataToBeSigned, HashAlgorithmName.SHA3_256);
}
else
{
    // Determine application behavior if SHA-3 is not available.
}

Additionally, SHA-3 includes two extendable-output functions (XOFs), SHAKE128 and SHAKE256. These are available as Shake128 and Shake256.

if (Shake128.IsSupported)
{
    using Shake128 shake = new Shake128();
    shake.AppendData("Hello .NET!"u8);
    byte[] digest = shake.GetHashAndReset(outputLength: 32);
    
    // Also available as a one-shot:
    digest = Shake128.HashData("Hello .NET!"u8, outputLength: 32);
}
else
{
    // Determine application behavior if SHAKE is not available.
}

SHA-3 support is currently aimed at supporting cryptographic primitives. Higher level constructions and protocols are not expected to fully support SHA-3 initially. This includes, but is not limited to, X.509 certificates, SignedXml, and COSE. Support for SHA-3 may expand in the future depending on platform support and standards which adopt SHA-3.

SHA-3 was standardized by NIST as FIPS 202 as an alternative to, not successor, to SHA-2. Developers and organizations should decide when or even if adopting SHA-3 is appropriate for them.

[ilonatommy]

HybridGlobalization mode on WASM

WASM app can use a new globalization mode that brings lighter ICU bundle and leverages Web API instead. In Hybrid mode, globalization data is partially pulled from ICU bundle and partially from calls into JS. It serves all the locales supported by WASM.

When to consider using HybridGlobalization:

This option is most suitable for applications that cannot work in InvariantGlobalization mode and use localization data from more than one ICU shard (EFIGS, CJK, no-CJK) - so currently using either:

<BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>

in Blazor WebAssembly or

<WasmIncludeFullIcuData>true</WasmIncludeFullIcuData>

in WASM Browser.

Apps that were loading no-CJK or CJK shard using the custom ICU file loading method:

<WasmIcuDataFileName>icudt_no_CJK.dat</WasmIcuDataFileName>

might also be interested, because hybrid file is smaller than no-CJK shard by 26% and smaller than CJK by 15%.

How to use HybridGlobalization:

Set MsBuild property: <HybridGlobalization>true</HybridGlobalization>. It will load icudt_hybrid.dat file that is 46% smaller than originally loaded icudt.dat.

Limitations:

Due to limitations of Web API, not all Globalization APIs are supported in Hybrid mode. Some of the supported APIs changed their behavior. To make sure your application is will not be affected, read the section Behavioral differences for WASM.

APIs that obtain the result by calling into JS have worse performance than the non-hybrid version. These APIs are listed in the documentation. The APIs that are not on the "Affected public APIs" lists perform the same as in non-hybrid mode.

[tarekgh]

Expanding LoggerMessageAttribute Constructor Overloads for Enhanced Functionality

The LoggerMessageAttribute previously offered only two constructors:

    public LoggerMessageAttribute()
    public LoggerMessageAttribute(int eventide, LogLevel level, string message)

a parameter-less constructor and another constructor that required specifying all the parameters (int eventide, LogLevel level, string message). This limitation meant that users had to either provide all the parameters, even if they didn't need them, using the second constructor, or use the parameter-less constructor and then supply the necessary parameters through attribute properties, such as [LoggerMessage(Message = "A record is being skipped: {recordId}")].
To address this issue, additional constructor overloads have been introduced, offering greater flexibility in specifying the required parameters with reduced code. The new constructor overloads include options such as specifying only the LogLevel and message, only the LogLevel, or only the message. These enhancements make it easier for users to define LoggerMessageAttributes while minimizing unnecessary code.

    public LoggerMessageAttribute(LogLevel level, string message);
    public LoggerMessageAttribute(LogLevel level);
    public LoggerMessageAttribute(string message);

Example

        [LoggerMessage(Level = LogLevel.Warning, Message = "{p1} should be valid")]
        public partial void LogWaraning(string p1);

dotnet/runtime#87254

Note: In the upcoming preview, for constructors that do not require an event Id, the system will automatically generate the event Id, eliminating the need for users to manually provide it.

[tarekgh]

Metric APIs change

InstrumentRecorder

In Preview 5, we introduced a class called InstrumentRecorder, primarily designed as a helper class for test scenarios. However, in Preview 6, we made significant improvements to this class and relocated it to a different library called Microsoft.Extensions.Telemetry.Testing. Along with the relocation, we also renamed the class to MetricCollector.
These enhancements in Preview 6 now allow the MetricCollector class to record metric measurements along with timestamps. Additionally, the class offers the flexibility to use any desired time provider for accurate timestamp generation.

Example

        const string CounterName = "MyCounter";

        var now = DateTimeOffset.Now;

        var timeProvider = new FakeTimeProvider(now);
        using var meter = new Meter(Guid.NewGuid().ToString());
        var counter = meter.CreateCounter<long>(CounterName);
        using var collector = new MetricCollector<long>(counter, timeProvider);

        Assert.Empty(collector.GetMeasurementSnapshot());
        Assert.Null(collector.LastMeasurement);

        counter. Add(3);

        // verify the update was recorded
        Assert.Equal(counter, collector.Instrument);
        Assert.NotNull(collector.LastMeasurement);
        
        Assert.Single(collector.GetMeasurementSnapshot());
        Assert.Same(collector.GetMeasurementSnapshot().Last(), collector.LastMeasurement);
        Assert.Equal(3, collector.LastMeasurement.Value);
        Assert.Empty(collector.LastMeasurement.Tags);
        Assert.Equal(now, collector.LastMeasurement.Timestamp);        

AddMetrics extension method namespace

To ensure consistency with the other extension methods in IServiceCollection, the namespace of the AddMetrics method has been modified from Microsoft.Extensions.Diagnostics.Metrics to Microsoft.Extensions.DependencyInjection. This change allows for a more unified and streamlined approach when using the IServiceCollection extension methods.

- namespace Microsoft.Extensions.Diagnostics.Metrics
+ namespace Microsoft.Extensions.DependencyInjection
{
    public static class MetricsServiceExtensions
    {
        public static IServiceCollection AddMetrics(this IServiceCollection services)
    }
}

[tarekgh]

Introducing the options validation source generator

To reduce startup overhead and improve validation feature set, we've introduced the source code generator that implements the validation logic.

Example

public class FirstModelNoNamespace
{
    [Required]
    [MinLength(5)]
    public string P1 { get; set; } = string. Empty;

    [Microsoft.Extensions.Options.ValidateObjectMembers(typeof(SecondValidatorNoNamespace))]
    public SecondModelNoNamespace? P2 { get; set; }

    [Microsoft.Extensions.Options.ValidateObjectMembers]
    public ThirdModelNoNamespace? P3 { get; set; }
}

public class SecondModelNoNamespace
{
    [Required]
    [MinLength(5)]
    public string P4 { get; set; } = string. Empty;
}

public class ThirdModelNoNamespace
{
    [Required]
    [MinLength(5)]
    public string P5 { get; set; } = string.Empty;
}

[OptionsValidator]
public partial class FirstValidatorNoNamespace : IValidateOptions<FirstModelNoNamespace>
{
}

[OptionsValidator]
public partial class SecondValidatorNoNamespace : IValidateOptions<SecondModelNoNamespace>
{
}

This will generate code like the following:

partial class FirstValidatorNoNamespace
{
    /// <summary>
    /// Validates a specific named options instance (or all when <paramref name="name"/> is <see langword="null" />).
    /// </summary>
    /// <param name="name">The name of the options instance being validated.</param>
    /// <param name="options">The options instance.</param>
    /// <returns>Validation result.</returns>
    [global::System.CodeDom.Compiler.GeneratedCodeAttribute("Microsoft.Extensions.Options.SourceGeneration", "42.42.42.42")]
    public global::Microsoft.Extensions.Options.ValidateOptionsResult Validate(string? name, global::FirstModelNoNamespace options)
    {
        var baseName = (string.IsNullOrEmpty(name) ? "FirstModelNoNamespace" : name) + ".";
        var builder = new global::Microsoft.Extensions.Options.ValidateOptionsResultBuilder();
        var context = new global::System.ComponentModel.DataAnnotations.ValidationContext(options);
        var validationResults = new global::System.Collections.Generic.List<global::System.ComponentModel.DataAnnotations.ValidationResult>();
        var validationAttributes = new global::System.Collections.Generic.List<global::System.ComponentModel.DataAnnotations.ValidationAttribute>(2);

        context.MemberName = "P1";
        context.DisplayName = baseName + "P1";
        validationAttributes.Add(global::__OptionValidationStaticInstances.__Attributes.A1);
        validationAttributes.Add(global::__OptionValidationStaticInstances.__Attributes.A2);
        if (!global::System.ComponentModel.DataAnnotations.Validator.TryValidateValue(options.P1!, context, validationResults, validationAttributes))
        {
            builder.AddResults(validationResults);
        }

        if (options.P2 is not null)
        {
            builder.AddResult(global::__OptionValidationStaticInstances.__Validators.V1.Validate(baseName + "P2", options.P2));
        }

        if (options.P3 is not null)
        {
            builder.AddResult(global::__ThirdModelNoNamespaceValidator__.Validate(baseName + "P3", options.P3));
        }

        return builder. Build();
    }
}


partial class SecondValidatorNoNamespace
{
    /// <summary>
    /// Validates a specific named options instance (or all when <paramref name="name"/> is <see langword="null" />).
    /// </summary>
    /// <param name="name">The name of the options instance being validated.</param>
    /// <param name="options">The options instance.</param>
    /// <returns>Validation result.</returns>
    [global::System.CodeDom.Compiler.GeneratedCodeAttribute("Microsoft.Extensions.Options.SourceGeneration", "42.42.42.42")]
    public global::Microsoft.Extensions.Options.ValidateOptionsResult Validate(string? name, global::SecondModelNoNamespace options)
    {
        var baseName = (string.IsNullOrEmpty(name) ? "SecondModelNoNamespace" : name) + ".";
        var builder = new global::Microsoft.Extensions.Options.ValidateOptionsResultBuilder();
        var context = new global::System.ComponentModel.DataAnnotations.ValidationContext(options);
        var validationResults = new global::System.Collections.Generic.List<global::System.ComponentModel.DataAnnotations.ValidationResult>();
        var validationAttributes = new global::System.Collections.Generic.List<global::System.ComponentModel.DataAnnotations.ValidationAttribute>(2);

        context.MemberName = "P4";
        context.DisplayName = baseName + "P4";
        validationAttributes.Add(global::__OptionValidationStaticInstances.__Attributes.A1);
        validationAttributes.Add(global::__OptionValidationStaticInstances.__Attributes.A2);
        if (!global::System.ComponentModel.DataAnnotations.Validator.TryValidateValue(options.P4!, context, validationResults, validationAttributes))
        {
            builder.AddResults(validationResults);
        }

        return builder. Build();
    }
}

If the app is using dependency injection, it can easily inject the validation there.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllersWithViews();
builder.Services.Configure<FirstModelNoNamespace>(builder.Configuration.GetSection(...));

builder.Services.AddSingleton<IValidateOptions<FirstModelNoNamespace>, FirstValidatorNoNamespace>();
builder.Services.AddSingleton<IValidateOptions<SecondModelNoNamespace>, SecondValidatorNoNamespace>();

dotnet/runtime#85475

[jkoritzinsky]

Interop: Source Generated COM Interop

In .NET 8 Preview 6, we have shipped a new source generator that supports interoperating with COM interfaces using the source generated interop story that we started with LibraryImportAttribute. In .NET 8 Preview 6, you can use the System.Runtime.InteropServices.Marshalling.GeneratedComInterfaceAttribute to mark an interface as a COM interface for the source generator. The source generator will then generate code to enable calling from C# code to unmanaged code, as well as code to enable calling from unmanaged code into C#. This source generator integrates with LibraryImportAttribute, and you can use types with the GeneratedComInterfaceAttribute as parameters and return types in LibraryImportAttribute-attributed methods.

using System.Runtime.InteropServices;
using System.Runtime.InteropServices.Marshalling;

[GeneratedComInterface]
[Guid("5401c312-ab23-4dd3-aa40-3cb4b3a4683e")]
interface IComInterface
{
    void DoWork();
}

internal class MyNativeLib
{
    [LibraryImport(nameof(MyNativeLib))]
    public static partial void GetComInterface(out IComInterface comInterface);
}

The source generator also supports the new System.Runtime.InteropServices.Marshalling.GeneratedComClassAttribute to enable you to pass your types that implement interfaces with the System.Runtime.InteropServices.Marshalling.GeneratedComInterfaceAttribute-attributed interfaces to unmanaged code. The source generator will generate the code necessary to expose a COM object that implements the interfaces and forwards calls to the managed implementation.

using System.Runtime.InteropServices;
using System.Runtime.InteropServices.Marshalling;

MyNativeLib.GetComInterface(out IComInterface comInterface);
comInterface.RegisterCallbacks(new MyCallbacks());
comInterface.DoWork();

[GeneratedComInterface]
[Guid("5401c312-ab23-4dd3-aa40-3cb4b3a4683e")]
interface IComInterface
{
    void DoWork();
    void RegisterCallbacks(ICallbacks callbacks);
}

[GeneratedComInterface]
[Guid("88470b56-aabc-46af-bf97-8106a1aa3cf9")]
interface ICallbacks
{
    void Callback();
}

internal class MyNativeLib
{
    [LibraryImport(nameof(MyNativeLib))]
    public static partial void GetComInterface(out IComInterface comInterface);
}

[GeneratedComClass]
internal class MyCallbacks : ICallbacks
{
    public void Callback()
    {
        Console.WriteLine("Callback called");
    }
}

Methods on interfaces with the GeneratedComInterfaceAttribute support all the same types as LibraryImportAttribute, and LibraryImportAttribute gains support for GeneratedComInterface-attributed types and GeneratedComClass-attributed types in this release.

If your C# code will only be use a GeneratedComInterfaceAttribute-attributed interface to either wrap a COM object from unmanaged code or wrap a managed object from C# to expose to unmanaged code, you can use the options in the GeneratedComInterfaceAttribute.Options property to customize which code will be generated. This option will enable you to not need to write marshallers for scenarios that you know will not be used.

The source generator uses the new System.Runtime.InteropServices.Marshalling.StrategyBasedComWrappers type to create and manage the COM object wrappers and the managed object wrappers. This new type handles providing the expected .NET user experience for COM interop, while providing customization points for advanced users. If your application has its own mechanism for defining types from COM or if you need to support scenarios that source-generated COM does not currently support, you can consider using the new StrategyBasedComWrappers type to add the missing features for your scenario and get the same .NET user experience for your COM types.

How to Use

Like LibraryImportAttribute, the COM source generator provides an easy onboarding experience through analyzers and code fixers. Next to each interface that has the System.Runtime.InteropServices.ComImportAttribute, a lightbulb will offer an option to convert to source generated interop. This fix will change the interface to use the GeneratedComInterfaceAttribute. Next to every class that implements an interface with the GeneratedComInterfaceAttribute, a lightbulb will offer an option to add the GeneratedComClassAttribute to the type. Once your types are converted, you can move your DllImport methods to use LibraryImportAttribute with the existing code fixer there. With these two lightbulbs, it is easy to convert your existing COM interop code to use the new source generated interop. There are also more analyzers to help catch places where you may be mixing source-generated and runtime-based COM interop that may require additional work.

Limitations

Currently the COM source generator has the following limitations. We do not expect to address these limitations in .NET 8, but we may in a future version of .NET.

• No support for IDispatch-based interfaces.
  • Support for these interfaces may be manually implemented using a local definition of the IDispatch interface.
• No support for IInspectable-based interfaces.
  • Use the CsWinRT tool to generate the interop code for these interfaces.
• No support for apartment affinity.
  • All COM objects are assumed to be free-threaded. Support for apartment affinity may be manually implemented using the StrategyBasedComWrappers type and custom strategy implementations.
• No support for COM properties.
  • These may be manually implemented as methods on the interface.
• No support for COM events.
  • These may be manually implemented using the underlying COM APIs.
• No support for using the new keyword to activate a COM CoClass.
  • Use LibraryImportAttribute to P/Invoke to the CoCreateInstance API to activate the CoClass.

Usage in .NET

We have already moved the .NET support for distributed transactions through the System.Transactions library to use the new source-generated interop! We used this experience to help refine the analyzers and code-fixers to provide a good migration experience.

[carlossanlop]

Stream-based ZipFile CreateFromDirectory and ExtractToDirectory method overloads

We added new overloads of ZipFile.CreateFromDirectory that allow users to collect all the files included in a directory and zip them, then store the resulting zip file into the provided stream.

Symmetrically, we added the ZipFile.ExtractToDirectory overloads that allow users to provide a stream containing a zipped file and extract its contents into the filesystem.

These APIs can avoid having to use the disk as an intermediate step. This can be useful in scenarios where disk space is constrained, like for example, in cloud-based environments:

• CreateFromDirectory does not have to write the zipped result into disk.
• ExtractToDirectory does not require the zipped file to be located in disk.

APIs

namespace System.IO.Compression;

public static partial class ZipFile
{
    public static void CreateFromDirectory(string sourceDirectoryName, Stream destination);
    public static void CreateFromDirectory(string sourceDirectoryName, Stream destination, CompressionLevel compressionLevel, bool includeBaseDirectory);
    public static void CreateFromDirectory(string sourceDirectoryName, Stream destination, CompressionLevel compressionLevel, bool includeBaseDirectory, Encoding? entryNameEncoding);

    public static void ExtractToDirectory(Stream source, string destinationDirectoryName) { }
    public static void ExtractToDirectory(Stream source, string destinationDirectoryName, bool overwriteFiles) { }
    public static void ExtractToDirectory(Stream source, string destinationDirectoryName, Encoding? entryNameEncoding) { }
    public static void ExtractToDirectory(Stream source, string destinationDirectoryName, Encoding? entryNameEncoding, bool overwriteFiles) { }
}

Usage

Here are a couple of examples using the overloads that take all the arguments:

Stream destinationStream = GetStreamFromSomewhere();

ZipFile.CreateFromDirectory(
    sourceDirectoryName: "/home/username/sourcedirectory/",
    destination: destinationStream,
    compressionLevel: CompressionLevel.Optimal,
    includeBaseDirectory: true,
    entryNameEncoding: Encoding.UTF8);

Stream sourceStream = GetStreamFromSomewhere();

ZipFile.ExtractToDirectory(
    source: sourceStream,
    destinationDirectoryName: "/home/username/destinationdirectory/",
    entryNameEncoding: Encoding.UTF8,
    overwriteFiles: true);

dotnet/runtime#1555