Freigeben über


UTF-7-Codepfade sind veraltet

Die UTF-7-Codierung wird nicht mehr in der breiten Anwendung verwendet, und viele Spezifikationen verbieten jetzt ihre Verwendung im Austausch. Es wird auch gelegentlich als Angriffsvektor in Anwendungen verwendet, die nicht erwarten, dass UTF-7-codierte Daten auftreten. Microsoft warnt vor der Verwendung, System.Text.UTF7Encoding da sie keine Fehlererkennung bereitstellt.

Folglich sind die Encoding.UTF7 Eigenschaften und UTF7Encoding Konstruktoren mittlerweile veraltet. Zusätzlich erlauben Encoding.GetEncoding und Encoding.GetEncodings Ihnen nicht mehr, UTF-7 anzugeben.

Änderungsbeschreibung

Zuvor können Sie eine Instanz der UTF-7-Codierung mithilfe der Encoding.GetEncoding APIs erstellen. Beispiel:

Encoding enc1 = Encoding.GetEncoding("utf-7"); // By name.
Encoding enc2 = Encoding.GetEncoding(65000); // By code page.

Darüber hinaus wurde eine Instanz, die die UTF-7-Codierung darstellt, von der Encoding.GetEncodings() Methode aufgezählt, die alle Encoding im System registrierten Instanzen aufzählt.

Ab .NET 5 sind die Encoding.UTF7 Eigenschaften und UTF7Encoding Konstruktoren veraltet und erzeugen Warnungen SYSLIB0001. Um jedoch die Anzahl der Warnungen zu verringern, die Anrufer bei Verwendung der UTF7Encoding Klasse erhalten, ist der UTF7Encoding Typ selbst nicht als veraltet gekennzeichnet.

// The next line generates warning SYSLIB0001.
UTF7Encoding enc = new UTF7Encoding();
// The next line does not generate a warning.
byte[] bytes = enc.GetBytes("Hello world!");

Darüber hinaus behandeln die Encoding.GetEncoding Methoden den Codierungsnamen utf-7 und die Codeseite 65000 als unknown. Das Behandeln der Codierung als unknown führt dazu, dass die Methode eine ArgumentException wirft.

// Throws ArgumentException, same as calling Encoding.GetEncoding("unknown").
Encoding enc = Encoding.GetEncoding("utf-7");

Schließlich enthält die Encoding.GetEncodings() Methode die UTF-7-Codierung nicht in das EncodingInfo zurückgegebene Array. Die Codierung wird ausgeschlossen, da sie nicht instanziiert werden kann.

foreach (EncodingInfo encInfo in Encoding.GetEncodings())
{
    // The next line would throw if GetEncodings included UTF-7.
    Encoding enc = Encoding.GetEncoding(encInfo.Name);
}

Grund für Änderung

Viele Anwendungen rufen Encoding.GetEncoding("encoding-name") mit einem Codierungsnamenwert auf, der von einer nicht vertrauenswürdigen Quelle bereitgestellt wird. Beispielsweise kann ein Webclient oder -server den charset Teil des Content-Type Headers nehmen und den Wert direkt weitergeben, ohne ihn zu Encoding.GetEncoding validieren. Dadurch kann ein böswilliger Endpunkt Content-Type: ...; charset=utf-7 angeben, was dazu führen kann, dass die empfangende Anwendung ein Fehlverhalten zeigt.

Darüber hinaus ermöglicht das Deaktivieren von UTF-7-Codepfaden das Optimieren von Compilern, wie z. B. von Blazor, zum Vollständigen Entfernen dieser Codepfade aus der resultierenden Anwendung. Daher werden die kompilierten Anwendungen effizienter ausgeführt und belegen weniger Speicherplatz.

Eingeführte Version

5.0

