XenServer PowerShell Module
===========================

Copyright (c) 2013-2023 Cloud Software Group, Inc. All Rights Reserved.

The XenServer PowerShell Module is a complete SDK for XenServer,
exposing the XenServer API as Windows PowerShell cmdlets.

The XenServer PowerShell Module includes a cmdlet for each API call,
so API documentation and examples written for other languages will apply equally
well to PowerShell. In particular, the SDK Guide and the Management API Guide
are ideal for developers wishing to use this module.

This module is free software. You can redistribute and modify it under the
terms of the BSD 2-Clause license. See LICENSE.txt for details.


Reference
---------

For XenServer documentation see https://docs.citrix.com/en-us/citrix-hypervisor/

The XenServer Management API Reference is available at
https://developer-docs.citrix.com/projects/citrix-hypervisor-management-api/en/latest/

The XenServer Software Development Kit Guide is available at
https://developer-docs.citrix.com/projects/citrix-hypervisor-sdk/en/latest/

A number of examples to help you get started with the SDK is available at
https://github.com/xenserver/xenserver-samples

For community content, blogs, and downloads, visit
https://www.citrix.com/community/citrix-developer/

To network with other developers using XenServer visit
https://discussions.citrix.com/forum/101-hypervisor-formerly-xenserver/


Prerequisites
-------------

This library requires .NET 6.0 and PowerShell 7.2.


Dependencies
------------

The XenServer PowerShell Module is dependent upon the following libraries:

- Newtonsoft JSON.NET by James Newton-King (see https://www.newtonsoft.com/).
  JSON.NET is licensed under the MIT license; see LICENSE.Newtonsoft.Json.txt
  for details. A patched version of the library (Newtonsoft.Json.CH.dll) is
  shipped with the XenServer PowerShell Module.

- XenServer.NET by Cloud Software Group, Inc.
  XenServer.NET is a complete SDK for XenServer, exposing the XenServer
  API as .NET classes. It is written in C#. 


Folder Structure
----------------

This archive contains the following folders that are relevant to PowerShell users:

- XenServerPowerShell\XenServerPSModule: this is the XenServer PowerShell
  Module
- XenServerPowerShell\src: contains the C# source code for the XenServer
  cmdlets shipped as a Visual Studio project.


Getting Started
---------------

1.  Unzip the contents of this archive.

2.  Navigate to the extracted XenServer\XenServerPowerShell directory and copy
    the whole folder XenServerPSModule into your PowerShell modules directory,
    which will normally be $env:UserProfile\Documents\WindowsPowerShell\Modules
    for per-user configuration or $env:windir\system32\WindowsPowerShell\v1.0\Modules
    for system-wide configuration.

3.  Open a PowerShell prompt as administrator.

    To do this, open the Windows Start menu by clicking the Start icon, find
    the item Windows PowerShell, right click it and select Run as administrator.

4.  Determine the current execution policy:

        PS> Get-ExecutionPolicy

    If the current policy is Restricted, you need to set it to RemoteSigned:

        PS> Set-ExecutionPolicy RemoteSigned

    You should understand the security implications of this change. If you
    are unsure, see Microsoft's documentation on the matter:

        PS> Get-Help about_signing

    If the current policy is AllSigned, it will work, but will be very
    inconvenient. You probably want to change it to RemoteSigned, as above.

    If the current policy is Unrestricted or RemoteSigned, it is compatible with
    the XenServer PowerShell Module, so there is nothing to do.

5.  Exit the privileged instance of PowerShell.

6.  Open a PowerShell prompt as a regular user (click Start > Windows PowerShell)
    and import the XenServer PowerShell Module:

        PS> Import-Module XenServerPSModule

7.  If you wish to load specific environment settings when the XenServer
    PowerShell Module is loaded, create the file XenServerProfile.ps1 and put it
    in $env:UserProfile\Documents\WindowsPowerShell for per-user configuration
    or $env:windir\system32\WindowsPowerShell\v1.0 for system-wide configuration.

8.  For an overview of the XenServer PowerShell Module type:

        PS> Get-Help about_XenServer

    You can obtain a list of all available cmdlets by typing:

        PS> Get-Command -Module XenServerPSModule

    For help with a specific command use:

        PS> Get-Help [CommandName]

9.  Here is a quick example of opening a session and making a call to a server:

        PS> Connect-XenServer -Url https://<servername>
        PS> Get-XenVM
        PS> Disconnect-XenServer


Building and Debugging the Source Code
--------------------------------------

1. Open the project XenServerPowerShell.csproj in Visual Studio (2019 or greater).

2. You should now be ready to build the source code.

3. If in Debug mode, clicking Start will launch a PowerShell prompt as an
   external process, and import the compiled XenServerPowerShell.dll as a module
   (without, however, processing the scripts, types, and formats shipped within
   the XenServerPSModule). You should now be ready to debug the cmdlets.
