<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Grant Totinov, M. Eng.</title>
    <description>The latest articles on DEV Community by Grant Totinov, M. Eng. (@granttotinov).</description>
    <link>https://dev.to/granttotinov</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4189698%2F61866765-f152-43cc-b88f-b6797bacee5f.jpg</url>
      <title>DEV Community: Grant Totinov, M. Eng.</title>
      <link>https://dev.to/granttotinov</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/granttotinov"/>
    <language>en</language>
    <item>
      <title>JPEG header, PHP payload: why I built UploadGuard for ASP.NET Core uploads</title>
      <dc:creator>Grant Totinov, M. Eng.</dc:creator>
      <pubDate>Sun, 15 Nov 2026 17:37:08 +0000</pubDate>
      <link>https://dev.to/granttotinov/jpeg-header-php-payload-why-i-built-uploadguard-for-aspnet-core-uploads-445d</link>
      <guid>https://dev.to/granttotinov/jpeg-header-php-payload-why-i-built-uploadguard-for-aspnet-core-uploads-445d</guid>
      <description>&lt;p&gt;Most ASP.NET Core apps accept files from users somewhere: avatars, CVs, CSV imports. The validation is usually a few lines. Compare the extension with a list, maybe read the first bytes with a signature library, and save the file. The &lt;a href="https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html" rel="noopener noreferrer"&gt;OWASP File Upload Cheat Sheet&lt;/a&gt; is blunt about signature checks: &lt;em&gt;"This should not be used on its own, as bypassing it is pretty common and easy."&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;A JPEG header followed by &lt;code&gt;&amp;lt;?php&lt;/code&gt;, a Word document with a VBA project inside, and a ZIP that unpacks to a hundred times its size all start with the right magic bytes. I wanted one place that does the rest of the work, so I built &lt;a href="https://github.com/GrantTotinov/UploadGuard" rel="noopener noreferrer"&gt;UploadGuard&lt;/a&gt;. It's MIT licensed, it targets .NET 10, and the first preview went up on &lt;a href="https://www.nuget.org/packages/UploadGuard" rel="noopener noreferrer"&gt;NuGet&lt;/a&gt; on 7 November 2026. This post is about what it checks, in what order, and the parts I deliberately left out.&lt;/p&gt;

&lt;h2&gt;
  
  
  One policy per kind of upload
&lt;/h2&gt;

&lt;p&gt;You describe each kind of upload once, as a named allow-list with limits:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="n"&gt;builder&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Services&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;AddUploadGuard&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;o&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;o&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;StoragePath&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"/var/app/uploads"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;o&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;AddPolicy&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"avatars"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;p&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;AllowImages&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;MaxSize&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;5&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;1024&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;1024&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;ReencodeImages&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// UploadGuard.PixelForge&lt;/span&gt;
    &lt;span class="n"&gt;o&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;AddPolicy&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"cv"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;p&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Allow&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;FileTypes&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Pdf&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;FileTypes&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Docx&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;MaxSize&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;10&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;1024&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;1024&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="n"&gt;builder&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Services&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;AddUploadGuardClamAV&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;o&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;o&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Host&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"clamav"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// UploadGuard.ClamAV, optional&lt;/span&gt;

&lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;MapPost&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"/avatar"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;IFormFile&lt;/span&gt; &lt;span class="n"&gt;file&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;UploadPipeline&lt;/span&gt; &lt;span class="n"&gt;uploads&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="n"&gt;result&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;uploads&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;SaveAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;file&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"avatars"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;result&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;IsValid&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="nc"&gt;Results&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Ok&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;result&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;StoredName&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Results&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;BadRequest&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;result&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Error&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;MapPost&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"/cv"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;IFormFile&lt;/span&gt; &lt;span class="n"&gt;file&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;WithUploadPolicy&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"cv"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;WithUploadPolicy&lt;/code&gt; is an endpoint filter: every file in the form is checked before the handler runs, and a bad one gets a &lt;code&gt;400&lt;/code&gt; validation problem with one error per form field. MVC has the same thing as an &lt;code&gt;[UploadPolicy("cv")]&lt;/code&gt; attribute.&lt;/p&gt;

&lt;p&gt;Mistakes in the configuration show up at startup. &lt;code&gt;AddUploadGuard&lt;/code&gt; runs your configuration eagerly instead of on first use, and the endpoint filter looks its policy up while the endpoint is being built. A policy without types, a duplicate name or &lt;code&gt;WithUploadPolicy("typo")&lt;/code&gt; stops the app from starting, rather than failing on the first real upload.&lt;/p&gt;

&lt;h2&gt;
  
  
  Fourteen files
&lt;/h2&gt;

&lt;p&gt;To see where signature matching stops, I ran the same 14 files through two popular signature libraries and through UploadGuard, used the way apps usually use them: accept the file when the detected extension equals the file's extension. Every file is generated by the test suite, and the comparison runs with &lt;code&gt;dotnet run -c Release --project benchmarks/UploadGuard.Benchmarks -- --compare&lt;/code&gt;.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;File&lt;/th&gt;
&lt;th&gt;Expected&lt;/th&gt;
&lt;th&gt;Mime-Detective 25.8.1&lt;/th&gt;
&lt;th&gt;File.TypeChecker 4.4.0&lt;/th&gt;
&lt;th&gt;UploadGuard&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;JPEG photo&lt;/td&gt;
&lt;td&gt;accept&lt;/td&gt;
&lt;td&gt;✅ accepted&lt;/td&gt;
&lt;td&gt;✅ accepted&lt;/td&gt;
&lt;td&gt;✅ accepted&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Word document&lt;/td&gt;
&lt;td&gt;accept&lt;/td&gt;
&lt;td&gt;❌ rejected (detected zip)&lt;/td&gt;
&lt;td&gt;✅ accepted&lt;/td&gt;
&lt;td&gt;✅ accepted&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;CSV export&lt;/td&gt;
&lt;td&gt;accept&lt;/td&gt;
&lt;td&gt;❌ rejected (not recognized)&lt;/td&gt;
&lt;td&gt;❌ rejected (not recognized)&lt;/td&gt;
&lt;td&gt;✅ accepted&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;JPEG with PHP appended&lt;/td&gt;
&lt;td&gt;reject&lt;/td&gt;
&lt;td&gt;❌ accepted&lt;/td&gt;
&lt;td&gt;❌ accepted&lt;/td&gt;
&lt;td&gt;✅ rejected (ActiveContent)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GIF/HTML polyglot&lt;/td&gt;
&lt;td&gt;reject&lt;/td&gt;
&lt;td&gt;❌ accepted&lt;/td&gt;
&lt;td&gt;❌ accepted&lt;/td&gt;
&lt;td&gt;✅ rejected (ActiveContent)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;PNG with &lt;code&gt;&amp;lt;script&amp;gt;&lt;/code&gt; appended&lt;/td&gt;
&lt;td&gt;reject&lt;/td&gt;
&lt;td&gt;❌ accepted&lt;/td&gt;
&lt;td&gt;❌ accepted&lt;/td&gt;
&lt;td&gt;✅ rejected (ActiveContent)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Macro-enabled Word renamed .docx&lt;/td&gt;
&lt;td&gt;reject&lt;/td&gt;
&lt;td&gt;✅ rejected (detected zip)&lt;/td&gt;
&lt;td&gt;❌ accepted&lt;/td&gt;
&lt;td&gt;✅ rejected (ExtensionMismatch)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;ZIP bomb (20 MB of zeros)&lt;/td&gt;
&lt;td&gt;reject&lt;/td&gt;
&lt;td&gt;❌ accepted&lt;/td&gt;
&lt;td&gt;✅ rejected (detected docx)&lt;/td&gt;
&lt;td&gt;✅ rejected (ArchiveTooLarge)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;ZIP slip (&lt;code&gt;../&lt;/code&gt; entry)&lt;/td&gt;
&lt;td&gt;reject&lt;/td&gt;
&lt;td&gt;❌ accepted&lt;/td&gt;
&lt;td&gt;✅ rejected (detected docx)&lt;/td&gt;
&lt;td&gt;✅ rejected (UnsafeArchive)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;PDF with JavaScript&lt;/td&gt;
&lt;td&gt;reject&lt;/td&gt;
&lt;td&gt;❌ accepted&lt;/td&gt;
&lt;td&gt;❌ accepted&lt;/td&gt;
&lt;td&gt;✅ rejected (ActiveContent)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;PDF with JavaScript in an object stream&lt;/td&gt;
&lt;td&gt;reject&lt;/td&gt;
&lt;td&gt;❌ accepted&lt;/td&gt;
&lt;td&gt;❌ accepted&lt;/td&gt;
&lt;td&gt;✅ rejected (ActiveContent)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;SVG with &lt;code&gt;&amp;lt;script&amp;gt;&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;reject&lt;/td&gt;
&lt;td&gt;✅ rejected (detected xml)&lt;/td&gt;
&lt;td&gt;✅ rejected (detected xml)&lt;/td&gt;
&lt;td&gt;✅ rejected (ActiveContent)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;HTML page named .csv&lt;/td&gt;
&lt;td&gt;reject&lt;/td&gt;
&lt;td&gt;✅ rejected (not recognized)&lt;/td&gt;
&lt;td&gt;✅ rejected (not recognized)&lt;/td&gt;
&lt;td&gt;✅ rejected (ExtensionMismatch)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;File name &lt;code&gt;shell.php.jpg&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;reject&lt;/td&gt;
&lt;td&gt;❌ accepted&lt;/td&gt;
&lt;td&gt;❌ accepted&lt;/td&gt;
&lt;td&gt;✅ rejected (InvalidFileName)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Correct&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;4/14&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;6/14&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;14/14&lt;/strong&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Some of the ✅ in the first two columns are right for the wrong reason. File.TypeChecker reports the bomb and the zip slip file as &lt;code&gt;docx&lt;/code&gt;, and Mime-Detective reports both Word files as &lt;code&gt;zip&lt;/code&gt;. That isn't a criticism: both libraries are good at signature matching, which is what they're for. UploadGuard is the layer around it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Nine checks, cheapest first
&lt;/h2&gt;

