UseLocalMachineOEMCodePageForFilenames Property (ZipArchive)

In This Topic

Gets or sets a Boolean value that indicates whether the local system's OEM text encoding code page can be used to write filenames in the archive.

Syntax

Visual Basic
C#

'Declaration
 
Public Property UseLocalMachineOEMCodePageForFilenames As Boolean

'Usage
 
Dim instance As ZipArchive
Dim value As Boolean
 
instance.UseLocalMachineOEMCodePageForFilenames = value
 
value = instance.UseLocalMachineOEMCodePageForFilenames

public bool UseLocalMachineOEMCodePageForFilenames {get; set;}

Property Value

true (the default value) if the local system's OEM text encoding code page can be used to write filenames in the archive. false otherwise. In this case, code page 437 is always used.

Remarks

This is an advanced property. It is only useful when dealing with interoperability issues with 3rd party Zip tools and Unicode characters. Unless there is a specific need, the property should be left to its default value.

The Zip format uses the IBM PC character encoding set, commonly referred to as IBM Code Page 437 to write filenames in its headers.

Windows has a registry setting that specifies what OEM code page is to be used for DOS-based programs. The value is located in the value "OEMCP" under registry key "HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage".

On English-based Windows installations, the value is code page 437, which matches the Zip specification. Windows installations in other locales might have different values for this setting. For example, a Vietnamese installation might use value 1258.

As a service to applications based in these other locales, Xceed Zip for .NET uses the code page of the local machine to write file names in headers. This allows, for example, a Vietnamese language based application to use its own special characters in zipped filenames.

With the advent of Unicode, relying on the code page for non-ASCII has become deprecated as it was never an optimal solution in the first place. Zip files created on a machine with a particular code page would not extract the filenames correctly on another machine that uses a different code page.

To preserve existing behavior for long-time users of the component, the default value of this property is to enable the use of the local machine's code page.

In practice, the code page has little to no effect because the component's default behavior is also to include Unicode extra headers that encode the file names and comments as Unicode in archives.

There is one scenario where it is necessary to set this property to false. The component has the ability to use any ASCII character as the fallback conversion when it converts a Unicode filename to ASCII for storage in a zip file. To use this feature, the local machine's code page cannot be used as the component then loses control over the string conversion.

In this case, an application will set the property to false, making the component always use code page 437, and set the desired fallback character to use.

Example

C#
VB.NET

public static void MaximumInteroperability()
{
  /* The path and filename of the zip file itself is not covered by the zip specification's
   * Unicode support. The name of the zip file is determined by your application and is
   * governed by the rules of your operating system. */
  AbstractFile zipFile = new DiskFile( "MaximumInteroperability.zip" );

  // Delete any existing zip file
  if( zipFile.Exists )
    zipFile.Delete();

  // Create a logical zip archive around the zip file
  ZipArchive zip = new ZipArchive( zipFile );

  // Disable the use of any OEM code page mandated by the local machine policy
  zip.UseLocalMachineOEMCodePageForFilenames = false;

  // Specify the '_' character for characters that can't be converted
  zip.UnknownCharacterFallbackConversion = 0x5f; // '_'

  string destinationPath;

  AbstractFile sourceFile = new DiskFile( @"D:\Components\NET40\FileSystem\Dev\Trunk\Tests\UnitTesting\Xceed.Zip.Tests\Data\TinyFile1.txt" );
  using( AutoBatchUpdate batch = new AutoBatchUpdate( zip ) )
  {
    /* We use "universal character names" like \u00C0 instead of using character
     * literals so that the code source file remains an ASCII file and can be read
     * without issue by any editor. */

    destinationPath = "FileNameWithNonASCIIStart\u00C0\u00C9\u044F\u30C6End.dat";

    ZippedFile destinationFile = ( ZippedFile ) zip.GetFile( destinationPath );
    // The string "My comment" in Japanese
    destinationFile.Comment = "\u79C1\u306E\u30B3\u30E1\u30F3\u30C8";
    sourceFile.CopyTo( destinationFile, true );

    destinationPath = "FileNameWithOEMCharsStartéàùïEnd.dat";
    destinationFile = ( ZippedFile ) zip.GetFile( destinationPath );
    sourceFile.CopyTo( destinationFile, true );
  }
}

    Public Shared Sub MaximumInteroperability()
'       The path and filename of the zip file itself is not covered by the zip specification's
'       * Unicode support. The name of the zip file is determined by your application and is
'       * governed by the rules of your operating system. 
      Dim zipFile As AbstractFile = New DiskFile("MaximumInteroperability.zip")

      ' Delete any existing zip file
      If zipFile.Exists Then
        zipFile.Delete()
      End If

      ' Create a logical zip archive around the zip file
      Dim zip As New ZipArchive(zipFile)

      ' Disable the use of any OEM code page mandated by the local machine policy
      zip.UseLocalMachineOEMCodePageForFilenames = False

      ' Specify the '_' character for characters that can't be converted
      zip.UnknownCharacterFallbackConversion = &H5f ' '_'

      Dim destinationPath As String

      Dim sourceFile As AbstractFile = New DiskFile("D:\Components\NET40\FileSystem\Dev\Trunk\Tests\UnitTesting\Xceed.Zip.Tests\Data\TinyFile1.txt")
      Using batch As New AutoBatchUpdate(zip)
'         We use "universal character names" like \u00C0 instead of using character
'         * literals so that the code source file remains an ASCII file and can be read
'         * without issue by any editor. 

        destinationPath = "FileNameWithNonASCIIStart" & ChrW(&H00C0).ToString() & ChrW(&H00C9).ToString() & ChrW(&H044F).ToString() & ChrW(&H30C6).ToString() & "End.dat"

        Dim destinationFile As ZippedFile = CType(zip.GetFile(destinationPath), ZippedFile)
        ' The string "My comment" in Japanese
        destinationFile.Comment = ChrW(&H79C1).ToString() & ChrW(&H306E).ToString() & ChrW(&H30B3).ToString() & ChrW(&H30E1).ToString() & ChrW(&H30F3).ToString() & ChrW(&H30C8).ToString()
        sourceFile.CopyTo(destinationFile, True)

        destinationPath = "FileNameWithOEMCharsStart����End.dat"
        destinationFile = CType(zip.GetFile(destinationPath), ZippedFile)
        sourceFile.CopyTo(destinationFile, True)
      End Using
    End Sub

Supported Frameworks

.NET: net5.0, net5.0-windows, net6.0, net6.0-macos, net6.0-windows, net7.0, net7.0-macos, net7.0-windows, net8.0, net8.0-browser, net8.0-macos, net8.0-windows, net9.0, net9.0-browser, net9.0-macos, net9.0-windows, net10.0, net10.0-browser, net10.0-macos, net10.0-windows.

.NET Standard: netstandard2.0, netstandard2.1

.NET Framework: net20, net35, net40, net403, net45, net451, net452, net46, net461, net462, net463, net47, net471, net472, net48, net481.

Reference

ZipArchive Class
ZipArchive Members
Handling Unicode characters
UnknownCharacterFallbackConversion Property
OEMCP Registry entry [technet.microsoft.com]

Send Feedback

Business Suite

Ultimate Suite

Property Value

Reference