scriptcs 簡介

1. 簡介
April 2016
蔡煥麟
http://huan-lin.blogspot.com

2. What?
是可以
動態編譯與執行
C# 程式碼的工具
全都是小寫字母

3. Why?
• 可使用任何編輯器來編寫 C# 程式碼。
• 拿來學習、實驗、與展示 C# 程式碼，非常輕巧、方便。
• 支援 NuGet－你的 script 可引用任何現成的 NuGet 套件
• 需要編寫動態執行的指令碼，可是不想學 Powershell、Python、
F#、或其他語言，因為你最熟悉也最喜歡的就是 C#。

4. 安裝
• 安裝套件管理工具：Chocolatey（讀音類似「查克拉踢」）
• 透過 Chocolatey 安裝 scriptcs：
cint scriptcs
• 安裝 Visual Studio Code，作為編寫 C# script 的編輯器
• 安裝 Visual Studio Code 擴充套件：
• C# （必要）
• scriptcsRunner

5. scriptcs – 基礎選項
範例 說明
scriptcs REPL 模式（即時互動）。作用等同於 scriptcs -repl。
scriptcs <file> 載入並執行指定的 .csx 檔案。
範例：scriptcs hello.csx
scriptcs -? 列出全部的選項。等於 scriptcs -help。
scriptcs -version 顯示 scriptcs 的版本號碼。
_ _
___ ___ _ __(_)_ __ | |__ ___ ___
/ __|/ __| '__| | '_ | __// __/ __|
__ (__| | | | |_) | |_| (____
|___/___|_| |_| .__/ _____|___/
|_| Version: 0.16.1
read–eval–print loop
程式檔案的副檔名
應一律使用 .csx。

6. Demo: scriptcs 命令列模式 (REPL)
https://youtu.be/voWtuADxN7k
影片中使用的命令
列視窗是 cmder。比
Windows 內建的命
令提示字元更好用、
更多功能。

7. scriptcs – 執行時期的選項
範例 說明
scriptcs -loglevel <level> 指定篩選的 log 等級。此參數可簡寫為 -log。
<level> 可以是：error | info | debug | trace。預設為 info。
scriptcs <file> -cache true 指定編譯後的 DLL 放在 .scriptcs_cache 子目錄下，供下次直接取用
（省掉第二次編譯）。
scriptcs <file> -debug 編譯時一併產生 .pdb 除錯符號檔，以便讓 Visual Studio 掛載
（attach）然後除錯你的 .csx 檔案。
scriptcs –config <file> 載入指定的組態檔。scriptcs 預設會自動尋找並載入名為
scriptcs.opts 的組態檔。組態檔的內容是 JSON 格式。範例：
{ “log” : “debug” , “cache” : true }

8. scriptcs – 傳遞給程式的引數
• 除了 scriptcs 所定義的命令列引數，我們也可以傳遞引數給自己的
script 程式碼。
• 語法：兩個連續減號 “--” 後面接的都是要傳遞給程式的引數。
scriptcs <scriptcs 引數> -- <傳遞給程式的引數>
• 範例：
scriptcs hello.csx -- “Good morning!”
• 在 .csx 程式中，可利用唯讀陣列 Env.ScriptArgs[] 來取得引數。
• 範例：
var str = Env.ScriptArgs[0]
Console.WriteLine(str); // 印出字串 “Good morning!”

9. scriptcs – 管理 NuGet 套件 (1/2)
範例 說明
scriptcs -install <package name> 安裝 NuGet 套件至 scriptcs_packages 子目錄，並建立
scriptcs_packages.config。
注意：scriptcs 會自動參考 scriptcs_packages 目錄下的所有套件
（亦即此目錄下的 DLL 組件無須額外加入參考的指令，只要直接
在程式中 using 命名空間即可）。
scriptcs -install 沒有指定 package name 時，作用等同於 restore all packages。也就
是安裝 scriptcs_packages.config 檔案中的所有套件。
scriptcs -install
<package name> <version>
安裝特定版本的 NuGet 套件。
scriptcs -install
<package name> <version> -pre
如果要安裝的 NuGet 套件是預先發行的版本，必須加上 -pre。
官方文件：Package installation

10. scriptcs – 管理 NuGet 套件 (2/2)
範例 說明
scriptcs -save 根據 scriptcs_packages 子目錄所包含的套件來重建
scriptcs_packages.config 檔案。
scriptcs -clean 刪除整個 scriptcs_packages 子目錄（scriptcs_packages.config 檔案保
持不變）。
官方文件：Package installation
註：scriptcs 使用 NuGet.Core 來管理套件，因此即使本機沒有安裝 NuGet，它
仍然可以管理 NuGet 套件。

11. NuGet.config
• 用途：定義套件的來源。
• NuGet 會使用這個檔案來決定去哪裡下載 NuGet 套件。
• 尋找 NuGet.config 的順序：
1. Local folder: scriptcs 會優先使用放在這裡的 NuGet.config 檔案。
2. NuGet 安裝目錄：%APPDATA%NuGet
3. https://www.nugget.org/api/v2
• 你可以在 local folder 放一個 scriptcs_nuget.config 來讓 scriptcs 使
用你指定的 NuGet 檔案庫。
• 參考官方文件：NuGet Configuration File

12. scriptcs 指示詞
語法 用途 範例
#load <file.csx> 載入另一個 .csx 檔案（會與目前的檔案一起編
譯）。換言之，此指令可讓你在目前的 .csx 檔
案中使用其他 .csx 檔案中的型別、變數、與方
法。
注意：
• 必須寫在 .csx 檔案中的最上方。
• 如需撰寫多個 #load 敘述，它們的先後順序
不重要。
#load “StrHelper.csx”
#load “LibStrHelper.csx”
#load “C:MyLibFoo.csx”
（檔名可以是相對路徑或絕對路
徑）
#r <file.dll> 加入組件參考。指定的 DLL 組件必須存在
scriptcs_bin 子目錄或者 GAC。
#r “nunit.core.dll”

13. 預設（自動）加入的組件參考與命名空間
• 預設會自動加入參考的組件有：
System, System.Core, System.Data, System.Data.DataSetExtensions,
System.Xml, System.Xml.Linq
• 預設會自動引用的命名空間有：
System, System.Collections.Generic, System.Linq, System.Text,
System.Threading.Tasks
• 另外，scriptcs 還會自動參考…
• NuGet 套件（亦即 scriptcs_packages 目錄下的套件）
• scriptcs_bin 目錄下的 DLL

14. 注意事項
• 不需要 solution 和 project 檔案。
• 沒有 Main()。第一行程式敘述就是程式的進入點。
• 不需要把程式碼包在類別裡（scriptcs 會幫你做）。
• 不需要、也不可以宣告 namespace。
• 不能撰寫 extension methods。
原因：C# 擴充方法必須寫在最上層的靜態類別裡，而 scriptcs 會
把你的程式碼包在另一個類別裡，造成編譯失敗。
此投影片沒有提到 scriptcs 的 script pack

15. 除錯技巧
• 使用 REPL 模式
• 使用 Console.WriteLine() 輸出除錯訊息
• ScriptCs.Logger.ScriptPack
• ScriptCs.ObjectDumper.ScriptPack
• 使用 Visual Studio Debugger

16. 使用 Visual Studio Debugger
• Open Project > 選擇 scriptcs.exe，然後儲存目前的 solution。
• 在 scriptcs.exe 上面點右鍵 > Properties，
• Arguments: <你的 .csx 檔案> -debug
• Working directory: <你的 .csx 檔案所在的目錄>
• 在 solution 名稱上點右鍵，Add > Existing items，然後加入 .csx
或 .cs 檔案。
• 在 .csx 檔案中設定中斷點，按 F5。
官方文件：Debugging a script

17. 附錄一: scriptcs 專屬檔案與資料夾
檔案／目錄 用途
.scriptcs_cache 快取編譯過的 DLL。
scriptcs_bin/ 存放需要自動參考的 DLL。
scriptcs_packages/ 存放 NuGet packages。
scriptcs_nuget.config 可蓋過全域的 nugget.config 設定。
scriptcs_packages.config NuGet 套件配置。

18. 參考資料
• scriptcs wiki
https://github.com/scriptcs/scriptcs/wiki
• Scriptcs blog
http://blog.scriptcs.net/
• Pluralsight 課程：Introduction to scriptcs （一小部分的內容已過時）
https://app.pluralsight.com/library/courses/introduction-scriptcs/
• C# on a diet with scriptcs （一小部分的內容已過時）
https://channel9.msdn.com/Events/TechEd/NewZealand/2013/DEV304

19. Thanks for Watching!