&lt;p&gt;Every upload goes through the same checks, and the first one that fails decides the result:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;#&lt;/th&gt;
&lt;th&gt;Check&lt;/th&gt;
&lt;th&gt;Error code&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;The file isn't empty&lt;/td&gt;
&lt;td&gt;&lt;code&gt;Empty&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;The size is within the policy's &lt;code&gt;MaxSize&lt;/code&gt; (10 MB by default)&lt;/td&gt;
&lt;td&gt;&lt;code&gt;TooLarge&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;The file name is safe&lt;/td&gt;
&lt;td&gt;&lt;code&gt;InvalidFileName&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;td&gt;The content is a known type, detected from the bytes only&lt;/td&gt;
&lt;td&gt;&lt;code&gt;UnknownType&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;5&lt;/td&gt;
&lt;td&gt;The extension belongs to the detected type&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ExtensionMismatch&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;6&lt;/td&gt;
&lt;td&gt;The type is on the policy's allow-list&lt;/td&gt;
&lt;td&gt;&lt;code&gt;TypeNotAllowed&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;7&lt;/td&gt;
&lt;td&gt;The &lt;code&gt;Content-Type&lt;/code&gt; header is empty, &lt;code&gt;application/octet-stream&lt;/code&gt; or a media type of the detected type&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ContentTypeMismatch&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;8&lt;/td&gt;
&lt;td&gt;Type-specific content checks&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;ArchiveTooLarge&lt;/code&gt;, &lt;code&gt;UnsafeArchive&lt;/code&gt;, &lt;code&gt;ActiveContent&lt;/code&gt;, &lt;code&gt;Corrupt&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;9&lt;/td&gt;
&lt;td&gt;Every registered scanner, such as ClamAV&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;Malware&lt;/code&gt;, &lt;code&gt;ScanFailed&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The order is deliberate. Size is checked before anything reads the content, so every later scan is bounded by &lt;code&gt;MaxSize&lt;/code&gt;. And because only one check fails, &lt;code&gt;UploadResult.Error.Code&lt;/code&gt; names exactly one reason. That code also tags the &lt;code&gt;uploadguard.uploads&lt;/code&gt; metric, so a dashboard can show which check is rejecting what. The error messages never contain internal details, so they're safe to return to the client.&lt;/p&gt;

&lt;p&gt;The file name rules in step 3 aren't about storage, because stored files never use the client's name. They catch names that only an attacker sends: paths, colons (&lt;code&gt;file.asp::$DATA&lt;/code&gt;), control and invisible bidi characters, Windows device names like &lt;code&gt;CON.jpg&lt;/code&gt;, trailing dots, and an executable extension in the middle, as in &lt;code&gt;shell.php.jpg&lt;/code&gt;, which a misconfigured Apache will run as PHP.&lt;/p&gt;

&lt;h2&gt;
  
  
  The type comes from the bytes
&lt;/h2&gt;

&lt;p&gt;The detector never looks at the extension or the Content-Type. It reads the header and recognizes 47 types, from JPEG and PDF to Office, OpenDocument, audio, video and executables. Some formats can't be told apart by content: CSV and plain text are the same bytes, and DOC, XLS and PPT share the compound file header. For those the detector returns several candidates, and the extension chooses between them:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="n"&gt;candidates&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nc"&gt;FileDetector&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;DetectAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;content&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;cancellationToken&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="n"&gt;extension&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;Path&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;GetExtension&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;fileName&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;ToLowerInvariant&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;Array&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Find&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;candidates&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;c&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;c&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Extensions&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Contains&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;extension&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="c1"&gt;// null here is ExtensionMismatch&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Text gets the most care, because that's where HTML hides. A file counts as text when the whole thing decodes as strict UTF-8 (or UTF-16 with a byte order mark) without control characters. Then it's classified the way browsers sniff an unknown type, following the &lt;a href="https://mimesniff.spec.whatwg.org/" rel="noopener noreferrer"&gt;WHATWG MIME Sniffing Standard&lt;/a&gt;: if it starts with &lt;code&gt;&amp;lt;!DOCTYPE HTML&lt;/code&gt;, &lt;code&gt;&amp;lt;html&lt;/code&gt;, &lt;code&gt;&amp;lt;script&lt;/code&gt;, &lt;code&gt;&amp;lt;iframe&lt;/code&gt;, &lt;code&gt;&amp;lt;body&lt;/code&gt; or one of the other tags in that list, followed by a space or &lt;code&gt;&amp;gt;&lt;/code&gt;, it's HTML. That's how the "HTML page named .csv" row gets rejected. A browser that sniffs the file will render it as a page, so it can't be accepted as a CSV.&lt;/p&gt;

&lt;p&gt;Office files needed one more step. A &lt;code&gt;.docx&lt;/code&gt; and a &lt;code&gt;.docm&lt;/code&gt; are both ZIP files with the same layout. Office decides by the content type of the main part in &lt;code&gt;[Content_Types].xml&lt;/code&gt;, and a VBA project makes the file macro-enabled. UploadGuard reads the same things:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="n"&gt;macros&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;Has&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"macroEnabled"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nc"&gt;Has&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"vbaProject"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="n"&gt;zip&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Entries&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Any&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;e&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;FullName&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;EndsWith&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"vbaProject.bin"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;StringComparison&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;OrdinalIgnoreCase&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;Has&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"wordprocessingml.document.main+xml"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nc"&gt;Has&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"ms-word.document.macroEnabled.main+xml"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;macros&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="nc"&gt;FileTypes&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Docm&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;FileTypes&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Docx&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;So a macro document renamed to &lt;code&gt;.docx&lt;/code&gt; is detected as DOCM and fails step 5. No macro scanner is involved. For the older binary formats, DOC, XLS and PPT, step 8 searches for the &lt;code&gt;_VBA_PROJECT&lt;/code&gt; directory entry instead, and for OpenDocument it looks for &lt;code&gt;Basic/&lt;/code&gt; and &lt;code&gt;Scripts/&lt;/code&gt; folders.&lt;/p&gt;

&lt;h2&gt;
  
  
  Archives without unpacking them
&lt;/h2&gt;

&lt;p&gt;ZIP-based files (plain ZIP, OOXML and OpenDocument) are checked from the central directory, the index at the end of the file that lists every entry with its sizes. Nothing is inflated:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;zip&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Entries&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Count&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;policy&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;MaxArchiveEntries&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;TooLarge&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kt"&gt;long&lt;/span&gt; &lt;span class="n"&gt;total&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;foreach&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="n"&gt;entry&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;zip&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Entries&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;entry&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;IsEncrypted&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;UploadErrorCode&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;UnsafeArchive&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"The archive has encrypted entries, which cannot be inspected or scanned."&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nc"&gt;IsSafePath&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;entry&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;FullName&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;UploadErrorCode&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;UnsafeArchive&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"The archive has an entry whose path leaves the extraction folder."&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;entry&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Length&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;policy&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;MaxUncompressedBytes&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="n"&gt;total&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;TooLarge&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="n"&gt;total&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="n"&gt;entry&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Length&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;total&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;policy&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;MaxCompressionRatio&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="n"&gt;stream&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Length&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="nc"&gt;TooLarge&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The defaults are 10,000 entries, 256 MB unpacked and a ratio of 100, and &lt;code&gt;LimitArchives(...)&lt;/code&gt; changes them per policy. &lt;code&gt;IsSafePath&lt;/code&gt; is the zip slip check: a leading slash, a drive letter, a NUL or a &lt;code&gt;..&lt;/code&gt; segment, with either kind of slash, rejects the file.&lt;/p&gt;

