---
title: "構成の作成とカスタマイズ"
slug: "create-and-customize-configurations"
abstract: ""
---
# 構成の作成とカスタマイズ

タスク、パラメータ、設定関数、変数を使ってインストールプロセスをカスタマイズできます。カスタムタスクや設定関数はモジュールとしてパッケージ化でき、構成に組み込むこともできます。

カスタマイズはSitecoreが提供する構成のいずれかを基にすることも、自分で設定を作成することも可能です。このセクションでは、Sitecoreインストールフレームワーク構成で使用できるさまざまなコンポーネントについて説明します。

## 任務

タスクとは、Install-SitecoreConfigurationコマンドレットを実行する際に連続して実行されるアクションのことです。タスクはPowerShellコマンドレットとして実装されます。

各タスクは一意の名前で識別され、*Type*プロパティを含まなければなりません。タスクにはパラメータが渡される場合もあれば、パラメータの集合が渡されることがあります。タスクは直接PowerShell関数にマッピングされ、Register-SitecoreInstallExtension -Typeタスクに登録されます。

以下の例は、設定でファイルを一箇所から別の場所へコピーするために使える、Copyタイプのタスクです。

{ 
 "Tasks": { 
 "CopyFiles" : { 
 "Description": "Copies files to the specified location",
 "Type": "Copy", 
         "Params": {
 "Source": "c:\\files",
 "Destination": "c:\\newfiles"
 }
 }
 }
}

### タスクのスキップ

タスクはパラメータ、変数、または設定関数を参照する*Skip*プロパティを含めることができます。戻り値が *真*であれば、タスクは実行されません。

{
 "Parameters : {
 "Param1" : {
 "Type" : "String"
 "DefaultValue" : ""
        }
    },
    "Tasks" :{
        "Task1" :{
            "Type" : "Copy
            "Params" :{
                "Source" : "C:\\\\Source",
                "Destination : "C:\\\\Destination"
 }
            "Skip" : "not(Parameter('Param1'))"
        }
    }
}

> !注設定が有効であることを保証するために、各タスクには一意の名前が必要です。これにより、タスクを直接実行でき、ログ上でタスクを識別できます。また、同じタイプのタスクを設定内で複数回使うことも可能です。

この構成では、Param1を任意の値に設定すると、Task1はスキップされます。

### 必須条件(前提条件)

タスクには、タスクを実行する前に前提条件チェックを行うためのRequiresブロックを含めることができます。前提条件のチェックはSkipセクションの後に行われます。前提条件は、ブール値を返すConfig Functionsの形をとるべきです。前提条件チェックが*false*を返す場合、SIFは現在のホスト内にネストされたシェルに入ろうとします。その後、提供されたプロンプトから、または外部から問題を修正する機会が得られます。

問題を修正した後、exitを入力してSIFに戻ります。その後、前提条件のチェックが再度実行されます。または、SkipRequireコマンドを入力してこの前提条件をスキップすることもできます。現在のホストがネストシェルをサポートしていない場合、要件はスキップされます。

{
 "Variables": {
 "Requires.Success" : TestPath(Path:'C:\\\\Windows')
    },
    "Tasks": {
        "Task1":{
            "Type": "WriteOutput",
            "Params" :{
         "InputObject":"Simple Task, depends on a variable."
            },
            "Requires": "variable('Requires.Success')"
 }
 },
    "Settings" : {
        "AutoRegisterExtensions" : True
    }
}

この構成では、Task1 Requires.Success変数の出力でC:\\Windowsの存在が *真である*か確認する必要があります。

## パラメータ

パラメータはユーザーが実行時に構成内で値を変更できるようにします。パラメータは型を宣言しなければなりません。また、デフォルト値や記述を宣言することもできます。

パラメータを設定に追加すると、parameter 設定関数を使ってタスクに渡すことができます。タスクは設定で提供された値、またはInstall-SitecoreConfiguration呼び出し時に渡された値を指し示します。

例えば、SourceパラメータとDestinationパラメータをCopyFilesタスクに渡す場合:

{
 "Parameters": {
 "Source": { "Type": "string", "Description": "The source of files" },
 "Destination": { "Type": "string", "DefaultValue": "c:\\newfiles" }
 },
    "Tasks": {
 "CopyFiles" : { 
 "Type": "Copy", 
 "Params": {
 "Source": "parameter('Source')",
 "Destination": "parameter('Destination')"
 }
 }
 }
}

Sourceパラメータには*DefaultValue*の性質が含まれていないため、Install-SitecoreConfigurationを呼び出す際に必須となります。

ただし、Destinationパラメータにはデフォルト値があります。ユーザーが値を提供しない場合は、設定のDefaultValueが使われます。

実行時の値は、そのparameter設定関数を使うCopyFilesタスクに渡されます。

コマンドラインで値を渡すには、パラメータ名を標準のPowerShellパラメータ構文で使う必要があります。例えば:

Install-SitecoreConfiguration -Path .\\configuration.json -Source c:\\sourcefiles

### パラメータ検証

パラメータ値はタスク開始前に検証可能です。各パラメータに対して、設定関数を用いて検証ロジックを指定できます:

{
 "Parameters": {
 "Source": {
 "Type": "string",
 "DefaultValue": "c:\\\\myfiles",
 "Validate": "validatelength(4, 260, $\_)"
 },
 }
}

この例では、Sourceパラメータはvalidatelength設定関数によって検証され、値の長さが4桁から260文字であることを保証します。

Validateプロパティは、boolを返す任意の設定関数を受け入れます。

検証に使用できるあらかじめ定義された関数は以下の通りです:

-   ValidateCount - パラメータの配列長が指定された範囲内であることを検証します。
-   ValidateLength - パラメータの長さが指定された範囲内であることを検証します。
-   ValidateNotNull - 引数がnullでないことを検証します。
-   ValidateNotNullOrEmpty - 引数がnullでないこと、かつ空文字列でないことを検証します。
-   ValidatePattern - パラメータが正統形形パターンに合致していることを検証します。
-   ValidateRange - 数値パラメータが Min および Maxで指定された範囲内にあるかを検証します。
-   ValidateSet - パラメータが指定された集合に存在していることを検証する。

Install-SitecoreConfigurationを呼び出すと、検証ロジックを含むすべてのパラメータがチェックされます。検証に失敗した場合、インストールコマンドは中止されます。検証を回避するには、Install-SitecoreConfigurationを呼び出して–SkipValidationオプションを使います。

## 設定関数

設定関数は構成の要素を動的に設定でき、値を計算したり、関数を呼び出したり、これらの値をタスクに渡したりすることで、構成を柔軟にできます。

構成関数は、□括弧で囲まれた文字列として表 。関数は名前で識別され、関数パラメータを受け取ることができます。例えば:

functionName(param1,param2,param3)

各関数は、以下のコマンドレットで登録されたPowerShell関数に直接マッピングされます:

Register-SitecoreInstallExtension -Type ConfigFunction

### 命名パラメータ

正しい値が期待されるパラメータに渡されることを確認するために、設定関数のパラメータを直接参照できます。

名前付きパラメータはカンマ区切りリストで記載されるべきです。パラメータ名の後にコロンを付ける必要があります:

{
 "Variables": {
 "Variable1": "GetFunction(Number:1234,String:'Text',Switch:True)"
 }
}

この例では、Variable1 GetFunction関数を呼び出し、Numberパラメータを*1234*、stringパラメータを値 'Text'、Switchパラメータを値True渡します。これはコマンドラインで「 Get-Function -Number:1234 -String:"Text" -Switch:$True 」を入力するのと同じです。

構成Switchパラメータを宣言した場合、TrueまたはFalseに設定されなければなりません。

ネスト関数も許可されており、パラメータ、変数、その他の設定関数を指すことがあります。例えば:

FunctionName1(functionName2(Switch1:'value1',Switch2:'value2'),Switch3:'value3')

## 変数

変数とは、構成自体の中で計算される値のことです。パラメータとは異なり、変数は設定関数を使ってその値を決定できます。変数は実行時に上書きすることはできません。しかし、計算時にパラメータや他の変数の値を利用できます。

