プロジェクトの共通設定⚓︎

.NET SDKの設定⚓︎

AlesInfiny Maris OSS Edition （以降、 AlesInfiny Maris ）では、 global.json ファイルを用いて、ビルドに利用する .NET SDK のバージョンを設定します。 ソリューションファイルの配置されているフォルダーに、「global.json」という名前のファイルを作成します。 ファイル名は、大文字/小文字まで一致するように作成してください。

global.json ファイルには、ビルドに利用する .NET SDK のバージョンと、指定された .NET SDK バージョンが存在しない場合のロールフォワードポリシーを設定します。

1
2
3
4
5
6

{
  "sdk": {
    "rollForward": "latestMinor",
    "version": "8.0.100"
  }
}

設定値の詳細は、 global.json の概要 を参照してください。

プロジェクトファイルの設定⚓︎

前節 で作成したプロジェクトの設定作業を行います。 AlesInfiny Maris では、各プロジェクトの設定差分がなるべく発生しないよう、 Directory.Build.props ファイルを用いてプロジェクト設定の集約を推奨します。 Directory.Build.props ファイルを用いたプロジェクト設定は、アプリケーション全体に対して適用する設定と、プロダクションコード全体に対して適用する設定、テストコード全体に対して適用する設定の 3 種類を原則用意します。

アプリケーション全体に対するプロジェクト設定⚓︎

ソリューションファイルの配置されているフォルダーに、 「 Directory.Build.props 」という名前のファイルを作成します。 ファイル名は、大文字/小文字まで一致するように作成してください。 以下の設定が有効になるよう、 Directory.Build.props を設定します。

• ImplicitUsings オプション
• Nullable オプション
• ManagePackageVersionsCentrally オプション

また利用するフレームワークのバージョンも設定します。 以下に上記設定を有効にしたプロジェクトファイルの設定例を示します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<Project>

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>

</Project>

著作権表記など、全プロジェクトに対して有効にしたい設定がある場合は、上記に加えて設定してください。

プロダクションコード用のプロジェクト設定⚓︎

プロダクションコードを配置する src フォルダーに、「 Directory.Build.props 」という名前のファイルを作成します。 ルートフォルダーに配置した Directory.Build.props ファイルを上書き設定できるよう、 <import> 要素を定義して、親フォルダーにある Directory.Build.props を読み込んでください。 また以下の設定が有効になるように、プロジェクトファイルを設定します。

• GenerateDocumentationFile オプション

また NeutralLanguage の設定¹ もあわせて行っておくことを推奨します。 上記設定を有効にしたプロジェクトファイルの設定例を示します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<Project>

  <Import Project="$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))" />

  <PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NeutralLanguage>ja-JP</NeutralLanguage>
  </PropertyGroup>

</Project>

テストコード用のプロジェクト設定⚓︎

テストコードを配置する tests フォルダーに、「 Directory.Build.props 」という名前のファイルを作成します。 プロダクションコード用のプロジェクト設定 でも解説した通り、ルートフォルダーに配置した Directory.Build.props ファイルを上書き設定できるよう、 <import> 要素の追加を推奨します。 特に設定する項目がなければ、 tests フォルダーに Directory.Build.props ファイルを追加する必要ありません。

プロジェクトファイルの設定値削除⚓︎

プロジェクトを新規作成したとき、 csproj ファイルには、ここまでに解説した設定と重複するものが自動的に追加されます。 このままでは、 csproj ファイルの設定値が有効になり、せっかく作成した Directory.Build.props ファイルが利用されません。 これまでの手順で行った設定値を参照しながら、 csproj ファイルに個別に設定されている値を削除します。

例えば、コンソールアプリケーションのプロジェクトを作成した場合、 csproj ファイルから削除すべき設定は以下の通りです。 csproj ファイルから設定を削除しても、 Directory.Build.props ファイルの設定が有効になります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

</Project>

パッケージ集中管理の導入⚓︎