&lt;p&gt;Trusting the declared sizes looks wrong for a bomb check, since an attacker writes them. It holds because .NET's &lt;code&gt;ZipArchive&lt;/code&gt; never inflates an entry past its declared size, and other extractors fail on the size and CRC mismatch. So code that unpacks with them can't be bombed by a lie these checks accepted. A custom inflater that ignores the declared size isn't protected, and the &lt;a href="https://github.com/GrantTotinov/UploadGuard/blob/main/docs/security.md" rel="noopener noreferrer"&gt;security notes&lt;/a&gt; say so.&lt;/p&gt;

&lt;p&gt;GZIP has no central directory, so there it's the other way round: the stream is inflated into a buffer that is thrown away, and the check stops as soon as the output passes the limit.&lt;/p&gt;

&lt;h2&gt;
  
  
  PDFs: a byte scan with two extra steps
&lt;/h2&gt;

&lt;p&gt;UploadGuard doesn't parse PDFs. It looks for the names that make a PDF do something when it's opened: &lt;code&gt;/JavaScript&lt;/code&gt;, &lt;code&gt;/JS&lt;/code&gt;, &lt;code&gt;/Launch&lt;/code&gt;, &lt;code&gt;/EmbeddedFile&lt;/code&gt;, &lt;code&gt;/RichMedia&lt;/code&gt; and &lt;code&gt;/XFA&lt;/code&gt;. A plain search for those is easy to get around, in two ways.&lt;/p&gt;

&lt;p&gt;First, a PDF name can write any character as &lt;code&gt;#&lt;/code&gt; and two hex digits, so &lt;code&gt;/J#61vaScript&lt;/code&gt; is &lt;code&gt;/JavaScript&lt;/code&gt;. The scanner decodes these escapes before it matches.&lt;/p&gt;

&lt;p&gt;Second, since PDF 1.5 objects can be stored inside compressed object streams, where a byte search only sees deflate data. So the inspector finds every &lt;code&gt;stream&lt;/code&gt; keyword, checks whether a zlib header follows it, and if so inflates the stream and scans the result:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="c1"&gt;// "stream", then CRLF or LF, then a zlib header: compression method 8 (deflate),&lt;/span&gt;
&lt;span class="c1"&gt;// and the two header bytes read as CMF * 256 + FLG are a multiple of 31 (RFC 1950).&lt;/span&gt;
&lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="n"&gt;cmf&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;window&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="n"&gt;flg&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;window&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;data&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;cmf&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&lt;/span&gt; &lt;span class="mh"&gt;0x0F&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="mi"&gt;8&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;cmf&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&amp;lt;&lt;/span&gt; &lt;span class="mi"&gt;8&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="n"&gt;flg&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;%&lt;/span&gt; &lt;span class="mi"&gt;31&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="n"&gt;from&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;All streams in a file share one budget, the same &lt;code&gt;maxUncompressedSize&lt;/code&gt; as archives, so a PDF can't be used as a decompression bomb against the checker itself. This is the "JavaScript in an object stream" row in the table, and it's also the slowest path: a PDF with a 200 KB compressed stream takes about 225 µs.&lt;/p&gt;

&lt;p&gt;It's still a scan and not a parser. LZW, ASCIIHex and encrypted streams aren't decoded. Pair it with antivirus, and never render user PDFs inline on your own origin.&lt;/p&gt;

&lt;h2&gt;
  
  
  Images, SVG and polyglots
&lt;/h2&gt;

&lt;p&gt;A file can be valid in two formats at once. A GIF can also parse as an HTML page, and a JPEG can carry PHP after its last marker. Every accepted image is searched for &lt;code&gt;&amp;lt;script&lt;/code&gt;, &lt;code&gt;&amp;lt;?php&lt;/code&gt;, &lt;code&gt;&amp;lt;html&lt;/code&gt;, &lt;code&gt;&amp;lt;iframe&lt;/code&gt;, &lt;code&gt;&amp;lt;body&lt;/code&gt; and &lt;code&gt;javascript:&lt;/code&gt;, ignoring case. The patterns are long enough that random pixel data practically never contains them.&lt;/p&gt;

&lt;p&gt;All the byte searches stream the file in 64 KB chunks instead of loading it. The last few bytes of each chunk are carried into the next one, as many as the longest pattern minus one, so a match across a chunk boundary isn't missed. For PDF names the overlap is three times longer, because each &lt;code&gt;#xx&lt;/code&gt; escape shrinks to one byte when it's decoded.&lt;/p&gt;

&lt;p&gt;SVG is XML, so it's read with &lt;code&gt;XmlReader&lt;/code&gt;, with the DTD ignored and never resolved. A file is rejected for script-like elements (&lt;code&gt;script&lt;/code&gt;, &lt;code&gt;foreignObject&lt;/code&gt;, &lt;code&gt;iframe&lt;/code&gt;, &lt;code&gt;embed&lt;/code&gt;, &lt;code&gt;object&lt;/code&gt;), &lt;code&gt;on*&lt;/code&gt; event handler attributes, an &lt;code&gt;xml-stylesheet&lt;/code&gt; instruction, or a script URL. Browsers ignore tabs and line breaks inside a URL scheme, so &lt;code&gt;javascript:&lt;/code&gt; with a tab in the middle still runs, and the check compares without them:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="kt"&gt;bool&lt;/span&gt; &lt;span class="nc"&gt;HasScriptUrl&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="n"&gt;compact&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Concat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Where&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;c&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;c&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="s1"&gt;' '&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;ScriptUrls&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Any&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;url&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;compact&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Contains&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;url&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;StringComparison&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;OrdinalIgnoreCase&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The markup scan only finds payloads it knows about. Re-encoding removes all of them. With &lt;a href="https://www.nuget.org/packages/UploadGuard.PixelForge" rel="noopener noreferrer"&gt;UploadGuard.PixelForge&lt;/a&gt;, &lt;code&gt;SaveAsync&lt;/code&gt; decodes each image with &lt;a href="https://granttotinov.github.io/projects/#pixelforge" rel="noopener noreferrer"&gt;PixelForge&lt;/a&gt; and encodes it again, so the stored file contains only pixels: EXIF and GPS data, comments, appended bytes and polyglot payloads are gone. The image is rotated upright first, because the orientation tag is dropped too. The pixel limit is read from the header before any memory is allocated, which stops decompression bombs such as a tiny PNG that claims to be 50000×50000. JPEG and WebP keep their format, and lossless WebP stays lossless. PNG, GIF and BMP become PNG.&lt;/p&gt;

&lt;h2&gt;
  
  
  Antivirus that fails closed
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://www.nuget.org/packages/UploadGuard.ClamAV" rel="noopener noreferrer"&gt;UploadGuard.ClamAV&lt;/a&gt; streams every file that passed the built-in checks to clamd. The &lt;code&gt;INSTREAM&lt;/code&gt; command is small enough to implement directly: send &lt;code&gt;zINSTREAM\0&lt;/code&gt;, then the content in chunks, each prefixed with its length as a 4-byte unsigned integer in network byte order, then a zero-length chunk. The &lt;code&gt;z&lt;/code&gt; prefix makes clamd end its reply with a NUL byte.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="nc"&gt;Task&lt;/span&gt; &lt;span class="nc"&gt;StreamChunksAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;Stream&lt;/span&gt; &lt;span class="n"&gt;content&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;NetworkStream&lt;/span&gt; &lt;span class="n"&gt;network&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;CancellationToken&lt;/span&gt; &lt;span class="n"&gt;cancellationToken&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="n"&gt;buffer&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="kt"&gt;byte&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;4&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="nc"&gt;ChunkSize&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="kt"&gt;int&lt;/span&gt; &lt;span class="n"&gt;read&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;while&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;read&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;content&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;ReadAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;buffer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;AsMemory&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;4&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;ChunkSize&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;cancellationToken&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nc"&gt;BinaryPrimitives&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;WriteUInt32BigEndian&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;buffer&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;uint&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="n"&gt;read&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;network&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;WriteAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;buffer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;AsMemory&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;4&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="n"&gt;read&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;cancellationToken&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;network&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;WriteAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="kt"&gt;byte&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;4&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;cancellationToken&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The more important decision is what happens when the scanner can't answer. If clamd is down, slower than the timeout (30 seconds by default), or refuses a stream longer than its &lt;code&gt;StreamMaxLength&lt;/code&gt;, the upload is rejected with &lt;code&gt;ScanFailed&lt;/code&gt;. A scanner that can't give a verdict is treated as a scanner that said no:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;UploadRejectedException&lt;/span&gt; &lt;span class="n"&gt;e&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;result&lt;/span&gt; &lt;span class="n"&gt;with&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;Error&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Error&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;Exception&lt;/span&gt; &lt;span class="n"&gt;e&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;when&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;cancellationToken&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;IsCancellationRequested&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nc"&gt;LogScanFailed&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;_logger&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;e&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;scanner&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;GetType&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Name&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;result&lt;/span&gt; &lt;span class="n"&gt;with&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;Error&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;UploadErrorCode&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;ScanFailed&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"The file could not be scanned for malware."&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The signature name of an infected file goes to the log, not to the client. &lt;code&gt;ClamAVClient&lt;/code&gt; also works on its own, with &lt;code&gt;PingAsync&lt;/code&gt;, &lt;code&gt;GetVersionAsync&lt;/code&gt; and &lt;code&gt;ScanAsync&lt;/code&gt;, and there's a health check for it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Storing and serving files
&lt;/h2&gt;

