.NET 中的數據修訂

編輯或隱藏可協助您清理或掩蓋日誌、錯誤訊息或其他輸出中的敏感資訊。這可讓您遵守隱私權規則並保護敏感數據。它適用於處理個人資料、財務資訊或其他機密數據點的應用程式。

安裝修訂套件

若要開始使用，請安裝 📦 Microsoft.Extensions.Compliance.Redaction NuGet 套件：

.NET CLI
套件參考

dotnet add package Microsoft.Extensions.Compliance.Redaction

或者，如果您使用 .NET 10+ SDK：

dotnet package add Microsoft.Extensions.Compliance.Redaction

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.Compliance.Redaction"
                    Version="*" />
</ItemGroup>

可用的編輯者

編輯人員負責編輯敏感數據。它們會修訂、取代或遮罩敏感性資訊。請考慮圖書館提供的下列可用編輯器：

ErasingRedactor 將任何輸入取代為空字串。
HmacRedactor會使用 HMACSHA256 來編碼要編輯的數據。

使用範例

若要使用內建的編輯器，您需要註冊相關服務。使用其中一個可用 AddRedaction 方法註冊服務，如下列清單所述：

AddRedaction(IServiceCollection)：在IRedactorProvider中註冊IServiceCollection的實作。
AddRedaction(IServiceCollection, Action<IRedactionBuilder>)：在IRedactorProvider中註冊IServiceCollection的實作，並使用指定的configure委派設定 Redactors 可用的。

設定編輯器

在運行時間使用IRedactorProvider獲取redactors。您可以實作您自己的提供者，並將其註冊於 AddRedaction 呼叫中，或使用預設提供者。使用這些IRedactionBuilder方法來設定編輯工具：

// This will use the default redactor, which is the ErasingRedactor
var serviceCollection = new ServiceCollection();
serviceCollection.AddRedaction();

// Using the default redactor provider:
serviceCollection.AddRedaction(redactionBuilder =>
{
    // Assign a redactor to use for a set of data classifications.
    redactionBuilder.SetRedactor<StarRedactor>(
        MyTaxonomyClassifications.Private,
        MyTaxonomyClassifications.Personal);
    // Assign a fallback redactor to use when processing classified data for which no specific redactor has been registered.
    // The `ErasingRedactor` is the default fallback redactor. If no redactor is configured for a data classification then the data will be erased.
    redactionBuilder.SetFallbackRedactor<MyFallbackRedactor>();
});

// Using a custom redactor provider:
builder.Services.AddSingleton<IRedactorProvider, StarRedactorProvider>();

在您的程式代碼中指定此資料分類：

public static class MyTaxonomyClassifications
{
    public static string Name => "MyTaxonomy";

    public static DataClassification Private => new(Name, nameof(Private));
    public static DataClassification Public => new(Name, nameof(Public));
    public static DataClassification Personal => new(Name, nameof(Personal));
}

設定 HMAC 編輯器

使用下列 IRedactionBuilder 方法配置 HMAC 編輯器：

var serviceCollection = new ServiceCollection();
serviceCollection.AddRedaction(builder =>
{
    builder.SetHmacRedactor(
        options =>
        {
            options.KeyId = 1234567890;
            options.Key = Convert.ToBase64String("1234567890abcdefghijklmnopqrstuvwxyz");
        },

        // Any data tagged with Personal or Private attributes will be redacted by the Hmac redactor.
        MyTaxonomyClassifications.Personal, MyTaxonomyClassifications.Private,

        // "DataClassificationSet" lets you compose multiple data classifications:
        // For example, here the Hmac redactor will be used for data tagged
        // with BOTH Personal and Private (but not one without the other).
        new DataClassificationSet(MyTaxonomyClassifications.Personal,
                                  MyTaxonomyClassifications.Private));
});

或者，以下列方式進行設定：

var serviceCollection = new ServiceCollection();
serviceCollection.AddRedaction(builder =>
{
    builder.SetHmacRedactor(
        Configuration.GetSection("HmacRedactorOptions"), MyTaxonomyClassifications.Personal);
});