以下の例では、Destination変数がenvironmentおよびconcat設定関数を使って宛先パスを決定します。

{
 "Parameters": {
 "Source": { "Type": "string", "Description": "The source of files" }
    },
    "Variables": {
 "Destination": "concat(environment('SystemDrive'),'\\\\newfiles')"
    },
    "Tasks": {
 "CopyFiles" : { 
 "Type": "Copy", 
 "Params": {
 "Source": "parameter('Source')",
 "Destination": "variable('Destination')"
 }
 }
 }
}

## モジュール

SIFは多くのタスクや設定機能を提供します。追加のタスクや設定機能も設定に含めることで読み込むことができます。

[モジュールがPSModulePath](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_psmodulepath?view=powershell-7.4)で利用可能であれば、モジュール名でロードできます。あるいは、明示的なパスを使ってモジュールをロードする必要があります。モジュールはインストール開始時にロードされます。

追加機能がコンピュータのモジュールにパッケージされている場合、設定のModulesセクションでインストールセッションにインポートできます。例えば:

-   モジュールを名前でロードするには–"MyCustomModule"
-   明示的な経路でモジュールを読み込むには「C:\\\\extensions\\\\extensions.psm1」

{
 "Modules": 
 "MyCustomModule",
 "C:\\\\extensions\\\\extensions.psm1"
 
}

## アンインストールタスク

構成にはオプションのUninstallTasksセクションを含めることができます。このセクションはTasksセクションと同じ形式です。 Tasksセクションで完了したすべてのアクションを元に戻すタスクのリストを含めるべきです。

アンインストールタスクは、–UninstallスイッチをInstall-SitecoreConfigurationに渡すか、Uninstall-SitecoreConfigurationエイリアスを呼び出すことで起動されます。 Uninstall-SitecoreConfigurationを呼び出した場合、\-Uninstallスイッチを含める必要はありません。

アンインストールタスクは通常のタスクと同じように扱い、同じ機能をサポートします。

{
 "Parameters" :{
        "SolrService": {
 "Type": "string",
 "DefaultValue": "Solr-7.2.1",
 "Description": "The name of the Solr service."
        },
    },
    "UninstallTasks": {
        "RemoveSolrService": {
            "Type": "RemoveService",
            "Params": {
                "Name": "parameter('SolrService')"
            }
        },
    }
}

この例では、RemoveSolrServiceアンインストールタスクがRemoveServiceタスクを実行し、SolrServiceパラメータで指定されたサービスを停止・削除します。

Includesセクションで他の構成を参照している場合、含まれる各構成のUninstall Tasksは最初の構成のタスクの後に逆順に実行されます。

## 登録

Registerセクションの各エントリでは、設定ファイル内でSIFタスクやConfigFunctionsとしてPowerShell関数を公開でき、それらをVariablesまたはTasksセクションで使用できます。これらはRegister-SitecoreInstallExtensionコマンドで自動的に登録されます。

このセクションの形式は以下の通りです。

{
 "Register": {
 "Tasks" : {
 "NewSMBShare" : "New-SMBShare",
 "Sleep": "Start-Sleep"
 },
 "ConfigFunction": {
 "GetRandom" : "Get-Random"
 }
    }
}

この構成では、New-SMBShareコマンドレットをNewSMBShareという名前のタスクとして登録し、Start-SleepをSleepという名前のタスクとして登録します。 Get-RandomコマンドレットはGetRandomという名前で設定関数として登録されます。

SIFを拡張するのと同じように、RegisterのTasksセクションは何も返さない関数用、ConfigFunctionsセクションは値を返す関数用です。

## 拡張の自動登録

設定ファイルはオプションで、動的に登録できるAutoRegisterExtensions設定を宣言でき、TasksとConfigFunctionsできます。デフォルト値はfalseです。

任意のPowerShellコマンドレットは、名前のハイフンを切ったバージョンで設定ファイル内で参照できます。

{   
 "Tasks": {
 "RandomSleep": {
 "Type": "StartSleep",
            "Params": {
                "Seconds": "GetRandom(10)"
 }
 }
 },
    "Settings" : {
 "AutoRegisterExtensions" : true
    }
}

