構成ファイルリファレンス – Preemptive Support Center Japanese

Dotfuscator 構成ファイルには、指定したアプリケーションがどのように保護されるかについての情報が含まれています。構成ファイルは dotfuscator_v2.6.dtd（またはそれ以前のもの）に準拠する XML ドキュメントで、通常はファイル拡張子が .xml です。

このページでは Dotfuscator の構成ファイルの書式、さまざまな構成オプションについて詳しく説明します。テキストエディターで構成ファイルを編集するときには、このページをガイダンスとしてお使いください。構成ファイルを扱う方法はほかにもあり、たとえば、MSBuild ターゲットやコマンドパレットを使って構成ファイルを生成することができます。

プロパティリストとプロパティ

<propertylist>（プロパティリスト）セクションは省略可能であり、構成ファイルで後から利用される可能性のある（<プロパティ> と呼ばれる）変数の定義および値の代入を行うことができます。このセクションで定義したプロパティ定義は、構成プロパティと呼ばれます。

構成プロパティ：

<!-- 拡張可能なプロパティを定義します -->
<!-- 省略可能 -->
<propertylist>
  <property name="name" value="myapp"/>
  <property name="outdir" value="c:\myapp\out"/>
</propertylist>

変数またはプロパティ参照は、このセクション内で定義しなくても、構成ファイル内で使用することはできます。たとえば、コマンドラインで変数を定義したり、環境変数を利用することができます。プロパティは、次のアルゴリズムを使用してそのプロパティに関連付けられた値を検索し、文字列の置き換えを行うことによって機能します。

外部のプロパティリストで値を確認します。
見つからない場合は、プロパティと同じ名前の環境変数を確認します。
それでも見つからない場合は、構成ファイルの propertylist セクションに構成の定義がないかどうかをチェックします。
それでも見つからない場合は、値に空の文字列を使用します。

プロパティは、構成ファイルの作成に役立ちます。この構成ファイルは、複数のアプリケーションや同じアプリケーションのさまざまなバージョン、あるいはさまざまなビルド環境間での移植を容易にするテンプレートとしての役割を果たします。プロパティは、次の構文で参照されます。

プロパティの構文：

${property_name}

プロパティ参照は大文字と小文字を区別するので、${OutDir} は ${outdir} とは異なるプロパティを参照します。プロパティ値は、ほかのプロパティ値を参照することがあります。

プロパティ参照は、構成ファイル内のその他の場所では文字どおりに解釈されます。

プロパティ参照の使用例：

<output>
  <file dir="${testdir}/output"/>
</output>

グローバルオプションセクション

グローバルオプションセクションは、実行全体にわたって適用する構成オプションを定義するためにあります。このセクションでは、各オプションについて詳しく説明します。

メモ：オプションは大文字と小文字を区別しません

Verbose、Quiet、Investigate オプション

これらのオプションは、対応するコマンドラインオプションと同じであり、構成ファイルまたはコマンドラインを使って有効にすることができます。コマンドラインからオプションの設定を解除する方法はありません。

Verbose、Quiet、Investigate オプション：

<global>
    <!-- 詳細表示モードで実行します -->
    <option>verbose</option>
    <!-- メッセージ非表示モードで実行します -->
    <option>quiet</option>
    <!-- 調査のみを実行して割り当てファイルを生成します -->
    <option>investigate</option>
</global>

SuppressIldasm グローバルオプション

このオプションを設定することにより、Microsoft の ILdasm ユーティリティがアセンブリ IL を表示しないよう Dotfuscator に指示します。これは .NET 2.0 以上を対象とするアセンブリにのみ有効です。

SuppressIldasm グローバルオプション：

<global>
    <option>suppressildasm</option>
</global>

入力アセンブリリスト

入力アセンブリリストには、難読化するアセンブリおよび/またはパッケージのファイル名とディレクトリを含めます。また、パッケージまたはアセンブリレベルで設定する構成オプションもここに含めます。

複数のモジュールから成るアセンブリの場合は、マニフェストを持つモジュールだけを含めます。

入力アセンブリリスト：

<input>
    <asmlist>
      <inputassembly>
        ...
        <file dir="c:\temp" name="myproj.dll"/>
      </inputassembly>
      ...
    </asmlist>
</input>

アセンブリ単位のライブラリモード

入力アセンブリにライブラリモードを指定するために、その入力アセンブリの <inputassembly> 要素に library オプションが自動的に追加されます。

<inputassembly>
  <option>library</option>
  ...
</inputassembly>

メモ：アセンブリのライブラリモードを無効にするには、option タグをコメントアウトするか削除するだけです

アセンブリ単位の宣言による難読化

宣言による難読化の有効化と無効化

入力アセンブリに対する宣言による難読化を有効にするには、その入力アセンブリの <inputassembly> 要素に honoroas オプションを追加します。

