---

This section details on the original issue you should resolve

<issue_title>[API Proposal]: TextWriter.WriteLineAsync with CancellationToken overloads</issue_title>
<issue_description>### Background and motivation

Currently, the only way to use StreamWriter.Write[Line]Async(string) with a CancellationToken is to call AsMemory on the string, then use StreamWriter.Write[Line]Async(ReadOnlyMemory<char>, CancellationToken). In fact, this is what StreamWriter.Write[Line]Async(string) does, but it uses default(CancellationToken) (see lines 676 and 833):

runtime/src/libraries/System.Private.CoreLib/src/System/IO/StreamWriter.cs

Lines 660 to 685 in 1d1bf92

	public override Task WriteAsync(string? value)
	{
	// If we have been inherited into a subclass, the following implementation could be incorrect
	// since it does not call through to Write() which a subclass might have overridden.
	// To be safe we will only use this implementation in cases where we know it is safe to do so,
	// and delegate to our base class (which will call into Write) when we are not sure.
	if (GetType() != typeof(StreamWriter))
	{
	return base.WriteAsync(value);
	}
	if (value != null)
	{
	ThrowIfDisposed();
	CheckAsyncTaskInProgress();
	Task task = WriteAsyncInternal(value.AsMemory(), appendNewLine: false, default);
	_asyncWriteTask = task;
	return task;
	}
	else
	{
	return Task.CompletedTask;
	}
	}

runtime/src/libraries/System.Private.CoreLib/src/System/IO/StreamWriter.cs

Lines 814 to 837 in 1d1bf92

	public override Task WriteLineAsync(string? value)
	{
	if (value == null)
	{
	return WriteLineAsync();
	}
	// If we have been inherited into a subclass, the following implementation could be incorrect
	// since it does not call through to Write() which a subclass might have overridden.
	// To be safe we will only use this implementation in cases where we know it is safe to do so,
	// and delegate to our base class (which will call into Write) when we are not sure.
	if (GetType() != typeof(StreamWriter))
	{
	return base.WriteLineAsync(value);
	}
	ThrowIfDisposed();
	CheckAsyncTaskInProgress();
	Task task = WriteAsyncInternal(value.AsMemory(), appendNewLine: true, default);
	_asyncWriteTask = task;
	return task;
	}

I propose CancellationToken overloads be added to TextWriter and have StreamWriter use them.

API Proposal

namespace System.IO;

public abstract class TextWriter
{
    // default impl would have token only affect the `Task.Factory.StartNew` invocation (same
    //   behavior as existing `Write[Line]Async(ReadOnlyMemory<char>, CancellationToken)`  methods)
    // alternatively, they could complete synchronously like `Stream` does
    public virtual Task WriteAsync(string? value, CancellationToken token);
    public virtual Task WriteLineAsync(CancellationToken token);
    public virtual Task WriteLineAsync(string? value, CancellationToken token);
}

public class StreamWriter : TextWriter
{
    // token would be passed to `WriteAsyncInternal`
    public override Task WriteAsync(string? value, CancellationToken token);
    public override Task WriteLineAsync(CancellationToken token);
    public override Task WriteLineAsync(string? value, CancellationToken token);
}

API Usage

Old code:

await using StreamWriter writer = new(...);
await writer.WriteLine(string.Create(CultureInfo.InvariantCulture, $"...").AsMemory(), token);

New code:

await using StreamWriter writer = new(...);
await writer.WriteLine(string.Create(CultureInfo.InvariantCulture, $"..."), token);

Alternative Designs

An analyzer to turn StreamWriter.Write[Line]Async(string) into StreamWriter.Write[Line]Async(ReadOnlyMemory<char>, CancellationToken)

Risks

Code previously using TextWriter.WriteLineAsync() and TextWriter.Write[Line]Async(string) with a CancellationToken in scope will get new warnings to pass in that token.

Open Questions

• Should the cancellation token have a default value (i.e., CancellationToken token = default in the signatures)?</issue_description>

<agent_instructions>Please implement the approved API on the base TextWriter class. You'll need to update not only the TextWriter.cs class, but also the corresponding surface area in the relevant ref file, and add tests.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@stephentoub > I stumbled over the same problem. I thought about giving it a shot, would this be a good first issue?

Thanks for the interest. We need to review the proposal first. </comment_new>
<comment_new>@bartonjs
Video

• Approved as non-virtual (they can defer to the ReadOnlyMemory implementation). If we need virtual later we can do that.

namespace System.IO;

public abstract class TextWriter
{
    public Task WriteAsync(string? value, CancellationToken token);
    public Task WriteLineAsync(CancellationToken token);
    public Task WriteLineAsync(string? value, CancellationToken token);
}
```</body></comment_new>
</comments>