&lt;p&gt;With a &lt;code&gt;StoragePath&lt;/code&gt;, accepted files are saved under 128 random bits plus the detected type's extension, so the client's file name is never used as a path. The app refuses to start if that folder is inside the web root, where files could be served or executed directly. Reading and deleting accept only names in the generated format, so a name taken from a URL can't traverse out of the folder.&lt;/p&gt;

&lt;p&gt;Serving files back is still your code, and it should make sure a browser never runs them:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;MapGet&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"/files/{name}"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;IUploadStorage&lt;/span&gt; &lt;span class="n"&gt;storage&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;HttpContext&lt;/span&gt; &lt;span class="n"&gt;http&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="n"&gt;content&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;storage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;OpenReadAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// throws ArgumentException for foreign names&lt;/span&gt;
    &lt;span class="n"&gt;http&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Headers&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;XContentTypeOptions&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"nosniff"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;http&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Headers&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;ContentSecurityPolicy&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"default-src 'none'; sandbox"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;Results&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;File&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;content&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"application/octet-stream"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;fileDownloadName&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Serving user files from a separate domain is better still. For blob storage, register your own &lt;code&gt;IUploadStorage&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  How fast it is
&lt;/h2&gt;

&lt;p&gt;Time to accept one valid file, measured with BenchmarkDotNet on an AMD Ryzen 5 5500U and .NET 10.0.11:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;File&lt;/th&gt;
&lt;th&gt;UploadGuard&lt;/th&gt;
&lt;th&gt;Mime-Detective&lt;/th&gt;
&lt;th&gt;File.TypeChecker&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1920×1080 JPEG&lt;/td&gt;
&lt;td&gt;9.7 µs&lt;/td&gt;
&lt;td&gt;60.1 µs&lt;/td&gt;
&lt;td&gt;5.4 µs&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;DOCX&lt;/td&gt;
&lt;td&gt;9.9 µs&lt;/td&gt;
&lt;td&gt;13.7 µs&lt;/td&gt;
&lt;td&gt;7.6 µs&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;PDF with a 200 KB compressed stream&lt;/td&gt;
&lt;td&gt;225 µs&lt;/td&gt;
&lt;td&gt;8.6 µs&lt;/td&gt;
&lt;td&gt;7.8 µs&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The comparison isn't like for like. The other two libraries only match signatures, while UploadGuard runs the whole policy, including the content checks for that type. The PDF row is the inflation from the previous section, and its cost grows with the size of the streams, up to the policy's limit.&lt;/p&gt;

&lt;h2&gt;
  
  
  What it doesn't cover
&lt;/h2&gt;

&lt;p&gt;UploadGuard lowers the risk of accepting a file. It doesn't make an untrusted file safe to open in every program, and I'd rather be clear about where it stops:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;The PDF and legacy Office checks are byte scans, not parsers. PowerPoint 97 can store VBA in places the &lt;code&gt;_VBA_PROJECT&lt;/code&gt; search doesn't see.&lt;/li&gt;
&lt;li&gt;Archives are inspected one level deep. A ZIP inside a ZIP isn't unpacked, and 7z, RAR and TAR are recognized but their contents aren't inspected.&lt;/li&gt;
&lt;li&gt;Only images can be rebuilt. Documents, archives and media are stored as uploaded, and their content can still exploit a vulnerable viewer.&lt;/li&gt;
&lt;li&gt;Text formats aren't validated beyond their encoding. CSV formula injection and XML external entities are problems for the code that reads the file.&lt;/li&gt;
&lt;li&gt;Authentication, authorization, CSRF protection and rate limiting stay your app's job.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The &lt;a href="https://github.com/GrantTotinov/UploadGuard/blob/main/docs/security.md" rel="noopener noreferrer"&gt;security notes&lt;/a&gt; map every recommendation of the OWASP cheat sheet to either a feature or "your app", and list these gaps in more detail.&lt;/p&gt;

&lt;h2&gt;
  
  
  Trying it
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;dotnet add package UploadGuard --prerelease
dotnet add package UploadGuard.ClamAV --prerelease       &lt;span class="c"&gt;# optional: virus scanning with clamd&lt;/span&gt;
dotnet add package UploadGuard.PixelForge --prerelease   &lt;span class="c"&gt;# optional: image re-encoding&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;It's a preview, so the API can still change. If a file gets through that shouldn't, or a real file gets rejected, please &lt;a href="https://github.com/GrantTotinov/UploadGuard/issues" rel="noopener noreferrer"&gt;open an issue&lt;/a&gt;. For anything that looks like a vulnerability, the &lt;a href="https://github.com/GrantTotinov/UploadGuard/blob/main/SECURITY.md" rel="noopener noreferrer"&gt;security policy&lt;/a&gt; says how to report it privately.&lt;/p&gt;

&lt;h2&gt;
  
  
  References
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;GrantTotinov/UploadGuard on GitHub: &lt;a href="https://github.com/GrantTotinov/UploadGuard" rel="noopener noreferrer"&gt;README&lt;/a&gt; and &lt;a href="https://github.com/GrantTotinov/UploadGuard/blob/main/docs/security.md" rel="noopener noreferrer"&gt;security model&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;NuGet: &lt;a href="https://www.nuget.org/packages/UploadGuard" rel="noopener noreferrer"&gt;UploadGuard&lt;/a&gt;, &lt;a href="https://www.nuget.org/packages/UploadGuard.ClamAV" rel="noopener noreferrer"&gt;UploadGuard.ClamAV&lt;/a&gt; and &lt;a href="https://www.nuget.org/packages/UploadGuard.PixelForge" rel="noopener noreferrer"&gt;UploadGuard.PixelForge&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;OWASP, &lt;a href="https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html" rel="noopener noreferrer"&gt;File Upload Cheat Sheet&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;WHATWG, &lt;a href="https://mimesniff.spec.whatwg.org/" rel="noopener noreferrer"&gt;MIME Sniffing Standard&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;Adobe, &lt;a href="https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/PDF32000_2008.pdf" rel="noopener noreferrer"&gt;PDF 32000-1:2008 (PDF 1.7)&lt;/a&gt;, §7.3.5 Name Objects and §7.5.7 Object Streams.&lt;/li&gt;
&lt;li&gt;P. Deutsch and J-L. Gailly, &lt;a href="https://www.rfc-editor.org/rfc/rfc1950.html" rel="noopener noreferrer"&gt;RFC 1950: ZLIB Compressed Data Format Specification version 3.3&lt;/a&gt;, 1996.&lt;/li&gt;
&lt;li&gt;ClamAV, &lt;a href="https://github.com/Cisco-Talos/clamav/blob/main/docs/man/clamd.8.in" rel="noopener noreferrer"&gt;clamd(8) manual page&lt;/a&gt;, the &lt;code&gt;INSTREAM&lt;/code&gt; command.&lt;/li&gt;
&lt;li&gt;The libraries in the comparison: &lt;a href="https://www.nuget.org/packages/Mime-Detective/25.8.1" rel="noopener noreferrer"&gt;Mime-Detective 25.8.1&lt;/a&gt; and &lt;a href="https://www.nuget.org/packages/File.TypeChecker/4.4.0" rel="noopener noreferrer"&gt;File.TypeChecker 4.4.0&lt;/a&gt;.&lt;/li&gt;
&lt;/ol&gt;

</description>
      <category>dotnet</category>
      <category>aspnetcore</category>
      <category>security</category>
      <category>csharp</category>
    </item>
    <item>
      <title>Typed, documented, ignored: forwarding getReferencedVirtualElement in Tiptap's React drag handle</title>
      <dc:creator>Grant Totinov, M. Eng.</dc:creator>
      <pubDate>Mon, 09 Nov 2026 17:00:52 +0000</pubDate>
      <link>https://dev.to/granttotinov/typed-documented-ignored-forwarding-getreferencedvirtualelement-in-tiptaps-react-drag-handle-5f07</link>
      <guid>https://dev.to/granttotinov/typed-documented-ignored-forwarding-getreferencedvirtualelement-in-tiptaps-react-drag-handle-5f07</guid>
      <description>&lt;p&gt;This is the smallest of my merged PRs: three added lines in &lt;a href="https://github.com/ueberdosis/tiptap/pull/7832" rel="noopener noreferrer"&gt;ueberdosis/tiptap#7832&lt;/a&gt;, merged on 15 May 2026 and published in &lt;code&gt;@tiptap/extension-drag-handle-react&lt;/code&gt; 3.23.5. I'm writing it up anyway, because the kind of bug it fixes is common in any library that wraps one implementation for several frameworks, and nothing in the toolchain catches it.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the option is for
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://tiptap.dev" rel="noopener noreferrer"&gt;Tiptap&lt;/a&gt; is a headless rich-text editor built on ProseMirror. Its drag handle extension shows a grip next to the block you're hovering, so you can drag paragraphs and other blocks around. The grip is positioned with Floating UI's &lt;code&gt;computePosition&lt;/code&gt;, using the hovered block's DOM element as the reference:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;repositionDragHandle&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;dom&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Element&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;virtualElement&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;getReferencedVirtualElement&lt;/span&gt;&lt;span class="p"&gt;?.()&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="na"&gt;getBoundingClientRect&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;dom&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getBoundingClientRect&lt;/span&gt;&lt;span class="p"&gt;(),&lt;/span&gt;
  &lt;span class="p"&gt;};&lt;/span&gt;

  &lt;span class="nf"&gt;computePosition&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;virtualElement&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;element&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;computePositionConfig&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;then&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;val&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// ...apply val.x / val.y&lt;/span&gt;
  &lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;getReferencedVirtualElement&lt;/code&gt; lets you replace that reference with a Floating UI virtual element, which is any object with a &lt;code&gt;getBoundingClientRect()&lt;/code&gt;. That's useful when the handle should line up with something other than the block's own box, such as a gutter or a custom node view.&lt;/p&gt;

&lt;h2&gt;
  
  
  The bug
&lt;/h2&gt;

&lt;p&gt;Issue &lt;a href="https://github.com/ueberdosis/tiptap/issues/7748" rel="noopener noreferrer"&gt;#7748&lt;/a&gt;, from &lt;a href="https://github.com/jbt" rel="noopener noreferrer"&gt;@jbt&lt;/a&gt; against 3.21.0, was short. The React &lt;code&gt;&amp;lt;DragHandle&amp;gt;&lt;/code&gt; component had the prop in its &lt;code&gt;DragHandleProps&lt;/code&gt; type, the &lt;a href="https://tiptap.dev/docs/editor/extensions/functionality/drag-handle-react#getreferencedvirtualelement" rel="noopener noreferrer"&gt;React drag handle docs&lt;/a&gt; described it, and passing it had no effect.&lt;/p&gt;

&lt;p&gt;The framework-agnostic extension did forward it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// packages/extension-drag-handle/src/drag-handle.ts&lt;/span&gt;
&lt;span class="nc"&gt;DragHandlePlugin&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
  &lt;span class="c1"&gt;// ...&lt;/span&gt;
  &lt;span class="na"&gt;getReferencedVirtualElement&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;options&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;getReferencedVirtualElement&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="c1"&gt;// ...&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The React component built the same plugin from its props, and this one option was missing from the list. Two wrappers around one plugin had drifted apart.&lt;/p&gt;

&lt;h2&gt;
  
  
  The fix
&lt;/h2&gt;

&lt;p&gt;Destructure the prop, pass it to the plugin, and add it to the effect's dependencies:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight tsx"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="c1"&gt;// ...&lt;/span&gt;
  &lt;span class="nx"&gt;onElementDragEnd&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nx"&gt;getReferencedVirtualElement&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nx"&gt;computePositionConfig&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;defaultComputePositionConfig&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nx"&gt;nested&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;props&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="nf"&gt;useEffect&lt;/span&gt;&lt;span class="p"&gt;(()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="c1"&gt;// ...&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;plugin&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;unbind&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;DragHandlePlugin&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="nx"&gt;editor&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nx"&gt;element&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nx"&gt;pluginKey&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="c1"&gt;// ...&lt;/span&gt;
    &lt;span class="nx"&gt;onNodeChange&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nx"&gt;getReferencedVirtualElement&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nx"&gt;nestedOptions&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;});&lt;/span&gt;

  &lt;span class="nx"&gt;editor&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;registerPlugin&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;plugin&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;return &lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;editor&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;isDestroyed&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nx"&gt;editor&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;unregisterPlugin&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;pluginKey&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="nf"&gt;unbind&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="p"&gt;};&lt;/span&gt;
&lt;span class="p"&gt;},&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
  &lt;span class="nx"&gt;element&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nx"&gt;editor&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nx"&gt;onNodeChange&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nx"&gt;getReferencedVirtualElement&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nx"&gt;pluginKey&lt;/span&gt; &lt;span class="cm"&gt;/* ... */&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;]);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Plus a changeset marking &lt;code&gt;@tiptap/extension-drag-handle-react&lt;/code&gt; for a patch release. To confirm it shipped, I unpacked the published packages from npm and searched the built &lt;code&gt;dist/index.js&lt;/code&gt; for the option name:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;3.23.4 : 0 occurrences
3.23.5 : 3 occurrences
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The three occurrences are the destructure, the plugin argument and the dependency.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why TypeScript didn't catch it
&lt;/h2&gt;

&lt;p&gt;The prop was declared, typed and documented. The code still compiled, because TypeScript doesn't complain when you leave a property out of a destructuring pattern. An unused prop isn't an error. The type said "this component accepts the option", and nothing could check the claim that it also used it.&lt;/p&gt;

&lt;p&gt;That's the general shape of this bug. When a wrapper lists the options it forwards one by one, every new option on the underlying plugin has to be added in several places: the type, the destructure, the call, and sometimes the dependency array. Missing one of them is silent. A test that renders the React component with every option set and checks what the plugin received would catch it. My PR didn't add one, and it would be a good follow-up.&lt;/p&gt;

&lt;h2&gt;
  
  
  The dependency array
&lt;/h2&gt;

&lt;p&gt;Adding the function to the &lt;code&gt;useEffect&lt;/code&gt; dependencies is the correct thing to do in React, and it's also how the other callback props (&lt;code&gt;onNodeChange&lt;/code&gt;, &lt;code&gt;onElementDragStart&lt;/code&gt;, &lt;code&gt;onElementDragEnd&lt;/code&gt;) were already handled. It has a consequence worth knowing about. When the function's identity changes, the effect runs again: the plugin is unregistered and a new one is registered.&lt;/p&gt;

&lt;p&gt;If you write the function inline, it's a new function on every render:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight tsx"&gt;&lt;code&gt;&lt;span class="c1"&gt;// re-registers the drag handle plugin on every render&lt;/span&gt;
&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;DragHandle&lt;/span&gt; &lt;span class="na"&gt;editor&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="si"&gt;{&lt;/span&gt;&lt;span class="nx"&gt;editor&lt;/span&gt;&lt;span class="si"&gt;}&lt;/span&gt; &lt;span class="na"&gt;getReferencedVirtualElement&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="si"&gt;{&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;myVirtualElement&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;&lt;span class="si"&gt;}&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Keep it stable with &lt;code&gt;useCallback&lt;/code&gt; instead:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight tsx"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;getReferencedVirtualElement&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;useCallback&lt;/span&gt;&lt;span class="p"&gt;(()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;rect&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;editor&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;view&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;dom&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getBoundingClientRect&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;top&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;bottom&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;editor&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;view&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;coordsAtPos&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;editor&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;state&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;selection&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="k"&gt;from&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="c1"&gt;// a contrived example: pin the handle to the editor's left edge,&lt;/span&gt;
  &lt;span class="c1"&gt;// level with the current selection&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;getBoundingClientRect&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;DOMRect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;rect&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;left&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;top&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;bottom&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="nx"&gt;top&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;},&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;editor&lt;/span&gt;&lt;span class="p"&gt;])&lt;/span&gt;

&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;DragHandle&lt;/span&gt; &lt;span class="nx"&gt;editor&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="nx"&gt;editor&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="nx"&gt;getReferencedVirtualElement&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="nx"&gt;getReferencedVirtualElement&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The alternative inside the component would be to keep the latest callback in a ref and leave it out of the dependencies. That avoids re-registering the plugin, but it would have changed how all the callback props behave, which is much more than a forwarding fix should do.&lt;/p&gt;

&lt;h2&gt;
  
  
  References
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;ueberdosis/tiptap issue &lt;a href="https://github.com/ueberdosis/tiptap/issues/7748" rel="noopener noreferrer"&gt;#7748&lt;/a&gt;: React DragHandle component ignores getReferencedVirtualElement.&lt;/li&gt;
&lt;li&gt;ueberdosis/tiptap PR &lt;a href="https://github.com/ueberdosis/tiptap/pull/7832" rel="noopener noreferrer"&gt;#7832&lt;/a&gt;: fix(drag-handle-react): forward getReferencedVirtualElement to plugin.&lt;/li&gt;
&lt;li&gt;Tiptap docs, &lt;a href="https://tiptap.dev/docs/editor/extensions/functionality/drag-handle-react" rel="noopener noreferrer"&gt;Drag Handle React extension&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;Floating UI docs, &lt;a href="https://floating-ui.com/docs/virtual-elements" rel="noopener noreferrer"&gt;Virtual elements&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;React docs, &lt;a href="https://react.dev/reference/react/useCallback" rel="noopener noreferrer"&gt;useCallback&lt;/a&gt;.&lt;/li&gt;
&lt;/ol&gt;

</description>
      <category>tiptap</category>
      <category>react</category>
      <category>typescript</category>
    </item>
    <item>
      <title>List`1[System.Int32] is not a style: escaping interpolated values in Spectre.Console markup</title>
      <dc:creator>Grant Totinov, M. Eng.</dc:creator>
      <pubDate>Sat, 07 Nov 2026 18:52:18 +0000</pubDate>
      <link>https://dev.to/granttotinov/list1systemint32-is-not-a-style-escaping-interpolated-values-in-spectreconsole-markup-1lcm</link>
      <guid>https://dev.to/granttotinov/list1systemint32-is-not-a-style-escaping-interpolated-values-in-spectreconsole-markup-1lcm</guid>
      <description>&lt;p&gt;&lt;a href="https://spectreconsole.net" rel="noopener noreferrer"&gt;Spectre.Console&lt;/a&gt; uses square brackets for markup: &lt;code&gt;[red]error[/]&lt;/code&gt; prints "error" in red. Any literal &lt;code&gt;[&lt;/code&gt; in your text has to be escaped as &lt;code&gt;[[&lt;/code&gt;, otherwise the parser tries to read it as a style.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;MarkupInterpolated&lt;/code&gt; and &lt;code&gt;MarkupLineInterpolated&lt;/code&gt; exist so you don't have to think about that for values you interpolate. You write &lt;code&gt;$"Hello {name}"&lt;/code&gt; and the library escapes &lt;code&gt;name&lt;/code&gt; for you. Issue &lt;a href="https://github.com/spectreconsole/spectre.console/issues/1763" rel="noopener noreferrer"&gt;#1763&lt;/a&gt;, opened by &lt;a href="https://github.com/yaakov-h" rel="noopener noreferrer"&gt;@yaakov-h&lt;/a&gt;, showed that this only worked when the value was a &lt;code&gt;string&lt;/code&gt;. My fix is &lt;a href="https://github.com/spectreconsole/spectre.console/pull/2118" rel="noopener noreferrer"&gt;#2118&lt;/a&gt;, merged on 12 May 2026 and released in &lt;a href="https://github.com/spectreconsole/spectre.console/releases/tag/0.56.0" rel="noopener noreferrer"&gt;0.56.0&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  The bug
&lt;/h2&gt;

&lt;p&gt;The issue's repro is short:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;CoolThing&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;override&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="nf"&gt;ToString&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="s"&gt;"This[contains, braces]."&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;AnsiConsole&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;MarkupLineInterpolated&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;$"I have a &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;thing&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="c1"&gt;// InvalidOperationException: Could not find color or style 'contains,'.&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The detail I liked most in the report was the workaround. Calling &lt;code&gt;{thing.ToString()}&lt;/code&gt; yourself avoids the crash, but the IDE then flags it with IDE0071, "simplify interpolation", because an explicit &lt;code&gt;ToString()&lt;/code&gt; inside an interpolation hole is normally redundant. So the code the analyzer wants is the code that crashes.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where it came from
&lt;/h2&gt;

&lt;p&gt;All the interpolated APIs go through one method:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;internal&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="nf"&gt;EscapeInterpolated&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;IFormatProvider&lt;/span&gt; &lt;span class="n"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;FormattableString&lt;/span&gt; &lt;span class="k"&gt;value&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kt"&gt;object&lt;/span&gt;&lt;span class="p"&gt;?[]&lt;/span&gt; &lt;span class="n"&gt;args&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;GetArguments&lt;/span&gt;&lt;span class="p"&gt;().&lt;/span&gt;&lt;span class="nf"&gt;Select&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;arg&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;arg&lt;/span&gt; &lt;span class="k"&gt;is&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;s&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="n"&gt;s&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;EscapeMarkup&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;arg&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;ToArray&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Format&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Format&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;args&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Strings are escaped. Everything else is handed to &lt;code&gt;string.Format&lt;/code&gt; as it is, which calls &lt;code&gt;ToString()&lt;/code&gt; on it later, after escaping has already happened.&lt;/p&gt;

&lt;p&gt;It doesn't take a contrived class to hit this. Plenty of ordinary .NET types have brackets in their default &lt;code&gt;ToString()&lt;/code&gt;. I ran the same four calls against 0.55.0 and 0.56.0:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;list&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;List&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;int&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="m"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="m"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="m"&gt;3&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;    &lt;span class="c1"&gt;// ToString(): System.Collections.Generic.List`1[System.Int32]&lt;/span&gt;
&lt;span class="kt"&gt;int&lt;/span&gt;&lt;span class="p"&gt;[]&lt;/span&gt; &lt;span class="n"&gt;array&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="m"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="m"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="m"&gt;3&lt;/span&gt;&lt;span class="p"&gt;];&lt;/span&gt;                 &lt;span class="c1"&gt;// ToString(): System.Int32[]&lt;/span&gt;
&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;thing&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;CoolThing&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;             &lt;span class="c1"&gt;// ToString(): This[contains, braces].&lt;/span&gt;
&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="k"&gt;when&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;DateTime&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;2026&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="m"&gt;5&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="m"&gt;12&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="m"&gt;11&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="m"&gt;9&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="m"&gt;0&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="n"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;MarkupInterpolated&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;$"items: &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;list&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="n"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;MarkupInterpolated&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;$"items: &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;array&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="n"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;MarkupInterpolated&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;$"value: &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;thing&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="n"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;MarkupInterpolated&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;$"at &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="k"&gt;when&lt;/span&gt;&lt;span class="p"&gt;:[&lt;/span&gt;&lt;span class="n"&gt;HH&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;mm&lt;/span&gt;&lt;span class="p"&gt;]}&lt;/span&gt;&lt;span class="s"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;== 0.55.0
List&amp;lt;int&amp;gt;                    InvalidOperationException: Encountered malformed markup tag at position 54.
int[]                        InvalidOperationException: Encountered malformed markup tag at position 21.
custom ToString              InvalidOperationException: Could not find color or style 'contains,'.
DateTime with [..] format    InvalidOperationException: Encountered malformed markup tag at position 10.
== 0.56.0
List&amp;lt;int&amp;gt;                    ok
int[]                        ok
custom ToString              ok
DateTime with [..] format    InvalidOperationException: Encountered malformed markup tag at position 10.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The last line is intentional, and I'll come back to it.&lt;/p&gt;