<inputassembly>
  <option>honoroas</option>
  ...
</inputassembly>

難読化属性の除去

入力アセンブリに対する難読化属性の除去を有効にするには、その入力アセンブリの <inputassembly> 要素に stripoa オプションを追加します。

<inputassembly>
  <option>stripoa</option>
  ...
</inputassembly>

アセンブリ単位の XAML の変換モード

この設定は、特定の入力アセンブリに次のマークアップを含めることができることを Dotfuscator に示します。そのマークアップは、ユニバーサル Windows アプリケーションで用いられる XAML、あるいは Windows Presentation Foundation アプリケーションで用いられるコンパイル済みの XAML リソース（BAML）です。いずれのマークアップも、名前変更のために分析され対象に加えられます。Dotfuscator で処理するため、変換されるマークアップは要素の分離コード参照とともに名前変更される識別子を持ちます。マークアップリソースから参照されるプロパティは、そのプロパティメタデータは保持されますが、名前が変更されます。

入力アセンブリに XAML の変換モードを指定するには、その入力アセンブリの <inputassembly> 要素に <option> 要素を追加します。

アセンブリ単位の XAML の変換モード：

<inputassembly>
  <option>transformxaml</option>
</inputassembly>

詳細については、TransformXaml を参照してください。

出力ディレクトリ

これは、出力アセンブリが書き込まれるディレクトリです。アプリケーションは無条件に、このディレクトリにあるファイルを常に上書きします。

出力ディレクトリ：

<output>
    <file dir="c:\work"/>
</output>

名前の変更セクション

名前の変更セクションでは、ユーザーは入力割り当てファイルおよび出力割り当てファイルの場所や、名前の変更から項目を除外するための詳細な規則など、名前の変更に固有のオプションを指定できます。

名前の変更セクションは省略可能です。このセクションが存在しない場合は、以下の既定の処理が適用されます。

既定の名前の変更が行われます（名前空間は削除されます）。
lowalpha の名前変更規則を使って新しい名前が選択されます。
割り当てファイルは {CurrentWorkingDir}/Dotfuscator/Map.xml に書き込まれます。
アプリケーションの種類に従って行われる対象除外以上の除外は行われません。

名前の変更オプション

disable オプションを使用すると、名前の変更セクションの残りの部分の内容に関係なく、Dotfuscator は名前の変更をまったく行いません。

名前の変更の無効オプション：

<renaming>
    <!--本セクションの残り部分を無視し、名前の変更処理をスキップします-->
    <option>disable</option>
    ...
</renaming>

Dotfuscator には、名前の変更アルゴリズムが名前空間を処理する方法を決定するためのオプションがいくつか用意されています。すなわち、"keepnamespace" と "keephierarchy" です。これらについては、識別子の名前の変更で詳しく説明します。

XML シリアライザーと互換性のある方法で型やメンバーの名前を変更するように、名前の変更アルゴリズムを変更することができます。

名前の変更アルゴリズムを変更して XML シリアライザーとの互換性を保つ：

<renaming>
    <!--  XML シリアル化の互換性 -->
    <option>xmlserialization</option>
    ...
</renaming>

keepManagedResourceNames オプションを使用すると、マネージリソースの名前が変更されないようにすることができます。

<renaming>
    <!--  このオプションでマネージ リソースの名前が変更されないようにします -->
    <option>keepManagedResourceNames</option>
    ...
</renaming>

メモ：名前の変更オプションは、大文字と小文字を区別しません。

名前の変更の対象除外

特定のコーディング規約のために、多数の特定の対象除外を作成しなければならない状況がある可能性があります。作成した後も、開発者はその規約に従うコードを追加した場合には、その新しいコードのために、さらにもう 1 つ特定の対象除外を作成することを覚えておかなければなりません。

これの解決策が、カスタム対象除外規則です。型名が "Dungeon" で終わるすべての型と、それらの型内の特定の型のフィールドは、何らかの理由で名前の変更対象から除外される必要があることがわかったとします。多数の特定の対象除外を作成するかわりに、次のように 1 つのカスタム規則を作成することができます。

Name フィールドに .*Dungeon と入力します。
regex を true として、この名前を正規表現として扱う必要があることを示します。これにより、ノードは、型名が "Dungeon" で終わる型と一致します。
子ノードを追加して名前を .* とし、この名前を正規表現として扱う必要があることを示します。
パブリックアクセス修飾子を持ち（speclist を +public として設定する）、署名が string[] であるフィールドのみを対象とするように規則を制限します。このシナリオには両方が必要です。

この例では、次のような構成が生成されます。

<excludelist>
   <type name=".*Dungeon" regex="true">
       <field name=".*" speclist="+public" signature="string[]"          
   regex="true" />