この構成では、RandomSleepタスクは自動的にStart-Sleepをタスクとして登録し実行し、ConfigFunctionとしてGet-Randomします。これはコマンドライン上でStart-Sleep -Seconds (Get-Random 10)を実行するのと同等です。

2つ以上のコマンドレットが一致すると、それらのコマンドレットが一覧化されエラーが出されます。

## 含まれる

要素を再利用し繰り返しを減らすために、構成は他の設定ファイルを参照することができます。

例えば、以下の設定はサイトを設定するための擬似設定です。これはCreateSite.jsonとして保存されます:

{
 "Parameters": {
 "Destination":{
 "Type": "string"
 },
 "SourcePackage":{
 "Type": "string"
    },
    "SiteName":{
 "Type": "string"
    }
 },
  "Tasks":{
 "CreateSite":{
      "Type": "CreateSite",
      "Params":{
       "SiteName": "parameter('SiteName')",
        "Path": "parameter('Destination')"
      }
    },
    "InstallPackage":{
 "Type": "CreateSite",
      "Params":{
 "Source": "parameter('SourcePackage')",
        "Path": "parameter('Destination')"
      }
    }
  }
}

前述の例を含む別の設定を作成することもできます:

{
 "Includes":{
 "CreateSite":{
 "Source": ".\\\\CreateSite.json"
 }
 }
}

含まれている設定の要素は、インポートされた名前空間(この場合は 'CreateSite')を使って上書きできます。

{
 "Parameters": {
 "CreateSite:Destination":{
 "Type": "string",
 "DefaultValue": "C:\\\\inetpub"
 }
 },
 "Includes":{
 "CreateSite":{
 "Source": ".\\\\CreateSite.json"
 }
 }
}

この例はCreateSite設定でインポートされた宛先パラメータのデフォルト値を上書きします。同様の構文がVariablesとTasksの上書きにも使われています。

同じ設定を複数回含めることもできます。名前は各機能の名前空間に使われます:

{
 "Parameters": {
 "CreateSite:Destination":{
 "Type": "string",
 "DefaultValue": "C:\\\\inetpub"
 },
    "CreateBackupSite:Destination":{
 "Type": "string",
 "DefaultValue": "C:\\\\inetpubbackup"
 }
 },
 "Includes":{
   "CreateSite":{
     "Source": ".\\\\CreateSite.json"
    },
    "CreateBackupSite":{
     "Source": ".\\\\CreateSite.json"
    }
 }
}

## 舞台設定

設定ではインストールプロセスのデフォルト要件を設定できます。一部の設定は、Install- SitecoreConfigurationコマンドレットにパラメータとして渡すことで実行時に上書きできます。

例えば:

Install-SitecoreConfiguration -WarningAction Stop -InformationAction SilentlyContinue

設定内の値は低い順に以下の順に適用されます。

-   デフォルト値はコード内に含まれるものです。
-   設定 – 設定ファイル内で設定します。
-   コマンドライン – コマンドラインで渡されます。

名称

デフォルト価値

許容値

コマンドライン

概要

警告行動

続けてください

続けてください  
  
無視してください  
  
問い合わせ  
  
静かに続ける  
  
やめて  
  
停止

はい

警告が出たときに取るべき行動。

エラーアクション

やめて

続けてください  
  
無視してください  
  
問い合わせ  
  
静かに続ける  
  
ストップ・サスペンション

はい

エラーが発生したときに取るべきアクション。

インフォメーションアクション

続けてください

続けてください  
  
無視してください  
  
問い合わせ  
  
静かに続ける  
  
やめて  
  
停止

はい

情報が記録されたときに取るべき行動。

AutoRegisterExtensios

間違いです

確かに  
  
間違いです

いいえ

タスクや設定関数の動的登録を可能にします。

設定ファイル内の設定は次のように宣言できます:

{
    "Settings": {
        "AutoRegisterExtensions": true,
        "InformationAction": "SilentlyContinue"
    }
}

この構成により、AutoRegisterExtensions特徴が可能になり、InformationAction優先順位がSilentlyContinueに設定されます。