&lt;h2&gt;
  
  
  The fix
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;internal&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="nf"&gt;EscapeInterpolated&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;IFormatProvider&lt;/span&gt; &lt;span class="n"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;FormattableString&lt;/span&gt; &lt;span class="k"&gt;value&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kt"&gt;object&lt;/span&gt;&lt;span class="p"&gt;?[]&lt;/span&gt; &lt;span class="n"&gt;args&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;GetArguments&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
        &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Select&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;arg&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;arg&lt;/span&gt; &lt;span class="k"&gt;switch&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="k"&gt;null&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
            &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;text&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;EscapeMarkup&lt;/span&gt;&lt;span class="p"&gt;(),&lt;/span&gt;
            &lt;span class="n"&gt;IFormattable&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;arg&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
            &lt;span class="n"&gt;_&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;arg&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ToString&lt;/span&gt;&lt;span class="p"&gt;()?.&lt;/span&gt;&lt;span class="nf"&gt;EscapeMarkup&lt;/span&gt;&lt;span class="p"&gt;(),&lt;/span&gt;
        &lt;span class="p"&gt;})&lt;/span&gt;
        &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ToArray&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Format&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Format&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;args&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Each case is there for a reason:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;null&lt;/code&gt; stays &lt;code&gt;null&lt;/code&gt;.&lt;/strong&gt; Calling &lt;code&gt;ToString()&lt;/code&gt; on it would throw, and turning it into an empty string early would hide it from a custom &lt;code&gt;ICustomFormatter&lt;/code&gt; that wants to print something like &lt;code&gt;&amp;lt;null&amp;gt;&lt;/code&gt;. There's a test for exactly that.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;string&lt;/code&gt;&lt;/strong&gt; is escaped, as before.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;IFormattable&lt;/code&gt;&lt;/strong&gt; is passed through untouched. This covers numbers, dates, &lt;code&gt;Guid&lt;/code&gt;, &lt;code&gt;TimeSpan&lt;/code&gt; and any type that understands format strings. If I converted these to strings early, &lt;code&gt;{price:C}&lt;/code&gt; or &lt;code&gt;{date:yyyy-MM-dd}&lt;/code&gt; would lose their format specifier, and culture-specific formatting through the provider would stop working. Their usual output doesn't contain brackets, so passing them through is the safe default.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Everything else&lt;/strong&gt; is converted with &lt;code&gt;ToString()&lt;/code&gt; and escaped. That covers collections, arrays, records and your own classes.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  What this doesn't fix
&lt;/h2&gt;

&lt;p&gt;The &lt;code&gt;IFormattable&lt;/code&gt; exception has a cost, and the last line of the experiment shows it. If a format string itself produces brackets, as in &lt;code&gt;{when:[HH:mm]}&lt;/code&gt;, the output still reaches the markup parser unescaped. Fixing that would mean formatting each &lt;code&gt;IFormattable&lt;/code&gt; with its format string and provider, then escaping the result. That's possible, but &lt;code&gt;GetArguments()&lt;/code&gt; doesn't give you the per-hole format string. You would have to parse &lt;code&gt;value.Format&lt;/code&gt; yourself, which is a much bigger change than the issue asked for. I left it out deliberately, and I'd rather say so here than pretend the problem is gone.&lt;/p&gt;

&lt;p&gt;If you need brackets from a format string, escape them in the format itself (&lt;code&gt;{when:[[HH:mm]]}&lt;/code&gt;) or format the value first and pass the string.&lt;/p&gt;

&lt;h2&gt;
  
  
  Tests
&lt;/h2&gt;

&lt;p&gt;Two tests in &lt;code&gt;MarkupTests&lt;/code&gt;:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;MarkupInterpolated_Should_Not_Throw_When_Object_ToString_Contains_Brackets&lt;/code&gt; uses the class from the issue and asserts both that nothing throws and that the output is exactly &lt;code&gt;This is a This[contains, braces].&lt;/code&gt;. Checking the exact output matters: an escaping bug can also show up as doubled brackets, not just as a crash.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;MarkupInterpolated_Should_Preserve_Null_For_Custom_Formatter&lt;/code&gt; passes a formatter that prints &lt;code&gt;&amp;lt;null&amp;gt;&lt;/code&gt; and checks that it still sees the &lt;code&gt;null&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;a href="https://github.com/patriksvensson" rel="noopener noreferrer"&gt;@patriksvensson&lt;/a&gt; approved it with a "LGTM 👍". It was my second PR to the project, after &lt;a href="https://dev.to/granttotinov/measure-twice-render-once-why-alignwidth-didnt-shrink-a-spectreconsole-panel-2358"&gt;the Align measurement fix&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  References
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;spectreconsole/spectre.console issue &lt;a href="https://github.com/spectreconsole/spectre.console/issues/1763" rel="noopener noreferrer"&gt;#1763&lt;/a&gt;: Interpolation crashes if object contains square brackets.&lt;/li&gt;
&lt;li&gt;spectreconsole/spectre.console PR &lt;a href="https://github.com/spectreconsole/spectre.console/pull/2118" rel="noopener noreferrer"&gt;#2118&lt;/a&gt;: Fix escaping of interpolated arguments in markup.&lt;/li&gt;
&lt;li&gt;Spectre.Console &lt;a href="https://github.com/spectreconsole/spectre.console/releases/tag/0.56.0" rel="noopener noreferrer"&gt;0.56.0 release notes&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;Spectre.Console docs, &lt;a href="https://spectreconsole.net/markup" rel="noopener noreferrer"&gt;Markup&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;Microsoft Learn, &lt;a href="https://learn.microsoft.com/dotnet/fundamentals/code-analysis/style-rules/ide0071" rel="noopener noreferrer"&gt;IDE0071: Simplify interpolation&lt;/a&gt;.&lt;/li&gt;
&lt;/ol&gt;

</description>
      <category>dotnet</category>
      <category>spectreconsole</category>
      <category>csharp</category>
    </item>
    <item>
      <title>Measure twice, render once: why Align.Width didn't shrink a Spectre.Console panel</title>
      <dc:creator>Grant Totinov, M. Eng.</dc:creator>
      <pubDate>Tue, 27 Oct 2026 02:42:27 +0000</pubDate>
      <link>https://dev.to/granttotinov/measure-twice-render-once-why-alignwidth-didnt-shrink-a-spectreconsole-panel-2358</link>
      <guid>https://dev.to/granttotinov/measure-twice-render-once-why-alignwidth-didnt-shrink-a-spectreconsole-panel-2358</guid>
      <description>&lt;p&gt;This was my first contribution to &lt;a href="https://github.com/spectreconsole/spectre.console" rel="noopener noreferrer"&gt;Spectre.Console&lt;/a&gt;: &lt;a href="https://github.com/spectreconsole/spectre.console/pull/2101" rel="noopener noreferrer"&gt;PR #2101&lt;/a&gt;, merged on 25 April 2026 and released in &lt;a href="https://github.com/spectreconsole/spectre.console/releases/tag/0.56.0" rel="noopener noreferrer"&gt;0.56.0&lt;/a&gt;, whose release notes include the line "&lt;a class="mentioned-user" href="https://dev.to/granttotinov"&gt;@granttotinov&lt;/a&gt; made their first contribution". The fix is eight lines. Understanding why those eight lines were needed meant learning how Spectre.Console lays out widgets, and that's what this post is mostly about.&lt;/p&gt;

&lt;h2&gt;
  
  
  The symptom
&lt;/h2&gt;

&lt;p&gt;Issue &lt;a href="https://github.com/spectreconsole/spectre.console/issues/1910" rel="noopener noreferrer"&gt;#1910&lt;/a&gt;, from &lt;a href="https://github.com/LittleLittleCloud" rel="noopener noreferrer"&gt;@LittleLittleCloud&lt;/a&gt;, describes it: put an &lt;code&gt;Align&lt;/code&gt; with an explicit width inside a &lt;code&gt;Panel&lt;/code&gt;, and the panel's border still stretches across the whole console.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="n"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Profile&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Width&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="m"&gt;50&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="n"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Write&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;Panel&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;Align&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Left&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;Text&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"Hello"&lt;/span&gt;&lt;span class="p"&gt;)).&lt;/span&gt;&lt;span class="nf"&gt;Width&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;20&lt;/span&gt;&lt;span class="p"&gt;)));&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Same code, before and after the fix:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;0.55.0
┌────────────────────────────────────────────────┐
│ Hello                                          │
└────────────────────────────────────────────────┘

0.56.0
┌──────────────────────┐
│ Hello                │
└──────────────────────┘
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The second panel is 24 columns wide: 20 for the content, plus one column of padding and one of border on each side.&lt;/p&gt;

&lt;h2&gt;
  
  
  Two passes: measure, then render
&lt;/h2&gt;

