CA1844: fornecer substituições baseadas em memória dos métodos assíncronos ao subclassificar 'Stream'

Causa

Um tipo derivado de Stream substitui ReadAsync(Byte[], Int32, Int32, CancellationToken), mas não substitui ReadAsync(Memory<Byte>, CancellationToken). Ou, um tipo derivado de Stream substitui WriteAsync(Byte[], Int32, Int32, CancellationToken), mas não substitui WriteAsync(ReadOnlyMemory<Byte>, CancellationToken).

Descrição da regra

Os métodos ReadAsync e WriteAsync baseados em memória foram adicionados para melhorar o desempenho, o que eles fazem de várias maneiras:

• Eles retornam ValueTask e ValueTask<int>, em vez de Task e Task<int>, respectivamente.
• Eles permitem que qualquer tipo de buffer seja passado sem precisar executar uma cópia extra para uma matriz.

Para obter esses benefícios de desempenho, os tipos que derivam de Stream devem fornecer uma implementação própria baseada em memória. Caso contrário, a implementação padrão será forçada a copiar a memória para uma matriz para chamar a implementação baseada em matriz, resultando em desempenho reduzido. Quando o chamador passa uma instância Memory<T> ou ReadOnlyMemory<T> que não é apoiada por uma matriz, o desempenho é mais afetado.

Como corrigir violações

A maneira mais fácil de corrigir violações é reescrever a implementação baseada em matriz como uma implementação baseada em memória e implementar os métodos baseados em matriz em termos dos métodos baseados em memória.

Example

// This class violates the rule.
public class BadStream : Stream
{
    private readonly Stream _innerStream;

    public BadStream(Stream innerStream)
    {
        _innerStream = innerStream;
    }

    public override bool CanRead => _innerStream.CanRead;
    public override bool CanSeek => _innerStream.CanSeek;
    public override bool CanWrite => _innerStream.CanWrite;
    public override long Length => _innerStream.Length;
    public override long Position { get => _innerStream.Position; set => _innerStream.Position = value; }

    public override async Task<int> ReadAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken)
    {
        // ...
        return await _innerStream.ReadAsync(buffer, offset, count, cancellationToken);
    }

    public override async Task WriteAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken)
    {
        // ...
        await _innerStream.WriteAsync(buffer, offset, count, cancellationToken);
    }

    // Other required overrides
    public override void Flush() => _innerStream.Flush();
    public override int Read(byte[] buffer, int offset, int count) => _innerStream.Read(buffer, offset, count);
    public override long Seek(long offset, SeekOrigin origin) => _innerStream.Seek(offset, origin);
    public override void SetLength(long value) => _innerStream.SetLength(value);
    public override void Write(byte[] buffer, int offset, int count) => _innerStream.Write(buffer, offset, count);
}

// This class satisfies the rule.
public class GoodStream : Stream
{
    private readonly Stream _innerStream;

    public GoodStream(Stream innerStream)
    {
        _innerStream = innerStream;
    }

    public override bool CanRead => _innerStream.CanRead;
    public override bool CanSeek => _innerStream.CanSeek;
    public override bool CanWrite => _innerStream.CanWrite;
    public override long Length => _innerStream.Length;
    public override long Position { get => _innerStream.Position; set => _innerStream.Position = value; }

    public override async ValueTask<int> ReadAsync(Memory<byte> buffer, CancellationToken cancellationToken = default)
    {
        // ...
        return await _innerStream.ReadAsync(buffer, cancellationToken);
    }

    public override async ValueTask WriteAsync(ReadOnlyMemory<byte> buffer, CancellationToken cancellationToken = default)
    {
        // ...
        await _innerStream.WriteAsync(buffer, cancellationToken);
    }

    public override async Task<int> ReadAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken)
    {
        return await this.ReadAsync(buffer.AsMemory(offset, count), cancellationToken);
    }

    public override async Task WriteAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken)
    {
        await this.WriteAsync(buffer.AsMemory(offset, count), cancellationToken);
    }

    // Other required overrides
    public override void Flush() => _innerStream.Flush();
    public override int Read(byte[] buffer, int offset, int count) => _innerStream.Read(buffer, offset, count);
    public override long Seek(long offset, SeekOrigin origin) => _innerStream.Seek(offset, origin);
    public override void SetLength(long value) => _innerStream.SetLength(value);
    public override void Write(byte[] buffer, int offset, int count) => _innerStream.Write(buffer, offset, count);
}

Quando suprimir avisos

Será seguro suprimir um aviso dessa regra se qualquer uma das seguintes situações se aplicar:

• O impacto no desempenho não é uma preocupação.
• Você sabe que sua subclasse Stream usará apenas os métodos baseados em matriz.
• Sua subclasse Stream tem dependências que não dão suporte a buffers baseados em memória.

Suprimir um aviso

Para suprimir apenas uma violação, adicione diretivas de pré-processador ao arquivo de origem a fim de desabilitar e, em seguida, reabilitar a regra.

#pragma warning disable CA1844
// The code that's violating the rule is on this line.
#pragma warning restore CA1844

Para desabilitar a regra em um arquivo, uma pasta ou um projeto, defina a severidade como none no arquivo de configuração.

[*.{cs,vb}]
dotnet_diagnostic.CA1844.severity = none

Para obter mais informações, confira Como suprimir avisos de análise de código.

Confira também

• Regras de desempenho