diff --git a/docs/docs/fundamentals/project-structure.md b/docs/docs/fundamentals/project-structure.md
new file mode 100644
index 000000000..4bc13c760
--- /dev/null
+++ b/docs/docs/fundamentals/project-structure.md
@@ -0,0 +1,161 @@
+# Project Structure
+
+This page describes the recommended project structure for projects using MagicOnion.
+
+.NET applications typically consist of a large unit called a solution, which contains .NET projects such as applications and libraries.
+Applications using MagicOnion typically have a server and client project, and are configured to share interfaces through some means.
+
+## Typical structure of a .NET application
+
+Here is an example of a typical project (solution) structure for a .NET application (console app, WPF or .NET MAUI etc).
+
+- **MyApp.sln**: Solution file
+- **MyApp.Server**: MagicOnion server application (ASP.NET Core gRPC Server)
+ - This project provides MagicOnion APIs and processes requests from clients
+- **MyApp.Client**: MagicOnion client application (Console, WPF, WinForms, .NET MAUI, etc...)
+ - This project connects to the MagicOnion server and sends requests
+- **MyApp.Shared**: Shared interface library (.NET library project)
+ - This project contains interface definitions for MagicOnion, such as Hub and Service interface definitions, MessagePack types used in requests/responses, etc.
+
+:::note
+Replace `MyApp` with your project name or solution name.
+:::
+
+The following is an example of directory structure for the above project structure.
+
+```plaintext
+MyApp.sln
+|─ src
+| ├─ MyApp.Server
+| │ ├─ MyApp.Server.csproj
+| | ├─ Hubs
+| | | ├─ ChatHub.cs
+| | └─ Services
+| | └─ GreeterService.cs
+| ├─ MyApp.Client
+| │ ├─ MyApp.Client.csproj
+| │ └─ Program.cs
+| └─ MyApp.Shared
+| ├─ MyApp.Shared.csproj
+| ├─ Hubs
+| | ├─ IChatHub.cs
+| |─ Services
+| | └─ IGreeterService.cs
+| |─ Requests
+| | └─ HelloRequest.cs
+| └─ Responses
+| └─ HelloResponse.cs
+└─ test
+ └─ MyApp.Server.Test
+ └─ ...
+```
+
+`MyApp.Shared` project is created as a .NET class library, references the `MagicOnion.Abstractions` package, and defines only pure interface definitions, data types, and enum types.
+And the `MyApp.Server` and `MyApp.Client` projects share interfaces by referencing the `MyApp.Shared` project.
+
+This is a minimal configuration example, and in actual projects, you may have projects or hierarchies such as models, domains, and ViewModels as needed.
+
+## Unity application structure
+
+Here is an example of a project structure for sharing interfaces between Unity client and server projects.
+
+The structure of a Unity application is different from a typical .NET project in that Unity projects cannot reference .NET library projects.
+This is because Unity projects cannot reference .NET library projects.
+
+The recommended configuration is as follows:
+
+- **MyApp.Server.sln**: Solution file
+- **MyApp.Server**: MagicOnion server application (ASP.NET Core gRPC Server)
+- **MyApp.Unity**: Unity client application
+- **MyApp.Shared**: Shared interface library (.NET library project and Unity local package)
+
+```plaintext
+MyApp.Server.sln
+|─ src
+| ├─ MyApp.Server
+| │ ├─ MyApp.Server.csproj
+| │ ├─ Program.cs
+| │ ├─ Hubs
+| │ │ └─ ChatHub.cs
+| │ └─ Services
+| │ └─ GreeterHub.cs
+| ├─ MyApp.Shared
+| │ ├─ MyApp.Shared.csproj
+| │ ├─ package.json
+| │ ├─ Hubs
+| │ │ └─ IChatHub.cs
+| │ └─ Services
+| │ └─ IGreeterHub.cs
+| └─ MyApp.Unity
+| ├─ Assembly-CSharp.csproj
+| ├─ MyApp.Unity.sln
+| └─ Assets
+| └─ ...
+└─ test
+ └─ MyApp.Server.Test
+ └─ ...
+```
+
+`MyApp.Shared` project is created as a .NET class library, references the `MagicOnion.Abstractions` package, and defines only pure interface definitions, data types, and enum types.
+In addition, it includes a `package.json` to make it available to Unity projects via the Unity Package Manager, and is configured not to output folders such as `bin` and `obj`.
+
+Here is an example of a minimal `package.json` file for a Unity local package.
+
+```json
+{
+ "name": "com.cysharp.magiconion.samples.myapp.shared.unity",
+ "version": "1.0.0",
+ "displayName": "MyApp.Shared.Unity",
+ "description": "MyApp.Shared.Unity",
+}
+```
+
+We recommend creating a `MyApp.Shared.Unity.asmdef` (Assembly Definition) file to define the Unity-specific assembly and to avoid naming conflicts with `MyApp.Shared`. Be careful not to use the same name as `MyApp.Shared` by adding a `.Unity` suffix, for example.
+
+Next, add the following settings to `MyApp.Shared.csproj` to prevent the creation of `bin` and `obj` directories and to hide Unity-specific files from the IDE.
+
+```xml
+
+
+ $(MSBuildThisFileDirectory).artifacts
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+With this configuration, intermediate files and built files are output to `.artifacts`, so if `bin` and `obj` directories are created, delete them.
+
+Next, add a reference to `MyApp.Shared` in the Unity project's `Packages/manifest.json`.
+
+```json
+{
+ "dependencies": {
+ "com.cysharp.magiconion.samples.myapp.shared.unity": "file:../MyApp.Shared/MyApp.Shared.Unity"
+ }
+}
+```
+
+`MyApp.Server` project references the `MyApp.Shared` project to share interfaces. This is similar to a typical .NET application.
+
+### Merging solutions with SlnMerge
+
+By using [SlnMerge](https://github.com/Cysharp/SlnMerge), you can merge the solutions generated by Unity and .NET projects.
+
+For example, MyApp.Server.sln contains MyApp.Server and MyApp.Shared projects, but the solution generated by Unity contains only Unity projects (Assembly-CSharp, Assembly-CSharp-Editor, etc.). By using SlnMerge, you can merge these solutions so that the server project can be seamlessly referenced even when the solution is opened from Unity.
+
+This allows for reference searches and debugger step-ins between Unity and .NET projects, which can improve development experiences.
diff --git a/docs/docs/support.md b/docs/docs/support.md
new file mode 100644
index 000000000..30e94fc9a
--- /dev/null
+++ b/docs/docs/support.md
@@ -0,0 +1,6 @@
+# Support
+MagicOnion provides community-based support. Please use the following resources.
+
+- [GitHub Issues](https://github.com/Cysharp/MagicOnion/issues)
+
+Please report bugs, feature requests, questions, and other issues here. Community support does not guarantee response times or feature requests.
diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts
index 3bcd8fe4f..9473286a5 100644
--- a/docs/docusaurus.config.ts
+++ b/docs/docusaurus.config.ts
@@ -51,7 +51,7 @@ const config: Config = {
routeBasePath: '/',
sidebarPath: './sidebars.ts',
- sidebarCollapsed: false,
+ sidebarCollapsed: true,
showLastUpdateTime: true,
@@ -59,8 +59,8 @@ const config: Config = {
? `https://github.com/Cysharp/MagicOnion/tree/main/docs/docs/${params.docPath}`
: `https://github.com/Cysharp/MagicOnion/tree/main/docs/i18n/${params.locale}/docusaurus-plugin-content-docs/current/${params.docPath}`,
- remarkPlugins: [additionalHeaderMetaRow],
- },
+ remarkPlugins: [additionalHeaderMetaRow],
+ },
theme: {
customCss: './src/css/custom.css',
},
@@ -91,6 +91,12 @@ const config: Config = {
label: 'License',
docId: 'license',
},
+ {
+ type: 'doc',
+ position: 'left',
+ label: 'Support',
+ docId: 'support',
+ },
{
href: 'https://cysharp.co.jp/en/',
label: 'Cysharp, Inc.',
diff --git a/docs/i18n/ja/docusaurus-plugin-content-docs/current.json b/docs/i18n/ja/docusaurus-plugin-content-docs/current.json
index 44166f891..1206d6941 100644
--- a/docs/i18n/ja/docusaurus-plugin-content-docs/current.json
+++ b/docs/i18n/ja/docusaurus-plugin-content-docs/current.json
@@ -39,6 +39,10 @@
"message": "インテグレーション",
"description": "The label for category Integration in sidebar docsSidebar"
},
+ "sidebar.docsSidebar.category.Best practices": {
+ "message": "ベストプラクティス",
+ "description": "The label for category Best practices in sidebar docsSidebar"
+ },
"sidebar.docsSidebar.category.Source Generator": {
"message": "Source Generator",
"description": "The label for category Source Generator in sidebar docsSidebar"
diff --git a/docs/i18n/ja/docusaurus-plugin-content-docs/current/fundamentals/project-structure.md b/docs/i18n/ja/docusaurus-plugin-content-docs/current/fundamentals/project-structure.md
new file mode 100644
index 000000000..126b23198
--- /dev/null
+++ b/docs/i18n/ja/docusaurus-plugin-content-docs/current/fundamentals/project-structure.md
@@ -0,0 +1,162 @@
+# プロジェクト構成
+
+このページでは MagicOnion を使用したプロジェクトの推奨構成について解説します。
+
+.NET アプリケーションでは一般的にソリューションという大きな単位があり、その中にアプリケーションやライブラリーなど .NET のプロジェクトが含まれる形で構成されます。
+MagicOnion を使用するアプリケーションはその性質上、最低限サーバーとクライアントのプロジェクトが存在し、何らかの手段でインターフェースを共有するといった構成がとられます。
+
+## 典型的な .NET アプリケーションの構成
+
+ここでは典型的な .NET クライアント (コンソールアプリケーションや WPF、.NET MAUI など) とサーバー、そしてインターフェースを共有する構成例について解説します。
+
+典型的な .NET アプリケーションでのプロジェクト(ソリューション)構成は以下のようになります。
+
+- **MyApp.sln**: ソリューションファイル
+- **MyApp.Server**: MagicOnion サーバーアプリケーション (ASP.NET Core gRPC Server)
+ - このプロジェクトは MagicOnion の API を提供し、クライアントからのリクエストを処理するサーバーアプリケーションです
+- **MyApp.Client**: MagicOnion クライアントアプリケーション (Console, WPF, WinForms, .NET MAUI, etc...)
+ - このプロジェクトは MagicOnion サーバーに接続し、リクエストを送信するクライアントアプリケーションです
+- **MyApp.Shared**: インターフェース共有ライブラリー (.NET ライブラリープロジェクト)
+ - このプロジェクトには MagicOnion 向けのインターフェース定義が含まれます。例えば Hub や Service のインターフェース定義、リクエスト/レスポンスで使用される MessagePack の型などです
+
+:::note
+MyApp は任意の名前で、プロジェクト名やソリューション名に置き換えてください。
+:::
+
+下記は上記の構成でのファイルの配置例です。
+
+```plaintext
+MyApp.sln
+|─ src
+| ├─ MyApp.Server
+| │ ├─ MyApp.Server.csproj
+| | ├─ Hubs
+| | | ├─ ChatHub.cs
+| | └─ Services
+| | └─ GreeterService.cs
+| ├─ MyApp.Client
+| │ ├─ MyApp.Client.csproj
+| │ └─ Program.cs
+| └─ MyApp.Shared
+| ├─ MyApp.Shared.csproj
+| ├─ Hubs
+| | ├─ IChatHub.cs
+| |─ Services
+| | └─ IGreeterService.cs
+| |─ Requests
+| | └─ HelloRequest.cs
+| └─ Responses
+| └─ HelloResponse.cs
+└─ test
+ └─ MyApp.Server.Test
+ └─ ...
+```
+
+`MyApp.Shared` プロジェクトは .NET クラスライブラリーとして作成し、`MagicOnion.Abstractions` パッケージを参照し、純粋なインターフェースの定義やデータ型、列挙型のみを定義します。
+そして `MyApp.Server` と `MyApp.Client` プロジェクトはそれぞれ `MyApp.Shared` プロジェクトをプロジェクト参照することでインターフェースを共有します。
+
+これは最低限の構成の例であり、実際のプロジェクトでは必要に応じてモデルやドメイン、ViewModel などのプロジェクトや階層を持つことがあります。
+
+## Unity アプリケーションの構成
+
+ここでは Unity クライアントとサーバー、そしてインターフェースを共有する構成例について解説します。
+
+Unity アプリケーションでの構成は Unity プロジェクトとサーバー (.NET) プロジェクトでのインターフェースを共有する方法が典型的な .NET プロジェクトと異なります。
+これは Unity プロジェクトからは .NET ライブラリープロジェクトを参照できないといった理由によります。
+
+推奨する構成は以下のようになります。
+
+- **MyApp.Server.sln**: ソリューションファイル
+- **MyApp.Server**: MagicOnion サーバーアプリケーション (ASP.NET Core gRPC Server)
+- **MyApp.Unity**: Unity クライアントアプリケーション
+- **MyApp.Shared**: インターフェース共有ライブラリー (.NET ライブラリープロジェクト兼 Unity ローカルパッケージ)
+
+```plaintext
+MyApp.Server.sln
+|─ src
+| ├─ MyApp.Server
+| │ ├─ MyApp.Server.csproj
+| │ ├─ Program.cs
+| │ ├─ Hubs
+| │ │ └─ ChatHub.cs
+| │ └─ Services
+| │ └─ GreeterHub.cs
+| ├─ MyApp.Shared
+| │ ├─ MyApp.Shared.csproj
+| │ ├─ package.json
+| │ ├─ Hubs
+| │ │ └─ IChatHub.cs
+| │ └─ Services
+| │ └─ IGreeterHub.cs
+| └─ MyApp.Unity
+| ├─ Assembly-CSharp.csproj
+| ├─ MyApp.Unity.sln
+| └─ Assets
+| └─ ...
+└─ test
+ └─ MyApp.Server.Test
+ └─ ...
+```
+
+MyApp.Shared プロジェクトは .NET クラスライブラリーとして作成し、`MagicOnion.Abstractions` パッケージを参照し、純粋なインターフェースの定義やデータ型、列挙型のみを定義します。加えて Unity プロジェクトから Unity Package Manager によって参照できるように `package.json` を含め、`bin`, `obj` といったフォルダーを出力しないように構成します。
+
+`package.json` の内容は下記のような最小構成の JSON ファイルです。
+
+```json
+{
+ "name": "com.cysharp.magiconion.samples.myapp.shared.unity",
+ "version": "1.0.0",
+ "displayName": "MyApp.Shared.Unity",
+ "description": "MyApp.Shared.Unity",
+}
+```
+
+アセンブリーを分割するために `MyApp.Shared.Unity.asmdef` (Assembly Definition) ファイルを追加することもお勧めします。`.Unity` サフィックスを付けるなど `MyApp.Shared` と完全に同じ名前にならないように注意してください。
+
+次に `MyApp.Shared.csproj` に下記のような設定を追加します。`bin`, `obj` ディレクトリーを作成しないようにする設定と Unity 向けのファイルを IDE 上に表示しないようにする設定です。
+
+```xml
+
+
+ $(MSBuildThisFileDirectory).artifacts
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+この設定により中間ファイルやビルド済みファイルは `.artifacts` 以下に出力されるようになるため、`bin`, `obj` ディレクトリーが作成されている場合は削除してください。
+
+次に Unity プロジェクトの `Packages/manifest.json` に MyApp.Shared への参照を追加します。
+
+```json
+{
+ "dependencies": {
+ "com.cysharp.magiconion.samples.myapp.shared.unity": "file:../MyApp.Shared/MyApp.Shared.Unity"
+ }
+}
+```
+
+MyApp.Server プロジェクトからは MyApp.Shared プロジェクトをプロジェクト参照することでインターフェースを共有します。これは典型的な .NET アプリケーションの場合と同様です。
+
+### SlnMerge によるソリューションの統合
+
+[SlnMerge](https://github.com/Cysharp/SlnMerge) という Unity 向けのエディター拡張を使用することで Unity が生成するソリューションと .NET プロジェクトのソリューションを統合できます。
+
+例えば MyApp.Server.sln には MyApp.Server と MyApp.Shared プロジェクトが含まれますが、Unity で生成されるソリューションには Unity 向けのプロジェクト (Assembly-CSharp, Assembly-CSharp-Editor など) のみが含まれます。SlnMerge を使用することでこれらのソリューションを統合し、Unity からソリューションを開いた場合でもシームレスにサーバープロジェクトを参照できるようになります。
+
+これにより Unity と .NET プロジェクト間での参照検索やデバッガーステップインなどが可能となり開発効率を改善できる場合があります。
diff --git a/docs/i18n/ja/docusaurus-plugin-content-docs/current/license.md b/docs/i18n/ja/docusaurus-plugin-content-docs/current/license.md
new file mode 100644
index 000000000..2bf08e109
--- /dev/null
+++ b/docs/i18n/ja/docusaurus-plugin-content-docs/current/license.md
@@ -0,0 +1,25 @@
+# ライセンス
+MagicOnion は MIT License に基づき提供されます。
+
+```plaintext
+Copyright (c) Yoshifumi Kawai
+Copyright (c) Cysharp, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
diff --git a/docs/i18n/ja/docusaurus-plugin-content-docs/current/support.md b/docs/i18n/ja/docusaurus-plugin-content-docs/current/support.md
new file mode 100644
index 000000000..62b1f374c
--- /dev/null
+++ b/docs/i18n/ja/docusaurus-plugin-content-docs/current/support.md
@@ -0,0 +1,14 @@
+# サポート
+MagicOnion はコミュニティーベースのサポートを提供しています。以下のリソースをご利用ください。
+
+- [GitHub Issues](https://github.com/Cysharp/MagicOnion/issues)
+
+バグ報告、機能リクエスト、質問、その他の問題についての報告はこちらで受け付けています。コミュニティーでのサポートは対応時間や機能リクエストへの対応を約束するものではありません。
+
+## 有償でのサポート
+株式会社 Cysharp では C# に関する技術コンサルティングを提供しています。
+
+- MagicOnion の導入や設計に関するサポート
+- 主に C# を中心とした Unity や .NET アプリケーション開発に関する技術コンサルティング
+
+採用実績や詳細については [Cysharp のウェブサイト](https://cysharp.co.jp/) からお気軽にお問い合わせください。(現在、日本語での対応のみとなります)
diff --git a/docs/i18n/ja/docusaurus-theme-classic/navbar.json b/docs/i18n/ja/docusaurus-theme-classic/navbar.json
index e7d3b8ec1..66df31360 100644
--- a/docs/i18n/ja/docusaurus-theme-classic/navbar.json
+++ b/docs/i18n/ja/docusaurus-theme-classic/navbar.json
@@ -7,6 +7,14 @@
"message": "Documents",
"description": "Navbar item with label Documents"
},
+ "item.label.License": {
+ "message": "License",
+ "description": "Navbar item with label License"
+ },
+ "item.label.Support": {
+ "message": "Support",
+ "description": "Navbar item with label Support"
+ },
"item.label.GitHub": {
"message": "GitHub",
"description": "Navbar item with label GitHub"
diff --git a/docs/sidebars.ts b/docs/sidebars.ts
index b133d70ae..aa0113039 100644
--- a/docs/sidebars.ts
+++ b/docs/sidebars.ts
@@ -23,6 +23,7 @@ const sidebars: SidebarsConfig = {
{
type: 'category',
label: 'Installation',
+ collapsed: false,
items: [
'installation/packages',
'installation/unity'
@@ -31,7 +32,6 @@ const sidebars: SidebarsConfig = {
{
type: 'category',
label: 'What\'s new',
- collapsed: true,
items: [
'release-notes/7.0',
],
@@ -39,8 +39,10 @@ const sidebars: SidebarsConfig = {
{
type: 'category',
label: 'Fundamentals',
+ collapsed: false,
items: [
'fundamentals/unary-or-streaminghub',
+ 'fundamentals/project-structure',
'fundamentals/exceptions-and-status-codes',
'fundamentals/authentication',
'fundamentals/lifecycle',
@@ -126,7 +128,7 @@ const sidebars: SidebarsConfig = {
'advanced/memorypack',
'advanced/raw-grpc'
]
- }
+ },
],
};