ICustomFormatter 介面
定義
重要
部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。
定義可支援物件值之自訂格式的方法。
public interface class ICustomFormatterpublic interface ICustomFormatter[System.Runtime.InteropServices.ComVisible(true)]
public interface ICustomFormattertype ICustomFormatter = interface[<System.Runtime.InteropServices.ComVisible(true)>]
type ICustomFormatter = interfacePublic Interface ICustomFormatter- 屬性
範例
下列範例會實作 ICustomFormatter ，以允許整數值的二進位、八進位和十六進位格式。 在此範例中，單一類別 MyFormatter 會實作 ICustomFormatter 和 IFormatProvider 。 其 IFormatProvider.GetFormat 方法會判斷參數是否 formatType 代表 ICustomFormatter 類型。 如果確實傳回本身 MyFormatter 的實例，則傳回 ，否則會傳 null 回 。 其 ICustomFormatter.Format 實作會判斷 format 參數是否為三個支援的格式字串之一， ( 「B」 表示二進位、八進位為 「O」，以及十六進位) 的 「H」 是否適當地格式化 arg 參數。 否則，如果 arg 不是 null ，則會呼叫 arg 參數的實作 IFormattable.ToString ，如果存在，則為 ，如果不存在，則呼叫其無 ToString 參數方法。 如果 arg 是 null，則方法會傳回 String.Empty。
using System;
using System.Globalization;
using System.Numerics;
public class MyFormatter : IFormatProvider, ICustomFormatter
{
// IFormatProvider.GetFormat implementation.
public object GetFormat(Type formatType)
{
// Determine whether custom formatting object is requested.
if (formatType == typeof(ICustomFormatter))
return this;
else
return null;
}
// Format number in binary (B), octal (O), or hexadecimal (H).
public string Format(string format, object arg, IFormatProvider formatProvider)
{
// Handle format string.
int baseNumber;
// Handle null or empty format string, string with precision specifier.
string thisFmt = String.Empty;
// Extract first character of format string (precision specifiers
// are not supported).
if (!String.IsNullOrEmpty(format))
thisFmt = format.Length > 1 ? format.Substring(0, 1) : format;
// Get a byte array representing the numeric value.
byte[] bytes;
if (arg is sbyte)
{
string byteString = ((sbyte)arg).ToString("X2");
bytes = new byte[1] { Byte.Parse(byteString, System.Globalization.NumberStyles.HexNumber) };
}
else if (arg is byte)
{
bytes = new byte[1] { (byte)arg };
}
else if (arg is short)
{
bytes = BitConverter.GetBytes((short)arg);
}
else if (arg is int)
{
bytes = BitConverter.GetBytes((int)arg);
}
else if (arg is long)
{
bytes = BitConverter.GetBytes((long)arg);
}
else if (arg is ushort)
{
bytes = BitConverter.GetBytes((ushort)arg);
}
else if (arg is uint)
{
bytes = BitConverter.GetBytes((uint)arg);
}
else if (arg is ulong)
{
bytes = BitConverter.GetBytes((ulong)arg);
}
else if (arg is BigInteger)
{
bytes = ((BigInteger)arg).ToByteArray();
}
else
{
try
{
return HandleOtherFormats(format, arg);
}
catch (FormatException e)
{
throw new FormatException(String.Format("The format of '{0}' is invalid.", format), e);
}
}
switch (thisFmt.ToUpper())
{
// Binary formatting.
case "B":
baseNumber = 2;
break;
case "O":
baseNumber = 8;
break;
case "H":
baseNumber = 16;
break;
// Handle unsupported format strings.
default:
try
{
return HandleOtherFormats(format, arg);
}
catch (FormatException e)
{
throw new FormatException(String.Format("The format of '{0}' is invalid.", format), e);
}
}
// Return a formatted string.
string numericString = String.Empty;
for (int ctr = bytes.GetUpperBound(0); ctr >= bytes.GetLowerBound(0); ctr--)
{
string byteString = Convert.ToString(bytes[ctr], baseNumber);
if (baseNumber == 2)
byteString = new String('0', 8 - byteString.Length) + byteString;
else if (baseNumber == 8)
byteString = new String('0', 4 - byteString.Length) + byteString;
// Base is 16.
else
byteString = new String('0', 2 - byteString.Length) + byteString;
numericString += byteString + " ";
}
return numericString.Trim();
}
private string HandleOtherFormats(string format, object arg)
{
if (arg is IFormattable)
return ((IFormattable)arg).ToString(format, CultureInfo.CurrentCulture);
else if (arg != null)
return arg.ToString();
else
return String.Empty;
}
}
open System
open System.Globalization
open System.Numerics
type MyFormatter() =
interface IFormatProvider with
// IFormatProvider.GetFormat implementation.
member this.GetFormat(formatType: Type) =
// Determine whether custom formatting object is requested.
if formatType = typeof<ICustomFormatter> then
this
else
null
interface ICustomFormatter with
// Format number in binary (B), octal (O), or hexadecimal (H).
member this.Format(format, arg: obj, formatProvider: IFormatProvider) =
// Handle null or empty format string, string with precision specifier.
let thisFmt =
// Extract first character of format string (precision specifiers
// are not supported).
if String.IsNullOrEmpty format |> not then
if format.Length > 1 then
format.Substring(0, 1)
else
format
else
String.Empty
// Get a byte array representing the numeric value.
let bytes =
match arg with
| :? sbyte as arg ->
let byteString = arg.ToString "X2"
Some [| Byte.Parse(byteString, NumberStyles.HexNumber) |]
| :? byte as arg ->
Some [| arg |]
| :? int16 as arg ->
BitConverter.GetBytes arg
|> Some
| :? int as arg ->
BitConverter.GetBytes arg
|> Some
| :? int64 as arg ->
BitConverter.GetBytes arg
|> Some
| :? uint16 as arg ->
BitConverter.GetBytes arg
|> Some
| :? uint as arg ->
BitConverter.GetBytes arg
|> Some
| :? uint64 as arg ->
BitConverter.GetBytes arg
|> Some
| :? bigint as arg ->
arg.ToByteArray()
|> Some
| _ ->
None
let baseNumber =
match thisFmt.ToUpper() with
// Binary formatting.
| "B" -> Some 2
| "O" -> Some 8
| "H" -> Some 16
// Handle unsupported format strings.
| _ -> None
match bytes, baseNumber with
| Some bytes, Some baseNumber ->
// Return a formatted string.
let mutable numericString = String.Empty
for i = bytes.GetUpperBound 0 to bytes.GetLowerBound 0 do
let byteString = Convert.ToString(bytes[i], baseNumber)
let byteString =
match baseNumber with
| 2 ->
String('0', 8 - byteString.Length) + byteString
| 8 ->
String('0', 4 - byteString.Length) + byteString
// Base is 16.
| _ ->
String('0', 2 - byteString.Length) + byteString
numericString <- numericString + byteString + " "
numericString.Trim()
| _ ->
try
this.HandleOtherFormats(format, arg)
with :? FormatException as e ->
raise (FormatException($"The format of '{format}' is invalid.", e))
member private this.HandleOtherFormats(format, arg: obj) =
match arg with
| :? IFormattable as arg ->
arg.ToString(format, CultureInfo.CurrentCulture)
| null ->
String.Empty
| _ ->
string arg
Imports System.Globalization
Imports System.Numerics
Public Class MyFormatter : Implements IFormatProvider, ICustomFormatter
' IFormatProvider.GetFormat implementation.
Public Function GetFormat(formatType As Type) As Object _
Implements IFormatProvider.GetFormat
' Determine whether custom formatting object is requested.
If formatType Is GetType(ICustomFormatter) Then
Return Me
Else
Return Nothing
End If
End Function
' Format number in binary (B), octal (O), or hexadecimal (H).
Public Function Format(fmt As String, arg As Object, _
formatProvider As IFormatProvider) As String _
Implements ICustomFormatter.Format
' Handle format string.
Dim base As Integer
' Handle null or empty format string, string with precision specifier.
Dim thisFmt As String = String.Empty
' Extract first character of format string (precision specifiers
' are not supported by MyFormatter).
If Not String.IsNullOrEmpty(fmt) Then
thisFmt = CStr(IIf(fmt.Length > 1, fmt.Substring(0, 1), fmt))
End If
' Get a byte array representing the numeric value.
Dim bytes() As Byte
If TypeOf(arg) Is SByte Then
Dim byteString As String = CType(arg, SByte).ToString("X2")
bytes = New Byte(0) { Byte.Parse(byteString, System.Globalization.NumberStyles.HexNumber ) }
ElseIf TypeOf(arg) Is Byte Then
bytes = New Byte(0) { CType(arg, Byte) }
ElseIf TypeOf(arg) Is Int16 Then
bytes = BitConverter.GetBytes(CType(arg, Int16))
ElseIf TypeOf(arg) Is Int32 Then
bytes = BitConverter.GetBytes(CType(arg, Int32))
ElseIf TypeOf(arg) Is Int64 Then
bytes = BitConverter.GetBytes(CType(arg, Int64))
ElseIf TypeOf(arg) Is UInt16 Then
bytes = BitConverter.GetBytes(CType(arg, UInt16))
ElseIf TypeOf(arg) Is UInt32 Then
bytes = BitConverter.GetBytes(CType(arg, UInt64))
ElseIf TypeOf(arg) Is UInt64 Then
bytes = BitConverter.GetBytes(CType(arg, UInt64))
ElseIf TypeOf(arg) Is BigInteger Then
bytes = CType(arg, BigInteger).ToByteArray()
Else
Try
Return HandleOtherFormats(fmt, arg)
Catch e As FormatException
Throw New FormatException(String.Format("The format of '{0}' is invalid.", fmt), e)
End Try
End If
Select Case thisFmt.ToUpper()
' Binary formatting.
Case "B"
base = 2
Case "O"
base = 8
Case "H"
base = 16
' Handle unsupported format strings.
Case Else
Try
Return HandleOtherFormats(fmt, arg)
Catch e As FormatException
Throw New FormatException(String.Format("The format of '{0}' is invalid.", fmt), e)
End Try
End Select
' Return a formatted string.
Dim numericString As String = String.Empty
For ctr As Integer = bytes.GetUpperBound(0) To bytes.GetLowerBound(0) Step -1
Dim byteString As String = Convert.ToString(bytes(ctr), base)
If base = 2 Then
byteString = New String("0"c, 8 - byteString.Length) + byteString
ElseIf base = 8 Then
byteString = New String("0"c, 4 - byteString.Length) + byteString
' Base is 16.
Else
byteString = New String("0"c, 2 - byteString.Length) + byteString
End If
numericString += byteString + " "
Next
Return numericString.Trim()
End Function
Private Function HandleOtherFormats(fmt As String, arg As Object) As String
If TypeOf arg Is IFormattable Then
Return DirectCast(arg, IFormattable).ToString(fmt, CultureInfo.CurrentCulture)
ElseIf arg IsNot Nothing Then
Return arg.ToString()
Else
Return String.Empty
End If
End Function
End Class
MyFormatter然後，可以使用 傳遞 物件做為 provider 方法的參數 Format 來提供自訂格式 MyFormatter 設定，如下列範例所示。
public class Example
{
public static void Main()
{
Console.WindowWidth = 100;
byte byteValue = 124;
Console.WriteLine(String.Format(new MyFormatter(),
"{0} (binary: {0:B}) (hex: {0:H})", byteValue));
int intValue = 23045;
Console.WriteLine(String.Format(new MyFormatter(),
"{0} (binary: {0:B}) (hex: {0:H})", intValue));
ulong ulngValue = 31906574882;
Console.WriteLine(String.Format(new MyFormatter(),
"{0}\n (binary: {0:B})\n (hex: {0:H})",
ulngValue));
BigInteger bigIntValue = BigInteger.Multiply(Int64.MaxValue, 2);
Console.WriteLine(String.Format(new MyFormatter(),
"{0}\n (binary: {0:B})\n (hex: {0:H})",
bigIntValue));
}
}
// The example displays the following output:
// 124 (binary: 01111100) (hex: 7c)
// 23045 (binary: 00000000 00000000 01011010 00000101) (hex: 00 00 5a 05)
// 31906574882
// (binary: 00000000 00000000 00000000 00000111 01101101 11000111 10110010 00100010)
// (hex: 00 00 00 07 6d c7 b2 22)
// 18446744073709551614
// (binary: 00000000 11111111 11111111 11111111 11111111 11111111 11111111 11111111 11111110)
// (hex: 00 ff ff ff ff ff ff ff fe)
Console.WindowWidth <- 100
let byteValue = 124uy
String.Format(MyFormatter(), "{0} (binary: {0:B}) (hex: {0:H})", byteValue)
|> printfn "%s"
let intValue = 23045
String.Format(MyFormatter(), "{0} (binary: {0:B}) (hex: {0:H})", intValue)
|> printfn "%s"
let ulngValue = 31906574882uL
String.Format(MyFormatter(), "{0}\n (binary: {0:B})\n (hex: {0:H})", ulngValue)
|> printfn "%s"
let bigIntValue = BigInteger.Multiply(Int64.MaxValue, 2)
String.Format(MyFormatter(), "{0}\n (binary: {0:B})\n (hex: {0:H})", bigIntValue)
|> printfn "%s"
// The example displays the following output:
// 124 (binary: 01111100) (hex: 7c)
// 23045 (binary: 00000000 00000000 01011010 00000101) (hex: 00 00 5a 05)
// 31906574882
// (binary: 00000000 00000000 00000000 00000111 01101101 11000111 10110010 00100010)
// (hex: 00 00 00 07 6d c7 b2 22)
// 18446744073709551614
// (binary: 00000000 11111111 11111111 11111111 11111111 11111111 11111111 11111111 11111110)
// (hex: 00 ff ff ff ff ff ff ff fe)
Public Module Example
Public Sub Main
Console.WindowWidth = 100
Dim byteValue As Byte = 124
Console.WriteLine(String.Format(New MyFormatter(), _
"{0} (binary: {0:B}) (hex: {0:H})", byteValue))
Dim intValue As Integer = 23045
Console.WriteLine(String.Format(New MyFormatter(), _
"{0} (binary: {0:B}) (hex: {0:H})", intValue))
Dim ulngValue As ULong = 31906574882
Console.WriteLine(String.Format(New MyFormatter(), _
"{0} {1} (binary: {0:B}) {1} (hex: {0:H})", _
ulngValue, vbCrLf))
Dim bigIntValue As BigInteger = BigInteger.Multiply(Int64.MaxValue, 2)
Console.WriteLine(String.Format(New MyFormatter(), _
"{0} {1} (binary: {0:B}) {1} (hex: {0:H})", _
bigIntValue, vbCrLf))
End Sub
End Module
' The example displays the following output:
' 124 (binary: 01111100) (hex: 7c)
' 23045 (binary: 00000000 00000000 01011010 00000101) (hex: 00 00 5a 05)
' 31906574882
' (binary: 00000000 00000000 00000000 00000111 01101101 11000111 10110010 00100010)
' (hex: 00 00 00 07 6d c7 b2 22)
' 18446744073709551614
' (binary: 00000000 11111111 11111111 11111111 11111111 11111111 11111111 11111111 11111110)
' (hex: 00 ff ff ff ff ff ff ff fe)
備註
介面 ICustomFormatter 包含單一方法 ICustomFormatter.Format 。 當這個介面由參考或實值型別實作時， Format 方法會傳回物件值的自訂格式字串表示。
一般而言， ICustomFormatter 介面是使用 IFormatProvider 介面來實作，以自訂包含 IFormatProvider 參數的兩個.NET Framework複合字串格式方法的行為。 具體來說， ICustomFormatter 介面可以提供傳遞至 String.Format(IFormatProvider, String, Object[]) 和 StringBuilder.AppendFormat(IFormatProvider, String, Object[]) 方法之物件的自訂格式設定。
提供物件的值自訂表格示法，需要您執行下列動作：
定義實作 ICustomFormatter 介面及其單一成員 的類別， Format 也就是 方法。
定義實作 IFormatProvider 介面及其單一成員 的類別， GetFormat 也就是 方法。 方法會 GetFormat 傳回實 ICustomFormatter 作的實例。 單一類別通常會同時實作 ICustomFormatter 和 IFormatProvider 。 在此情況下，類別的實作
GetFormat只會傳回本身的實例。傳遞 實 IFormatProvider 作做為
provider方法的 String.Format(IFormatProvider, String, Object[]) 引數或可比較的方法。
.NET 程式庫方法接著會使用您的自訂格式設定，而不是自己的格式設定。
給實施者的注意事項
Common Language Runtime 會嘗試針對複合格式字串中的每個格式專案使用您的 ICustomFormatter 實作。 因此，您應該預期會呼叫您的 ICustomFormatter 實作，將格式化服務提供給其未設計用來處理的物件或值。 在這些情況下，您的 Format(String, Object, IFormatProvider) 方法必須針對該物件或值呼叫適當的格式方法。
實作 ICustomFormatter 有兩種：內建和延伸。
內建實作是實作，可提供應用程式定義物件的自訂格式設定。 在此情況下，您的實作應該包含下列專案：
定義物件的格式字串定義。 格式字串是選擇性的。 一般而言，「G」 或 「g」 格式字串會定義一般 (或最常使用) 格式。 不過，您可以自由定義您選擇的任何格式字串。 您也可以自由決定是否區分大小寫或區分大小寫。
測試，以確保傳遞至方法 Format(String, Object, IFormatProvider) 的物件類型是您的應用程式定義型別。 如果不存在，您應該呼叫物件的實作 IFormattable ，如果不存在，則呼叫其 ToString() 方法。 您應該準備好處理這些方法呼叫可能會擲回的任何例外狀況。
如果您的實作支援格式字串，則為處理 Null 格式字串的程式碼。 最常見的方法是以一般格式規範取代 Null 格式字串。
處理實作支援的任何格式字串的程式碼。
處理您不支援的格式字串的程式碼。 最常見的方法是擲回 FormatException ，雖然您可以提供預設格式設定。
延伸模組實作是實作，可為已經支援格式化的類型提供自訂格式設定。 例如，您可以定義 ， CustomerNumberFormatter 以特定數位之間的連字號格式化整數類型。 在此情況下，您的實作應該包含下列專案：
擴充物件格式之格式字串的定義。 這些格式字串是必要的，但不能與類型現有的格式字串衝突。 例如，如果您要擴充類型的格式 Int32 設定，則不應該實作 「C」、「D」、「E」、「F」 和 「G」 格式規範等等。
測試傳遞至 Format(String, Object, IFormatProvider) 方法的物件類型是延伸模組所支援格式的類型。 如果不是，請呼叫物件的實作 IFormattable ，如果有的話，或呼叫物件的無 ToString() 參數方法，如果不存在的話。 您應該準備好處理這些方法呼叫可能會擲回的任何例外狀況。
處理擴充功能所支援之任何格式字串的程式碼。
處理擴充功能不支援的任何格式字串的程式碼。 這些應該傳遞至型別的實作 IFormattable 。 您應該準備好處理這些方法呼叫可能會擲回的任何例外狀況。
方法
| Format(String, Object, IFormatProvider) |
使用指定的格式和特定文化特性的格式資訊，將指定物件的值轉換為相等的字串表示。 |