In den meisten Fällen müssen Sie keine Maßnahmen ergreifen. Beachten Sie für Apps, die zuvor UTF-7-bezogene Codepfade aktiviert haben, die folgenden Anleitungen.

  • Wenn Ihre App Encoding.GetEncoding mit unbekannten Codierungsnamen aufruft, die von einer nicht vertrauenswürdigen Quelle bereitgestellt werden:

    Vergleichen Sie stattdessen die Codierungsnamen mit einer konfigurierbaren Zulassungsliste. Die konfigurierbare Zulassungsliste sollte mindestens den Branchenstandard "utf-8" enthalten. Je nach Ihren Clients und behördlichen Anforderungen müssen Sie möglicherweise auch regionsspezifische Codierungen zulassen, z. B. "GB18030".

    Wenn Sie keine Zulassungsliste implementieren, gibt Encoding.GetEncoding jede Encoding zurück, die im System integriert ist oder über einen benutzerdefinierten EncodingProvider registriert ist. Überwachen Sie die Anforderungen Ihres Diensts, um zu überprüfen, ob dies das gewünschte Verhalten ist. UTF-7 wird standardmäßig weiterhin deaktiviert, es sei denn, Ihre Anwendung aktiviert den weiter unten in diesem Artikel erwähnten Kompatibilitätsswitch erneut.

  • Wenn Sie Encoding.UTF7 oder UTF7Encoding innerhalb Ihres eigenen Protokolls oder Dateiformats verwenden:

    Wechseln Sie zur Verwendung von Encoding.UTF8 oder UTF8Encoding. UTF-8 ist ein Branchenstandard und wird in allen Sprachen, Betriebssystemen und Laufzeiten weit unterstützt. Die Verwendung von UTF-8 erleichtert zukünftige Wartung Ihres Codes und macht ihn mit dem Rest des Ökosystems interoperabler.

  • Wenn Sie eine Encoding-Instanz gegen Encoding.UTF7 vergleichen:

    Erwägen Sie stattdessen, eine Überprüfung gegen die bekannte UTF-7-Codeseite durchzuführen, die 65000 lautet. Durch Vergleichen mit der Codepage vermeiden Sie die Warnung und können außerdem einige Sonderfälle behandeln, wenn beispielsweise jemand new UTF7Encoding() aufgerufen oder Unterklassen des Typs erstellt hat.

    void DoSomething(Encoding enc)
    {
        // Don't perform the check this way.
        // It produces a warning and misses some edge cases.
        if (enc == Encoding.UTF7)
        {
            // Encoding is UTF-7.
        }
    
        // Instead, perform the check this way.
        if (enc != null && enc.CodePage == 65000)
        {
            // Encoding is UTF-7.
        }
    }
    
  • Wenn Sie Encoding.UTF7 oder UTF7Encoding verwenden müssen:

    Sie können die Warnung im Code oder in der SYSLIB0001CSPROJ-Datei Ihres Projekts unterdrücken.

    #pragma warning disable SYSLIB0001 // Disable the warning.
    Encoding enc = Encoding.UTF7;
    #pragma warning restore SYSLIB0001 // Re-enable the warning.
    
    <Project Sdk="Microsoft.NET.Sdk">
      <PropertyGroup>
       <TargetFramework>net5.0</TargetFramework>
       <!-- NoWarn below suppresses SYSLIB0001 project-wide -->
       <NoWarn>$(NoWarn);SYSLIB0001</NoWarn>
      </PropertyGroup>
    </Project>
    

    Hinweis

    Das Unterdrücken von SYSLIB0001 deaktiviert nur die Encoding.UTF7- und UTF7Encoding-Warnungen über Veraltetes. Es deaktiviert keine anderen Warnungen und ändert nicht das Verhalten von APIs wie Encoding.GetEncoding.

  • Wenn Sie Encoding.GetEncoding("utf-7", ...) unterstützen müssen, gehen Sie wie folgt vor:

    Sie können die Unterstützung dafür über einen Kompatibilitätsschalter erneut aktivieren. Dieser Kompatibilitätsswitch kann in der CSPROJ-Datei der Anwendung oder in einer Laufzeitkonfigurationsdatei angegeben werden, wie in den folgenden Beispielen gezeigt.

    In der CSPROJ-Datei der Anwendung:

    <Project Sdk="Microsoft.NET.Sdk">
      <PropertyGroup>
       <TargetFramework>net5.0</TargetFramework>
       <!-- Re-enable support for UTF-7 -->
       <EnableUnsafeUTF7Encoding>true</EnableUnsafeUTF7Encoding>
      </PropertyGroup>
    </Project>
    

    In der runtimeconfig.template.json-Datei der Anwendung:

    {
      "configProperties": {
        "System.Text.Encoding.EnableUnsafeUTF7Encoding": true
      }
    }
    

    Tipp

    Wenn Sie die Unterstützung für UTF-7 erneut aktivieren, sollten Sie eine Sicherheitsüberprüfung des Codes durchführen, der Encoding.GetEncoding aufruft.

Betroffene APIs