&lt;p&gt;Every Spectre.Console widget is an &lt;code&gt;IRenderable&lt;/code&gt; with two methods:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;Measure(options, maxWidth)&lt;/code&gt; returns a &lt;code&gt;Measurement(Min, Max)&lt;/code&gt;: the narrowest the widget can be, and the widest it would like to be, within &lt;code&gt;maxWidth&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;Render(options, maxWidth)&lt;/code&gt; produces the actual segments of text.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Containers like &lt;code&gt;Panel&lt;/code&gt;, &lt;code&gt;Table&lt;/code&gt; and &lt;code&gt;Columns&lt;/code&gt; call &lt;code&gt;Measure&lt;/code&gt; on their children first, decide how wide each child gets, and only then call &lt;code&gt;Render&lt;/code&gt;. A panel that isn't set to expand sizes itself from its child's measurement.&lt;/p&gt;

&lt;p&gt;The base class has a deliberately simple default:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;protected&lt;/span&gt; &lt;span class="k"&gt;virtual&lt;/span&gt; &lt;span class="n"&gt;Measurement&lt;/span&gt; &lt;span class="nf"&gt;Measure&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;RenderOptions&lt;/span&gt; &lt;span class="n"&gt;options&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;int&lt;/span&gt; &lt;span class="n"&gt;maxWidth&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;Measurement&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;maxWidth&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;maxWidth&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;"I want all the space you have." That's a safe default for a widget that doesn't know better, and &lt;code&gt;Align&lt;/code&gt; didn't override it. Its &lt;code&gt;Render&lt;/code&gt; method used &lt;code&gt;Width&lt;/code&gt; correctly, so the text was aligned inside a 20-column area. But when the panel asked how wide it should be, &lt;code&gt;Align&lt;/code&gt; answered "50", and the panel drew its border at 50.&lt;/p&gt;

&lt;h2&gt;
  
  
  The fix
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;protected&lt;/span&gt; &lt;span class="k"&gt;override&lt;/span&gt; &lt;span class="n"&gt;Measurement&lt;/span&gt; &lt;span class="nf"&gt;Measure&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;RenderOptions&lt;/span&gt; &lt;span class="n"&gt;options&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;int&lt;/span&gt; &lt;span class="n"&gt;maxWidth&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;width&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Min&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;Width&lt;/span&gt; &lt;span class="p"&gt;??&lt;/span&gt; &lt;span class="n"&gt;maxWidth&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;maxWidth&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;measurement&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;_renderable&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Measure&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;options&lt;/span&gt; &lt;span class="k"&gt;with&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;Height&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt; &lt;span class="n"&gt;width&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;Measurement&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Min&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;measurement&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Min&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;width&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt; &lt;span class="n"&gt;width&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In words: the width I'll occupy is my explicit &lt;code&gt;Width&lt;/code&gt;, if there is one, capped at what the parent can offer. Ask the child how it measures within that width. Report that width as my maximum, and the child's minimum as my minimum, but never more than my width.&lt;/p&gt;

&lt;p&gt;The issue already sketched an override. The version that got merged differs in that last &lt;code&gt;Math.Min&lt;/code&gt;, and that came from review.&lt;/p&gt;

&lt;h2&gt;
  
  
  What review changed
&lt;/h2&gt;

&lt;p&gt;The first review was automated, from Copilot, and it made two points that both changed the PR.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The minimum has to be clamped too.&lt;/strong&gt; My first version returned &lt;code&gt;new Measurement(measurement.Min, width)&lt;/code&gt;. The review pointed out that a child's &lt;code&gt;Min&lt;/code&gt; can be larger than &lt;code&gt;width&lt;/code&gt;. &lt;code&gt;Paragraph&lt;/code&gt;, for example, doesn't clamp its minimum for unbreakable content, so a long word reports a minimum wider than the space it's given. A measurement where &lt;code&gt;Min &amp;gt; Max&lt;/code&gt; makes no sense, and a &lt;code&gt;Table&lt;/code&gt; or &lt;code&gt;Columns&lt;/code&gt; reading it would reserve more space than the explicit &lt;code&gt;Width&lt;/code&gt; allows, which defeats the point of setting it. Clamping &lt;code&gt;Min&lt;/code&gt; keeps the measurement consistent: &lt;code&gt;Min &amp;lt;= Max == width&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The test has to exercise &lt;code&gt;Measure&lt;/code&gt;, not &lt;code&gt;Render&lt;/code&gt;.&lt;/strong&gt; My first test rendered &lt;code&gt;Align.Left(new Panel("Hello World!")).Width(20)&lt;/code&gt; and checked the output. The review noted that this would pass without the fix, because &lt;code&gt;Align.Render&lt;/code&gt; already respected &lt;code&gt;Width&lt;/code&gt;. The bug only shows up when a parent measures the &lt;code&gt;Align&lt;/code&gt;. The final test calls &lt;code&gt;Measure&lt;/code&gt; directly:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;Fact&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;void&lt;/span&gt; &lt;span class="nf"&gt;Should_Return_Explicit_Width_When_Set&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// Given&lt;/span&gt;
    &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;console&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;TestConsole&lt;/span&gt;&lt;span class="p"&gt;().&lt;/span&gt;&lt;span class="nf"&gt;Size&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;Size&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;40&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="m"&gt;15&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
    &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;align&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;Align&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Left&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;Panel&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"Hello World!"&lt;/span&gt;&lt;span class="p"&gt;)).&lt;/span&gt;&lt;span class="nf"&gt;Width&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;20&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

    &lt;span class="c1"&gt;// When&lt;/span&gt;
    &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;measurement&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="n"&gt;IRenderable&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="n"&gt;align&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Measure&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;RenderOptions&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;console&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt; &lt;span class="m"&gt;40&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

    &lt;span class="c1"&gt;// Then&lt;/span&gt;
    &lt;span class="n"&gt;Assert&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Equal&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;20&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;measurement&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Max&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A test that passes with and without the fix doesn't test the fix. The cheapest check is to run a new test against the old code and watch it fail.&lt;/p&gt;

&lt;h2&gt;
  
  
  The public API snapshot
&lt;/h2&gt;

&lt;p&gt;Spectre.Console keeps a verified snapshot of its entire public API surface (&lt;code&gt;Public_API.Output.verified.txt&lt;/code&gt;), and the build fails if the surface changes without the snapshot being updated. A new &lt;code&gt;protected override&lt;/code&gt; counts as a public API change, because subclasses can see it. I hadn't updated the snapshot, so &lt;a href="https://github.com/patriksvensson" rel="noopener noreferrer"&gt;@patriksvensson&lt;/a&gt; pushed a commit that did, then merged it with "Thank you for your contribution. Much appreciated! 👍". For a first PR to a project, that's about as smooth as it gets. It's still worth looking for snapshot tests like this before opening one.&lt;/p&gt;

&lt;h2&gt;
  
  
  What I'd tell someone writing a Spectre.Console widget
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;If your widget can be narrower than the space it's offered, override &lt;code&gt;Measure&lt;/code&gt;. The default claims everything.&lt;/li&gt;
&lt;li&gt;Keep &lt;code&gt;Measure&lt;/code&gt; and &lt;code&gt;Render&lt;/code&gt; in agreement. If &lt;code&gt;Render&lt;/code&gt; uses a width, &lt;code&gt;Measure&lt;/code&gt; should report the same width.&lt;/li&gt;
&lt;li&gt;Keep &lt;code&gt;Min &amp;lt;= Max&lt;/code&gt;, and clamp anything you get from a child.&lt;/li&gt;
&lt;li&gt;Test measurement directly, or through a parent that depends on it, like &lt;code&gt;Panel&lt;/code&gt;, &lt;code&gt;Table&lt;/code&gt; or &lt;code&gt;Columns&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  References
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;spectreconsole/spectre.console issue &lt;a href="https://github.com/spectreconsole/spectre.console/issues/1910" rel="noopener noreferrer"&gt;#1910&lt;/a&gt;: Align Measure always return maxWidth even when I explicitly set Width.&lt;/li&gt;
&lt;li&gt;spectreconsole/spectre.console PR &lt;a href="https://github.com/spectreconsole/spectre.console/pull/2101" rel="noopener noreferrer"&gt;#2101&lt;/a&gt;: Fix Align measure to respect explicitly set width.&lt;/li&gt;
&lt;li&gt;Spectre.Console &lt;a href="https://github.com/spectreconsole/spectre.console/releases/tag/0.56.0" rel="noopener noreferrer"&gt;0.56.0 release notes&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;Spectre.Console docs, &lt;a href="https://spectreconsole.net/console/widgets/align/" rel="noopener noreferrer"&gt;Align widget&lt;/a&gt;.&lt;/li&gt;
&lt;/ol&gt;

</description>
      <category>dotnet</category>
      <category>spectreconsole</category>
      <category>csharp</category>
    </item>
  </channel>
</rss>
