# 画面設計書 73-サーバーロールメンバー

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける「サーバーロールメンバー」機能の設計書です。SQL Server インスタンスのサーバーロールメンバーシップを管理するコマンド群について記述します。

### 本画面の処理概要

本機能は、SQL Server のサーバーレベルロールに所属するログインの取得・追加・削除を行う機能を提供します。sysadmin、dbcreator、securityadmin等のロールに誰が所属しているかを監査し、必要に応じてメンバーシップを変更できます。

**業務上の目的・背景**：セキュリティ監査およびコンプライアンス要件において、どのログインがどのサーバーロールに所属しているかを正確に把握することは極めて重要です。特にsysadminなどの高権限ロールのメンバーは厳密に管理する必要があります。本機能により、ロールメンバーシップの監査、レポート作成、権限問題のトラブルシューティングが効率化されます。

**画面へのアクセス方法**：PowerShellコンソールから `Get-DbaServerRoleMember`、`Add-DbaServerRoleMember`、`Remove-DbaServerRoleMember` コマンドを直接実行します。

**主要な操作・処理内容**：
1. `Get-DbaServerRoleMember`: サーバーロールのメンバーシップ情報を詳細に取得
2. `Add-DbaServerRoleMember`: サーバーロールへのログインの追加
3. `Remove-DbaServerRoleMember`: サーバーロールからのログインの削除

**画面遷移**：本機能はCLIコマンドのため画面遷移は存在しません。`Get-DbaServerRole` の出力から特定のロールを選択し、`Get-DbaServerRoleMember` にパイプラインで渡すことで、そのロールのメンバーを取得できます。

**権限による表示制御**：サーバーロールメンバーシップの取得には VIEW SERVER STATE 権限が必要です。メンバーの追加・削除には securityadmin または sysadmin 権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 563 | Get-DbaServerRoleMember | 主機能 | サーバーロールメンバーの取得 |
| 538 | Add-DbaServerRoleMember | 主機能 | サーバーロールメンバーの追加 |
| 580 | Remove-DbaServerRoleMember | 主機能 | サーバーロールメンバーの削除 |

## 画面種別

一覧 / 管理（サーバーロールメンバーの一覧取得および管理操作）

## URL/ルーティング

PowerShellコマンド:
- `Get-DbaServerRoleMember`
- `Add-DbaServerRoleMember`
- `Remove-DbaServerRoleMember`

## 入出力項目

### Get-DbaServerRoleMember 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| ServerRole | string[] | No | 対象のサーバーロール名 |
| ExcludeServerRole | string[] | No | 除外するサーバーロール名 |
| Login | object[] | No | 対象のログイン名 |
| ExcludeFixedRole | switch | No | 固定ロールを除外（SQL Server 2017以上） |
| EnableException | switch | No | 例外を有効化 |

## 表示項目

### Get-DbaServerRoleMember 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Role | string | サーバーロール名 |
| Name | string | ロールメンバーのログイン名 |
| SmoRole | ServerRole | SMO ServerRoleオブジェクト |
| SmoLogin | Login | SMO Loginオブジェクト |

## イベント仕様

### 1-Get-DbaServerRoleMember実行

1. Connect-DbaInstance を使用してSQL Serverに接続
2. $server.Roles からサーバーロールコレクションを取得
3. Login パラメータが指定された場合、Get-DbaLogin でログインを取得し、ListMembers() でそのログインが所属するロールを特定
4. ServerRole パラメータでフィルタリング
5. ExcludeServerRole パラメータで除外
6. ExcludeFixedRole パラメータで固定ロールを除外
7. 各ロールに対して EnumMemberNames() でメンバーを列挙
8. Login パラメータが指定された場合、指定されたログインのみにフィルタリング
9. 各メンバーについて、PSCustomObject を作成して出力

### 2-Add-DbaServerRoleMember実行

1. 対象ロールとログインの存在確認
2. SMO ServerRole オブジェクトの AddMember() メソッドを実行
3. 追加結果を返却

### 3-Remove-DbaServerRoleMember実行

1. 対象ロールとメンバーの存在確認
2. SMO ServerRole オブジェクトの DropMember() メソッドを実行
3. 削除結果を返却

## データベース更新仕様

### 操作別データベース影響一覧

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaServerRoleMember実行 | sys.server_role_members | SELECT | ロールメンバーシップの取得 |
| Get-DbaServerRoleMember実行 | sys.server_principals | SELECT | ロールとログイン情報の取得 |
| Add-DbaServerRoleMember実行 | sys.server_role_members | INSERT | メンバーシップの追加 |
| Remove-DbaServerRoleMember実行 | sys.server_role_members | DELETE | メンバーシップの削除 |

