Skip to content

Commit 7ddf2f3

Browse files
brdeyobrdeyo
committed
Update extensions usage documentation with a few extra changes.
1 parent 88e4711 commit 7ddf2f3

File tree

2 files changed

+39
-182
lines changed

2 files changed

+39
-182
lines changed

‎website/docs/developing/0020-develop-extensions.md

Lines changed: 3 additions & 182 deletions
Original file line numberDiff line numberDiff line change
@@ -181,189 +181,10 @@ will have the following content.
181181
```
182182

183183
## How To Use/Integrate Extensions
184-
Once extensions have been developed and an extensions package exists, they can be used in the Virtual Client runtime. There are a number of different ways that
185-
extensions can be bootstrapped/installed on the system to suit the needs of the situation. The following examples illustrate some common ways that extensions can
186-
be integrated into the Virtual Client runtime.
187-
188-
### Place Extensions Directly in Virtual Client Application Folder
189-
The simplest way to integrate extensions binaries, profiles or packages into Virtual Client is to copy the files directly to the Virtual Client application
190-
directory (e.g. /virtualclient, /virtualclient/profiles, /virtualclient/packages).
191-
192-
* Extensions binaries/.dlls can be placed directly in the root directory of the Virtual Client application (i.e. right beside the VirtualClient executable).
193-
194-
``` bash
195-
# Given an installation location /home/users/virtualclient, the binaries/.dlls
196-
# can be copied into the root directory directly.
197-
#
198-
/home/users/virtualclient/Custom.VirtualClient.Extensions.Actions.dll
199-
/home/users/virtualclient/Custom.VirtualClient.Extensions.Dependencies.dll
200-
/home/users/virtualclient/Custom.VirtualClient.Extensions.Monitors.dll
201-
```
202-
203-
* Extensions profiles can be placed directly in the Virtual Client 'profiles' directory alongside the existing/out-of-box profiles.
204-
205-
``` bash
206-
# Given an installation location /home/users/virtualclient, the profiles
207-
# can be copied into the 'profiles' directory directly.
208-
#
209-
/home/users/virtualclient/profiles/PERF-CUSTOM-WORKLOAD-A.json
210-
/home/users/virtualclient/profiles/PERF-CUSTOM-WORKLOAD-B.json
211-
```
212-
213-
* Extensions packages can be placed directly in the Virtual Client 'packages' directory.
214-
215-
``` bash
216-
# Given an installation location /home/users/virtualclient, the packages
217-
# can be copied into the 'packages' directory directly.
218-
/home/users/virtualclient/packages/customworkload_a.1.0.0.zip
219-
/home/users/virtualclient/packages/customworkload_b.1.0.0.zip
220-
```
221-
222-
### Reference Extensions from Other Locations on the System
223-
Virtual Client enables the user/developer to define additional locations to look for extensions during execution startup. To do so, the user/developer can set
224-
custom environment variables on the system to provide Virtual Client with the alternate locations. Virtual Client will look for dependencies in both the default
225-
locations (normal operation) as well as within these alternate locations.
226-
227-
#### Supported Environment Variables
228-
The following environment variables can be used to define alternate locations for dependencies:
229-
230-
* **VC_LIBRARY_PATH**
231-
Defines 1 or more path locations where extensions assemblies/.dlls exist and that should be loaded at runtime. Multiple directory paths can be defined separated
232-
by a semi-colon ';' character (similar to the Windows and Linux `PATH` environment variable). Note that Virtual Client will search the immediate directory only
233-
for extension assemblies/.dlls. Recursive subdirectory searches are not supported.
234-
235-
``` bash
236-
# Example Folder Contents:
237-
# /VirtualClient.Extensions.Actions
238-
# /VirtualClient.Extensions.Actions.dll
239-
# /VirtualClient.Extensions.Actions.pdb
240-
#
241-
# /VirtualClient.Extensions.Monitors
242-
# /VirtualClient.Extensions.Monitors.dll
243-
# /VirtualClient.Extensions.Monitors.pdb
244-
#
245-
# On Windows systems
246-
C:\VirtualClient> set VC_LIBRARY_PATH=C:\Extensions\VirtualClient.Extensions.Actions
247-
C:\VirtualClient> set VC_LIBRARY_PATH=C:\Extensions\VirtualClient.Extensions.Actions;C:\Extensions\VirtualClient.Extensions.Monitors
248-
249-
# On Linux systems.
250-
/home/user/virtualclient$ export VC_LIBRARY_PATH=/home/user/Extensions/VirtualClient.Extensions.Actions
251-
/home/user/virtualclient$ export VC_LIBRARY_PATH=/home/user/Extensions/VirtualClient.Extensions.Actions;/home/user/Extensions/VirtualClient.Extensions.Monitors
252-
```
253-
254-
* **VC_PACKAGES_PATH**
255-
Defines 1 or more path locations where Virtual Client packages (including extensions packages) exist. Multiple directory paths can be defined separated by a semi-colon ';' character (similar to the Windows
256-
and Linux `PATH` environment variable). Note that Virtual Client will search the immediate directory only for packages. Recursive subdirectory searches are
257-
not supported.
258-
259-
``` bash
260-
# Example Folder Contents:
261-
# /CustomPackages1
262-
# /customworkload_a.1.0.0.zip
263-
# /customworkload_b.1.0.0.zip
264-
#
265-
# /CustomPackages2
266-
# /customworkload_c.1.0.0.zip
267-
# /customworkload_d.1.0.0.zip
268-
#
269-
# On Windows systems
270-
C:\VirtualClient> set VC_PACKAGES_PATH=C:\CustomPackages1
271-
C:\VirtualClient> set VC_PACKAGES_PATH=C:\CustomPackages1;C:\CustomPackages2;
272-
273-
# On Linux systems.
274-
/home/user/virtualclient$ export VC_PACKAGES_PATH=/home/user/CustomPackages1
275-
/home/user/virtualclient$ export VC_PACKAGES_PATH=/home/user/CustomPackages1;/home/user/CustomPackages2
276-
```
277-
278-
* **VC_PROFILES_PATH**
279-
Defines 1 or more path locations where extensions profiles exist and that should be available for use during execution. Multiple directory paths can be defined separated
280-
by a semi-colon ';' character (similar to the Windows and Linux `PATH` environment variable). Note that Virtual Client will search the immediate directory only for extension
281-
profiles. Recursive subdirectory searches are not supported.
282-
283-
``` bash
284-
# Example Folder Contents:
285-
# /CustomProfiles1
286-
# /PERF-CUSTOM-WORKLOAD-A.json
287-
# /PERF-CUSTOM-WORKLOAD-B.json
288-
#
289-
# /CustomProfiles2
290-
# /PERF-CUSTOM-WORKLOAD-C.json
291-
# /PERF-CUSTOM-WORKLOAD-D.json
292-
#
293-
# On Windows systems
294-
C:\VirtualClient> set VC_PROFILES_PATH=C:\CustomPackages1
295-
C:\VirtualClient> set VC_PROFILES_PATH=C:\CustomPackages1;C:\CustomPackages2;
296-
297-
# On Linux systems.
298-
/home/user/virtualclient$ export VC_PROFILES_PATH=/home/user/CustomProfiles1
299-
/home/user/virtualclient$ export VC_PROFILES_PATH=/home/user/CustomProfiles1;/home/user/CustomProfiles2
300-
```
301-
302-
#### Priority of Operations
303-
Given multiple of these environment variables are defined at the same time, Virtual Client will perform the search (and load/install) operations in the
304-
following way:
305-
306-
* **Priority for extensions packages and binaries/.dlls:**
307-
* Packages with "extensions" in the default Virtual Client `/packages` folder are installed. This includes assemblies/.dlls and profiles extensions.
308-
* Packages with "extensions" in directories defined in the `VC_PACKAGES_PATH` environment variable are installed. This includes assemblies/.dlls and profiles extensions.
309-
However, packages that exist in the `/packages` folder have precedence. Duplicate packages found in the paths defined by this environment variable will be ignored.
310-
* Binaries/.dlls in directories defined in the `VC_LIBRARY_PATH` environment variable are loaded into the runtime unless a duplicate (by name) is already loaded.
311-
Duplicate binaries/.dlls in the paths defined by this environment variable will be ignored.
312-
313-
* **Priority for extensions profile:**
314-
* Profiles that are in the default Virtual Client `packages` folder have highest precedence.
315-
* Profiles in directories defined in the `VC_PROFILES_PATH` environment variable have secondary precedence.
316-
317-
### Downloaded Extensions from a Package Store
318-
The default for most Virtual Client scenarios is to download extensions from a package store. The **VirtualClient bootstrap** command can be used to download
319-
extensions from a package store and install them.
320-
321-
```bash
322-
# Package/Blob Store Structure
323-
/container=packages/blob=crc.vc.extensions.zip
324-
325-
# Execute bootstrap command to download and install the extensions
326-
C:\Users\Any\VirtualClient> VirtualClient.exe bootstrap --package=crc.vc.extensions.zip --name=crcvcextensions --packages="{BlobStoreConnectionString|SAS URI}"
327-
328-
# Execute an extensions profile
329-
C:\Users\Any\VirtualClient> VirtualClient.exe --profile=EXAMPLE-WORKLOAD-PROFILE.json --timeout=1440 --packages="{BlobStoreConnectionString|SAS URI}"
330-
```
331-
332-
### A Custom-Defined Bootstrap Profile is Used
333-
The developer can choose to use a custom profile for bootstrapping/installing extensions as well.
334-
335-
``` json
336-
# Profile = BOOTSTRAP-EXTENSIONS.json
337-
{
338-
"Description": "Installs extensions from a package store.",
339-
"Dependencies": [
340-
{
341-
"Type": "DependencyPackageInstallation",
342-
"Parameters": {
343-
"Scenario": "InstallCRCExtensionsPackage",
344-
"BlobContainer": "packages",
345-
"BlobName": "crc.vc.extensions.zip",
346-
"PackageName": "crcvcextensions",
347-
"Extract": true
348-
}
349-
}
350-
]
351-
}
352-
```
353-
354-
...Then you can use it! Note that the profile can exist in another directory location and be referenced by the path to the file (full or relative path).
355-
184+
Once extensions have been developed and an extensions package exists, they can be used in the Virtual Client runtime. See the following documentation
185+
for details on how to integrate extensions into the runtime.
356186

357-
```bash
358-
# Package/Blob Store Structure
359-
/container=packages/blob=crc.vc.extensions.zip
360-
361-
# 1) Execute Bootstrap Command
362-
/VirtualClient/VirtualClient.exe --profile=S:\Some\Other\Folder\BOOTSTRAP-EXTENSIONS.json --dependencies --packages="{BlobStoreConnectionString|SAS URI}"
363-
364-
# 2) Execute Extensions Profile
365-
/VirtualClient/VirtualClient.exe --profile=EXAMPLE-WORKLOAD-PROFILE.json --timeout=1440
366-
```
187+
* [Integrating Extensions at Runtime](../guides/0221-usage-extensions.md)
367188

368189
## How To Debug Extensions in Visual Studio
369190
This next section is going to cover the topic of debugging Virtual Client extensions. It is very helpful at times when doing development work to have

‎website/docs/guides/0221-usage-extensions.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -319,6 +319,42 @@ how to incorporate script-based extensions.
319319
/home/user/script_extensions_packages/any.script.extensions.1.0.0/linux-x64/profiles/SCRIPT-WORKLOAD-1.json
320320
/home/user/script_extensions_packages/any.script.extensions.1.0.0/linux-x64/profiles/SCRIPT-WORKLOAD-2.json
321321
```
322+
323+
## Downloaded Extensions from a Package Store
324+
The default for most Virtual Client scenarios is to download extensions from a package store. The `VirtualClient bootstrap` command can be used to download
325+
extensions from a package store and install them.
326+
327+
``` bash
328+
# Package/Blob Store Structure
329+
/container=packages/blob=crc.vc.extensions.zip
330+
331+
# Execute bootstrap command to download and install the extensions
332+
C:\Users\Any\VirtualClient> VirtualClient.exe bootstrap --package=crc.vc.extensions.zip --name=crcvcextensions --packages="{BlobStoreConnectionString|SAS URI}"
333+
334+
# Execute an extensions profile
335+
C:\Users\Any\VirtualClient> VirtualClient.exe --profile=EXAMPLE-WORKLOAD-PROFILE.json --timeout=1440 --packages="{BlobStoreConnectionString|SAS URI}"
336+
```
337+
338+
The developer can choose to use a custom profile for bootstrapping/installing extensions as well.
339+
340+
``` json
341+
# Profile = BOOTSTRAP-EXTENSIONS.json
342+
{
343+
"Description": "Installs extensions from a package store.",
344+
"Dependencies": [
345+
{
346+
"Type": "DependencyPackageInstallation",
347+
"Parameters": {
348+
"Scenario": "InstallCRCExtensionsPackage",
349+
"BlobContainer": "packages",
350+
"BlobName": "crc.vc.extensions.zip",
351+
"PackageName": "crcvcextensions",
352+
"Extract": true
353+
}
354+
}
355+
]
356+
}
357+
```
322358

323359
## Script-Based Extensions Walkthrough
324360
The following sections provide a bit more guidance on how to develop script-based extensions for Virtual Client and then to integrate them. Virtual Client provides

0 commit comments

Comments
 (0)