在您的 JSON 組態檔中包含本節：

{
    "HmacRedactorOptions": {
        "KeyId": 1234567890,
        "Key": "1234567890abcdefghijklmnopqrstuvwxyz"
    }
}

HmacRedactorOptions需要設定其 HmacRedactorOptions.Key 和 HmacRedactorOptions.KeyId 屬性。
Key應為基底 64 格式，且長度至少為 44 個字元。針對服務的每個主要部署使用不同的密鑰。保留密鑰內容秘密，並定期輪替。
KeyId會附加至每個修訂的值，以識別用來哈希數據的索引鍵。
不同的索引鍵識別碼表示值不相關，無法用於相互關聯。

備註

仍 HmacRedactor 處於實驗階段，因此上述方法會導致 EXTEXP0002 警告，指出它尚未穩定。若要使用它，請將新增<NoWarn>$(NoWarn);EXTEXP0002</NoWarn>至項目檔，或圍繞對#pragma warning disable EXTEXP0002的呼叫新增SetHmacRedactor。

設定自訂編輯器

要建立自定義編輯器，請定義繼承自 Redactor 的子類別：

public sealed class StarRedactor : Redactor
{
    private const string Stars = "****";

    public override int GetRedactedLength(ReadOnlySpan<char> input) => Stars.Length;

    public override int Redact(ReadOnlySpan<char> source, Span<char> destination)
    {
        Stars.CopyTo(destination);

        return Stars.Length;
    }
}

建立自定義編輯器供應商

介面 IRedactorProvider 會根據數據分類提供編輯器的實例。若要建立自定義編輯器提供者，請繼承自 IRedactorProvider，如下列範例所示：

using Microsoft.Extensions.Compliance.Classification;
using Microsoft.Extensions.Compliance.Redaction;

public sealed class StarRedactorProvider : IRedactorProvider
{
    private static readonly StarRedactor _starRedactor = new();

    public static StarRedactorProvider Instance { get; } = new();

    public Redactor GetRedactor(DataClassificationSet classifications) => _starRedactor;
}

記錄敏感性資訊

記錄是意外數據暴露的常見來源。個人資料、認證或財務詳細數據等機密資訊絕不應以純文本寫入記錄。若要避免這種情況，請一律在記錄潛在的敏感數據時使用修訂。

記錄敏感數據的步驟

安裝遙測延伸模組套件：安裝Microsoft.Extensions.Telemetry ，才能使用擴充記錄器來啟用修訂功能。
設定修訂：藉由呼叫 AddRedaction(IServiceCollection) 方法，將 redactors 與您的記錄管線整合，以在寫入記錄之前自動清理或遮罩敏感性字段。
識別敏感性字段：瞭解應用程式中哪些數據很敏感，且需要保護，並以適當的數據分類加以標記。
檢閱記錄輸出：定期稽核您的記錄，以確保不會公開任何敏感數據。

範例：在日誌中遮蔽數據

使用 Microsoft.Extensions.Logging 時，您可以結合修訂與記錄，如下所示：

using Microsoft.Extensions.Telemetry;
using Microsoft.Extensions.Compliance.Redaction;

var services = new ServiceCollection();
services.AddLogging(builder =>
{
    // Enable redaction.
    builder.EnableRedaction();
});

services.AddRedaction(builder =>
{
    // configure redactors for your data classifications
    builder.SetRedactor<StarRedactor>(MyTaxonomyClassifications.Private);
});
// Use annotations to mark sensitive data.
// For example, apply the Private classification to SSN data.
[LoggerMessage(0, LogLevel.Information, "User SSN: {SSN}")]
public static partial void LogPrivateInformation(
    this ILogger logger,
    [MyTaxonomyClassifications.Private] string SSN);

public void TestLogging()
{
    LogPrivateInformation("MySSN");
}

輸出應該如下所示：

User SSN: *****

這可確保在記錄之前先修訂敏感數據，降低數據外泄的風險。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-06-07