Merge ea72f31 into ddd6cbe

docs/Getting-Started/LocalModules.md

@@ -59,4 +59,6 @@ package.json
 
 ## Importing
 
-When the modules have been downloaded, you can utilise them using the  [`Import-PodeModule`](../../Functions/Utilities/Import-PodeModule) function.
+When the modules have been downloaded, you can import them using the [`Import-PodeModule`](../../Functions/Utilities/Import-PodeModule) function.
+
+Unlike `Import-Module`, [`Import-PodeModule`](../../Functions/Utilities/Import-PodeModule) will check if some module is within the `ps_modules` directory first, then it will check the global modules.

docs/Getting-Started/Migrating/1X-to-2X.md

@@ -71,3 +71,120 @@ On the following functions:
 * `Remove-PodeStaticRoute`
 
 The `-Endpoint` and `-Protocol` parameters have been removed in favour of `-EndpointName`.
+
+### Scoping and Auto-Importing
+
+The 2.0 release sees a big change to some scoping issues in Pode, around modules/snapins/functions and variables. For more information, see the new page on [Scoping](../../../Tutorials/Scoping).
+
+#### Modules/Snapins
+
+You can now use `Import-Module`, or `Add-PSSnapin`, and Pode will automatically import all loaded modules/snapins into its runspaces:
+
+```powershell
+Import-Module SomeModule
+
+Start-PodeServer -ScriptBlock {
+    Add-PodeEndpoint -Address localhost -Port 9000 -Protocol Http
+
+    Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
+        Use-SomeModuleFunction
+    }
+}
+```
+
+[`Import-PodeModule`](../../../Functions/Utilities/Import-PodeModule) still exists, as it supports the use of local modules in `ps_modules`. The only difference is that the `-Now` switch has been removed, and you can now use `Import-PodeModule` outside of the [`Start-PodeServer`](../../../Functions/Core/Start-PodeServer) block.
+
+[`Import-PodeSnapin`](../../../Functions/Utilities/Import-PodeSnapin) also still exists, and has the same differences as `Import-PodeModule` above.
+
+To disable the auto-import, you can do so via the `server.psd1` configuration file. You can also set auto-imported modules to only used exported ones via [`Export-PodeModule`](../../../Functions/AutoImport/Export-PodeModule)/[`Export-PodeSnapin`](../../../Functions/AutoImport/Export-PodeSnapin).
+
+```powershell
+@{
+    Server = @{
+        AutoImport = @{
+            Modules = @{
+                Enable = $false
+                ExportOnly = $true
+            }
+            Snapins = @{
+                Enable = $false
+                ExportOnly = $true
+            }
+        }
+    }
+}
+```
+
+#### Functions
+
+Local functions are now automatically imported into Pode's runspaces! This makes it a little simpler to use quick functions in Pode:
+
+```powershell
+function Write-HelloResponse
+{
+    Write-PodeJsonResponse -Value @{ Message = 'Hello!' }
+}
+
+Start-PodeServer -ScriptBlock {
+    function Write-ByeResponse
+    {
+        Write-PodeJsonResponse -Value @{ Message = 'Bye!' }
+    }
+
+    Add-PodeEndpoint -Address localhost -Port 9000 -Protocol Http
+
+    Add-PodeRoute -Method Get -Path '/hello' -ScriptBlock {
+        Write-HelloResponse
+    }
+
+    Add-PodeRoute -Method Get -Path '/bye' -ScriptBlock {
+        Write-ByeResponse
+    }
+}
+```
+
+If you store Routes/etc in other files, you can also have local functions in these files as well. However, for Pode to import them you must use [`Use-PodeScript`](../../../Functions/Utilities/Use-PodeScript) to dot-source the scripts - this will trigger Pode to scan the file for functions.
+
+To disable the auto-import, you can do so via the `server.psd1` configuration file. You can also set auto-imported modules to only used exported ones via [`Export-PodeFunction`](../../../Functions/AutoImport/Export-PodeFunction).
+
+```powershell
+@{
+    Server = @{
+        AutoImport = @{
+            Functions = @{
+                Enable = $false
+                ExportOnly = $true
+            }
+        }
+    }
+}
+```
+
+#### Variables
+
+You can now define local variables, and use the `$using:` syntax in almost all `-ScriptBlock` parameters, like:
+
+* Routes
+* Middleware
+* Authentication
+* Logging
+* Endware
+* Timers
+* Schedules
+* Handlers
+
+This allows you to do something like:
+
+```powershell
+$outer_msg = 'Hello, there'
+
+Start-PodeServer -ScriptBlock {
+    Add-PodeEndpoint -Address localhost -Port 9000 -Protocol Http
+
+    $inner_msg = 'General Kenobi'
+
+    Add-PodeRoute -Method Get -Path '/random' -ScriptBlock {
+        Write-PodeJsonResponse -Value @{ Message = "$($using:outer_msg) ... $($using:inner_msg)" }
+    }
+}
+```

