CA1844: Op geheugen gebaseerde onderdrukkingen van asynchrone methoden bieden bij het subklassen 'Stream'

Oorzaak

Een type dat is afgeleid van Stream onderdrukkingen ReadAsync(Byte[], Int32, Int32, CancellationToken) , maar niet overschrijft ReadAsync(Memory<Byte>, CancellationToken). Of een type dat is afgeleid van Stream onderdrukkingen WriteAsync(Byte[], Int32, Int32, CancellationToken) , maar niet overschrijft WriteAsync(ReadOnlyMemory<Byte>, CancellationToken).

Beschrijving van regel

De op geheugen gebaseerde ReadAsync en WriteAsync methoden zijn toegevoegd om de prestaties te verbeteren, die ze op meerdere manieren bereiken:

• Ze retourneren ValueTask en ValueTask<int> in plaats van Task respectievelijk.Task<int>
• Hiermee kan elk type buffer worden doorgegeven zonder dat u een extra kopie naar een matrix hoeft uit te voeren.

Om deze prestatievoordelen te realiseren, moeten typen die zijn afgeleid van Stream hun eigen implementatie op basis van geheugen bieden. Anders wordt de standaard implementatie gedwongen het geheugen naar een matrix te kopiëren om de implementatie op basis van een matrix aan te roepen, wat resulteert in verminderde prestaties. Wanneer de aanroeper een Memory<T> of ReadOnlyMemory<T> exemplaar doorgeeft dat niet wordt ondersteund door een matrix, worden de prestaties meer beïnvloed.

Schendingen oplossen

De eenvoudigste manier om schendingen op te lossen, is door uw implementatie op basis van matrix te herschrijven als een implementatie op basis van geheugen en vervolgens de op matrix gebaseerde methoden te implementeren in termen van de methoden op basis van geheugen.

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);
}

Wanneer waarschuwingen onderdrukken

Het is veilig om een waarschuwing van deze regel te onderdrukken als een van de volgende situaties van toepassing is:

• De prestatietreffer is geen probleem.
• U weet dat uw Stream subklasse alleen gebruikmaakt van de op matrix gebaseerde methoden.
• Uw Stream subklasse bevat afhankelijkheden die geen ondersteuning bieden voor buffers op basis van geheugen.

Een waarschuwing onderdrukken

Als u slechts één schending wilt onderdrukken, voegt u preprocessorrichtlijnen toe aan uw bronbestand om de regel uit te schakelen en vervolgens opnieuw in te schakelen.

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

Als u de regel voor een bestand, map of project wilt uitschakelen, stelt u de ernst none ervan in op het configuratiebestand.

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

Zie Codeanalysewaarschuwingen onderdrukken voor meer informatie.

Zie ook

• Prestatieregels