</excludelist>

さらに例を挙げると、System.Web.Services 属性を持つメソッドは、次のカスタム規則に変換されます。

<excludelist>
  <type name=".*" regex="true" excludetype="false">
    <comment>System.Web.services 名前空間の属性で修飾された 
 すべてのメソッドを除外します。</comment>
    <method name=".*" regex="true">
      <customattribute name="System.Web.Services.*" regex="true" />
    </method>
  </type>
</excludelist>

詳細については、対象除外規則を参照してください。

出力割り当てファイル

この機能は、特定の実行中に Dotfuscator が使用したすべての名前の変更割り当てのログを作成します。これは、統計セクションも提供します。

このオプションを指定することで、Dotfuscator の名前の変更機能に対し、名前の変更がどのように行われたかを追跡記録するよう指示できます。その結果、ユーザーは名前の変更状況をすぐに調査できるほか、今後 Dotfuscator を実行する際に入力として使用することができます。

<renaming>
    ...
    <mapping>
          <file dir="c:\work" name="testout.xml"/>
        </mapoutput>
    </mapping>
</renaming>

SmartObfuscation

スマート難読化により、Dotfuscator はアプリケーションの種類に特有の規則に基づいて、名前の変更や除去を実行できない要素を自動検出できるようになります。スマート難読化は既定で有効に設定されており、ほとんどの場合は有効にしておく必要があります。ユーザーが積極的な難読化を行ってもアプリケーションを損なわないと確信している場合には、このセクションで disable オプションを設定することにより、無効することができます。

スマート難読化にはレポート機能が用意されており、このセクションでレポートの詳細を構成できます。verbosity 属性に指定できる値は all、warningsonly、および none です。既定値は all です。

スマート難読化レポートは、任意でディスクに書き出すことができます。Dotfuscator は同じ名前の既存のスマート難読化レポートが検出された場合には、自動的にそのレポートの名前を変更してから、新しいレポートで既存レポートを上書きします。

SmartObfuscation：

<smartobfuscation>
  <!-- 本セクションの残り部分を無視し、スマート難読化処理をスキップします -->
  <option>disable</option>
  <smartobfuscationreport verbosity="all" overwrite="true">
    <!-- 出力レポート ファイルの指定は任意です -->
    <file dir="c:\myapp" name="smartobfuscation.xml"/>
  </smartobfuscationreport>
</smartobfuscation>

チェックの構成

各チェックは、アプリケーションコード内の 1 つまたは複数のメソッドを対象とします。これらのメソッドはチェックの場所と呼ばれ、<type name> タグで指定されます。

チェックが差し込まれる場所は、次のように指定することで、プロジェクト構造に従います。
プロジェクト名 ->差し込みが行われるクラス -> 差し込みが行われるクラス内のメソッドと指定します。

メソッドの署名も指定する必要があります。署名とは、メソッドの戻り値の型とパラメーターのことです。たとえば、次のようになります。

戻り値の型が void で、パラメーターがないメソッドの署名は void() です。文字列パラメーターが 2 つある場合の署名は void(string,string)、整数パラメーターが 1 つある場合の署名は void(int) となります。

チェックの例：

<sos />
  <extattributes>
        </extattribute>
    <extattribute name="PreEmptive.Attributes.TamperCheckAttribute"> 
// この属性は改ざんチェックをアクティブ化します。属性を次のように変更することもできます。 
PreEmptive.Attributes.DebuggingCheckAttribute -> デバッグ チェックの場合
PreEmptive.Attributes.RootCheckAttribute -> ルート チェックの場合
PreEmptive.Attributes.ShelfLifeCheckAttribute -> Shelf Life チェックの場合
      <type name="<projectname>.<class>"> // プロジェクト名とクラスを置き換えます。例：                
                                              "DotfuscatorCommunitySample.Hello"
        <method name="<methodname>" signature="void()" /> // <methodname> を 
         差し込みを行うメソッドの名前と置き換えます。例："LogIn"
      </type>
      <propertylist>
        <property name="Action" value="Exit" /> // 詳細は Action 値をお読みください 
        <property name="ActionProbability" value="1" /> // 詳細は操作の確率をお読みください 
        <property name="ApplicationNotificationSinkName" value="" /> 
        <property name="ApplicationNotificationSinkOwner" value="" />
        <property name="ApplicationNotificationSinkElement" value="None" />
      </propertylist>
    </extattribute>
</extattributes>

1 つのプロジェクトで複数のチェックを有効にするには、それらを <extattributes> タグ内に含める必要があります。

たとえば、次のように記述します。

<sos />
  <extattributes>
        </extattribute>
                  …..
       </extattribute>
       </extattribute>
                 …..
       </extattribute>
  </extattributes>

プロパティ リストとプロパティ

グローバル オプション セクション