.NET アプリケーションでは、NuGet を用いて、様々なパッケージの参照や管理をします。 既定のまま NuGet を用いると、 csproj ファイルに参照する NuGet パッケージのバージョンを設定しなければなりません。 プロジェクト数が少ないうちは、この管理方法でも問題ありませんが、プロジェクト数が増えるにしたがって、管理は煩雑になっていきます。 こういった問題を解消するため、 NuGet 6.2 から パッケージ集中管理 機能が追加されました。 参照するパッケージのバージョンを 1 つのファイルで管理できるため、積極的な活用を推奨します。

パッケージ集中管理の機能を利用するには、アプリケーション全体に対するプロジェクト設定 で解説した ManagePackageVersionsCentrally プロパティを有効にします。 ルートフォルダーの Directory.Build.props ファイルに設定すれば、すべてのプロジェクトに対してこの設定を反映できます。

続いて、ルートフォルダーに「 Directory.Packages.props 」という名前のファイルを作成します。 ファイル名は、大文字/小文字まで一致するように作成してください。 ソリューションをゼロから作成する場合は、以下のように <Project> 要素だけを定義します。

1
2

<Project>
</Project>

開発に Visual Studio を利用している場合は、ソリューションを開きなおして、パッケージ集中管理の機能を有効化してください。 Directory.Packages.props ファイルは、 NuGet を用いて外部のパッケージを参照したとき、自動的に設定が書きこまれます。

静的コード解析用パッケージと設定ファイルの導入⚓︎

コードの品質を一定以上に保つため、静的コード解析ツールを導入します。

.editorconfig⚓︎

複数の開発者で、一貫したコーディングスタイルを維持するために利用します。 また .NET 開発においては、静的コード解析ルールを調整するためにも利用します。

.editorconfig ファイルの配置⚓︎

.editorconfig ファイルを追加すると、ファイルを配置したフォルダーと、その配下のフォルダーすべての該当ファイルに設定値が適用されます。 .editorconfig の設定を下位フォルダーでオーバーライドできます。 オーバーライド設定を記述した .editorconfig ファイルを適用したいフォルダーに配置すると、それ以下のフォルダーでオーバーライドした設定が有効になります。

AlesInfiny Maris の標準的な構成では、ソリューションルートのフォルダーに、アプリケーション全体のコーディングスタイルを設定した .editorconfig ファイルを配置します。 tests フォルダーには、テストコード専用の設定をするための .editorconfig ファイルを作成して全体の設定をオーバーライドします。

.editorconfig ファイルについての詳細は「 EditorConfig で移植可能なカスタム エディター設定を作成する 」を参照してください。

.editorconfig のルール設定⚓︎

ソリューションルートに配置する .editorconfig ファイルは、 Visual Studio を用いて生成したファイルを使用します。 ルールの設定も Visual Studio を用いると、 GUI 上で設定変更できます。 詳細な手順は「 EditorConfig ファイルの追加と削除 」を参照してください。

tests フォルダーに配置するテストコード専用の設定は、原則コード分析ルールの設定のみ行います。 以下に設定例を示します。

1
2
3
4
5

[*.cs]
# Wrapping preferences
dotnet_diagnostic.SA0001.severity=none
dotnet_diagnostic.SA1123.severity=none
dotnet_diagnostic.SA1600.severity=none

1
2
3

[*.cs]
# 自動生成コードなので、警告させない
dotnet_analyzer_diagnostic.severity = none

StyleCop Analyzers⚓︎

複数の開発者で、一貫したコーディングスタイルを維持するために利用します。 .editorconfig では統一しきれない細かなコーディングルールを定義する目的に使用します。

StyleCop Analyzers のインストール⚓︎

StyleCop Analyzers は NuGet パッケージ として提供されています。 StyleCop Analyzers を用いて静的コード解析したいプロジェクトから参照設定を行ってください。 通常はすべてのプロジェクトから参照するように設定します。

stylecop.json ファイルの配置⚓︎

StyleCop Analyzers は、 stylecop.json ファイルを用いてコーディングルールを設定します。 stylecop.json にはソリューション内のすべてのコードに対して適用すべきコーディングルールを設定します。 stylecop.json ファイルはソリューション内にひとつだけ作成し、ソリューションファイルと同じフォルダーに配置します。 stylecop.json の設定方法については 公式ドキュメント を参照してください。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

{
  "$schema": "https://raw.githubusercontent.com/DotNetAnalyzers/StyleCopAnalyzers/master/StyleCop.Analyzers/StyleCop.Analyzers/Settings/stylecop.schema.json",
  "settings": {
    "documentationRules": {
      "companyName": "AlesInfiny Maris",
      "documentInterfaces": true,
      "documentExposedElements": true,
      "documentInternalElements": true,
      "documentPrivateElements": false,
      "documentPrivateFields": false,
      "documentationCulture": "ja-jp",
      "fileNamingConvention": "stylecop",
      "excludeFromPunctuationCheck": [ "seealso" ]
    },
    "indentation": {
      "indentationSize": 4,
      "tabSize": 4,
      "useTabs": false
    },
    "readabilityRules": {
      "allowBuiltInTypeAliases": false
    },
    "orderingRules": {
      "elementOrder": [ "kind", "accessibility", "constant", "static", "readonly" ],
      "systemUsingDirectivesFirst": true,
      "usingDirectivesPlacement": "outsideNamespace",
      "blankLinesBetweenUsingGroups": "allow"
    },
    "namingRules": {
      "allowCommonHungarianPrefixes": true,
      "allowedHungarianPrefixes": [ "db" ],
      "allowedNamespaceComponents": [],
      "includeInferredTupleElementNames": true,
      "tupleElementNameCasing": "PascalCase"
    },
    "maintainabilityRules": {
      "topLevelTypes": [ "class", "struct", "interface", "enum" ]
    },
    "layoutRules": {
      "newlineAtEndOfFile": "allow",
      "allowConsecutiveUsings": true
    }
  }
}

プロジェクトから stylecop.json を参照する⚓︎

stylecop.json は、各プロジェクトのルートフォルダーにあるかのように設定しなければなりません。 同時にコーディングルールの管理負荷軽減のため、 stylecop.json を各プロジェクトに分散配置せず、ソリューション内にひとつだけ配置することが望まれます。 これらを両立するため、各プロジェクトからは、ソリューションルートに配置した stylecop.json をリンクとしてプロジェクトに追加しましょう。 Visual Studio のソリューションエクスプローラーを利用して、 stylecop.json ファイルの [ビルドアクション] プロパティを [C# アナライザー追加ファイル] に設定します。 これにより、 StyleCop Analyzers の設定ファイルであることをコンパイラーに通知できます。

ここまで解説した内容を実施すると、最終的にプロジェクトファイルの設定は以下のようになります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

<Project Sdk="Microsoft.NET.Sdk">

  <!-- StyleCop Analyzers 関連の設定以外省略 -->

  <ItemGroup>
    <AdditionalFiles Include="..\..\stylecop.json" Link="stylecop.json" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="StyleCop.Analyzers">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
  </ItemGroup>
</Project>

1
2
3
4
5
6

<Project>
  <!-- 無関係の部分は省略 -->
  <ItemGroup>
    <AdditionalFiles Include="..\..\stylecop.json" Link="stylecop.json" />
  </ItemGroup>
</Project>

メッセージリソースの追加⚓︎

プロダクションコード用のプロジェクト内で使用するメッセージを管理するために、リソースファイルを追加しましょう。 プロダクションコード用のプロジェクトに [Resources] フォルダーを追加し、その中に [Messages.resx] ファイルを追加します。 例外メッセージやログメッセージなど、プロジェクト内で使用するメッセージは、すべてこのリソースファイルに集約して管理します。

リソースファイルの作成は、 Visual Studio を用いるのが最も簡単です。 詳細な手順は「 .NET アプリ用のリソース ファイルを作成する 」を参照してください。

Visual Studio を用いてリソースファイルを作成すると、リソースファイルに定義したメッセージを取得するコードが自動生成されます。 また Visual Studio の GUI 上で、リソースの公開範囲を指定できます。 リソースの公開範囲は internal にすることを推奨します。 同じメッセージが複数のプロジェクトで使われる場合も、プロジェクトごとにリソースを管理しましょう。