### テーブル別更新項目詳細

#### sys.server_role_members

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | role_principal_id, member_principal_id | すべてのメンバーシップ | Get-DbaServerRoleMember |
| INSERT | role_principal_id, member_principal_id | 新しいメンバーシップ | Add-DbaServerRoleMember |
| DELETE | role_principal_id, member_principal_id | 削除対象のメンバーシップ | Remove-DbaServerRoleMember |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| MSG-001 | エラー | Failure | SQL Server接続失敗時 |
| MSG-002 | エラー | Issue gathering login details | ログイン情報取得失敗時 |
| MSG-003 | 情報 | Getting Server Role Members for $role on $instance | ロールメンバー取得時（Verbose） |
| MSG-004 | 情報 | Filtering by logins: $logins | ログインフィルタリング時（Verbose） |
| MSG-005 | 情報 | $role members: $members | メンバー列挙時（Verbose） |

## 例外処理

| 例外種別 | 発生条件 | 処理内容 |
|---------|---------|---------|
| ConnectionError | SQL Serverへの接続失敗 | Stop-Function で処理を停止 |
| LoginNotFound | 指定されたログインが存在しない | エラーメッセージを表示 |
| RoleNotFound | 指定されたロールが存在しない | 処理をスキップ |

## 備考

- ExcludeFixedRole パラメータは SQL Server 2017 以上で利用可能
- 1つのログインが複数のロールに所属している場合、各ロール-ログイン組み合わせごとに1つのオブジェクトが返される
- SmoRole と SmoLogin プロパティにより、SMOオブジェクトへの直接アクセスが可能

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaServerRoleMember.ps1 | `public/Get-DbaServerRoleMember.ps1` | 出力PSCustomObjectの構造（行173-181） |

**読解のコツ**: PSCustomObject で明示的にプロパティを定義している点に注目。SmoRole と SmoLogin により、後続処理で SMO オブジェクトを直接操作可能。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaServerRoleMember.ps1 | `public/Get-DbaServerRoleMember.ps1` | param ブロック（行105-116）とフィルタリングロジック（行128-156） |

**主要処理フロー**:
1. **行121**: Connect-DbaInstance による接続
2. **行126**: $server.Roles でロールコレクション取得
3. **行128-143**: Login パラメータによるフィルタリング（ListMembers() 使用）
4. **行146-156**: ServerRole, ExcludeServerRole, ExcludeFixedRole によるフィルタリング
5. **行161**: EnumMemberNames() でメンバー列挙
6. **行173-181**: PSCustomObject の作成と出力

### プログラム呼び出し階層図

```
Get-DbaServerRoleMember
    |
    +-- Connect-DbaInstance (SQL Server 接続)
    |
    +-- $server.Roles (SMO ServerRole コレクション)
    |
    +-- [Login パラメータ指定時]
    |       +-- Get-DbaLogin (ログイン取得)
    |       +-- $login.ListMembers() (ロール一覧取得)
    |
    +-- Where-Object (フィルタリング)
    |       +-- ServerRole パラメータ
    |       +-- ExcludeServerRole パラメータ
    |       +-- ExcludeFixedRole パラメータ
    |
    +-- EnumMemberNames() (メンバー列挙)
    |
    +-- [Login パラメータ指定時]
    |       +-- Where-Object (指定ログインのみ)
    |
    +-- $server.Logins (ログインオブジェクト取得)
    |
    +-- PSCustomObject 作成・出力
```

### データフロー図

```
[入力]               [処理]                    [出力]

SqlInstance  ───+
                |
SqlCredential ──+──> Connect-DbaInstance ───> Server Object
                |
Login ──────────+──> Get-DbaLogin ──────────> Login Object
                |    ListMembers() ──────────> Role Names
                |
ServerRole ─────+──> フィルタリング ──────────> ServerRole[]
                |
                +──> EnumMemberNames() ───────> Member Names

ServerRole[] + Member Names ──> PSCustomObject作成
                                + SmoRole
                                + SmoLogin

PSCustomObject ────────────────> Pipeline Output
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaServerRoleMember.ps1 | `public/Get-DbaServerRoleMember.ps1` | ソース | ロールメンバー取得 |
| Add-DbaServerRoleMember.ps1 | `public/Add-DbaServerRoleMember.ps1` | ソース | ロールメンバー追加 |
| Remove-DbaServerRoleMember.ps1 | `public/Remove-DbaServerRoleMember.ps1` | ソース | ロールメンバー削除 |
| Get-DbaLogin.ps1 | `public/Get-DbaLogin.ps1` | ソース | ログイン取得（Login パラメータ使用時） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