docs/Tutorials/ImportingModules.md

@@ -1,20 +1,22 @@
-# Importing Modules/SnapIns
+# Importing Modules/Snapins
 
-Because Pode runs most things in isolated runspaces, importing and using modules or snap-ins can be quite bothersome. To overcome this, you can use the  [`Import-PodeModule`](../../Functions/Utilities/Import-PodeModule) or [`Import-PodeSnapIn`](../../Functions/Utilities/Import-PodeSnapIn) functions to declare paths/names of modules or snap-ins that need to be imported into all of the runspaces.
+Modules/Snapins in Pode have recently undergone a change, making them easier to use with Pode's many runspaces. This change means you can use the normal `Import-Module`/`Add-PSSnapin` at the top of your scripts, and Pode will automatically import them into its runspaces. For more information, see the [Scoping](../Scoping) page.
+
+The older [`Import-PodeModule`](../../Functions/Utilities/Import-PodeModule) and [`Import-PodeSnapin`](../../Functions/Utilities/Import-PodeSnapin) still exist - but now mostly just directly call the main module/snapin functions.
 
 !!! important
-    Snap-ins are only supported in Windows PowerShell.
+    Snapins are only supported in Windows PowerShell.
 
 ## Modules
 
+Modules in Pode can be imported in the normal manor using `Import-Module`. The [`Import-PodeModule`](../../Functions/Utilities/Import-PodeModule) function can now be used inside and outside of [`Start-PodeServer`](../../Functions/Core/Start-PodeServer), and should be used if you're using local modules via `ps_modules`.
+
 ### Import via Path
 
-The following example will tell Pode that the `tools.psm1` module needs to be imported into all runspaces. This will allow the functions defined within the module to be accessible to all other functions within your server.
+The following example will tell Pode that the `tools.psm1` module needs to be imported. This will allow the functions defined within the module to be accessible to all other functions within your server.
 
 ```powershell
-Start-PodeServer {
-    Import-PodeModule -Path './path/to/tools.psm1'
-}
+Import-PodeModule -Path './path/to/tools.psm1'
 ```
 
 ### Import via Name
@@ -24,19 +26,22 @@ The following example will tell Pode to import the `EPS` module into all runspac
 If you're using [`local modules`](../../Getting-Started/LocalModules) in your `package.json` file, then Pode will first check to see if the EPS module is in the `ps_modules` directory. When Pode can't find the EPS module within the `ps_modules` directory, then it will attempt to import a globally installed version of the EPS module.
 
 ```powershell
-Start-PodeServer {
-    Import-PodeModule -Name EPS
-}
+# if using local modules:
+Import-PodeModule -Name EPS
+
+# if using global modules
+Import-Module -Name EPS
 ```
 
-## SnapIns
+## Snapins
 
 ### Import via Name
 
 The following example will tell Pode to import the `WDeploySnapin3.0` snap-in into all runspaces:
 
 ```powershell
-Start-PodeServer {
-    Import-PodeSnapIn -Name 'WDeploySnapin3.0'
-}
+Import-PodeSnapin -Name 'WDeploySnapin3.0'
+
+# or just:
+Add-PSSnapin -Name 'WDeploySnapin3.0'
 ```

docs/Tutorials/Routes/Utilities/FunctionsAndModules.md

@@ -37,7 +37,7 @@ Add-PodeRoute -Method Post -Path '/Invoke-Expression' -ScriptBlock {
 
 If you have a Module whose exported commands you want to convert into Routes, then you can supply the Module's name to [`ConvertTo-PodeRoute`](../../../../Functions/Routes/ConvertTo-PodeRoute).
 
-Supplying a Module will cause it to be automatically imported into all runspaces, using [`Import-PodeModule`](../../../../Functions/Utilities/Import-PodeModule). This means the Module can be referenced by name, or by path; it also means [`Import-PodeModule`](../../../../Functions/Utilities/Import-PodeModule).supports modules within the `ps_modules` directory.
+Supplying a Module will cause it to be automatically imported using [`Import-PodeModule`](../../../../Functions/Utilities/Import-PodeModule). This means the Module can be referenced by name, or by path, and it supports modules within the `ps_modules` directory.
 
 For example, if you wanted to import all commands from Pester you could do the following: