Appclusive (R) provides a Microsoft PowerShell module which you can use to manage and work with the Appclusive API. This module is built on the C# .NET Client and acts as a convenience wrapper. For more information about the C# .NET Client see the documentation of C# .NET Client.

Installation

Prerequisites:

  • PowerShell 5

The PowerShell client module is available on NuGet and on PowerShellGallery

Install from NuGet

To install the most recent version of the PowerShell client module from NuGet execute the following steps.

  1. Open PowerShell
  2. Install Net.Appclusive.PS.Client from NuGet

    PATH\TO\nuget.exe install Net.Appclusive.PS.Client

  3. Execute PATH\TO\Net.Appclusive.PS.Client\Install.ps1

Install from PowerShellGallery

To install the most recent version of the PowerShell client module from PowerShellGallery execute the following steps.

  1. Open PowerShell
  2. Execute Install-Module -Name Net.Appclusive.PS.Client -AllowClobber

The AllowClobber switch avoids the error during installation that a command with name Enter-Server is already available on the system. As an alias (Apc) is specified the error message can be ignored.

Install from Project

To install the PowerShell client module during development without releasing on NuGet execute the following commands in PowerShell console.

# change to Downloads directory of current user
$downloadsDirectory = "$env:USERPROFILE\Downloads";
cd $downloadsDirectory;
ls -Recurse * | Remove-Item -Recurse -Force;

# install dependent NuGet packages
nuget install biz.dfch.CS.Commons -version 1.12.0;
nuget install biz.dfch.CS.PowerShell.Commons -version 2.0.0;
nuget install Microsoft.Data.Edm -version 5.6.4;
nuget install Microsoft.Data.OData -version 5.6.4;
nuget install Microsoft.Data.Services.Client -version 5.6.4;
nuget install System.Linq.Dynamic -version 1.0.7;
nuget install System.Spatial -version 5.6.4;

# create and install NuGet package Net.Appclusive.PS.Client
nuget pack C:\src\Net.Appclusive.Net.Client\src\Net.Appclusive.PS.Client.nuspec;
nuget install Net.Appclusive.PS.Client -Source $downloadsDirectory -OutputDirectory packages;
.\packages\Net.Appclusive.PS.Client.4.0.0\Install.ps1;

Configuration

The Appclusive API base URI and the credential to be used by the PowerShell client can be specified in the configuration file of the PowerShell client module.

C:\Program Files\WindowsPowerShell\Modules\Net.Appclusive.PS.Client\Net.Appclusive.PS.Client.config

Basic Authentication

Username without domain

<net_Appclusive_PS_Client
    apiBaseUri="http://appclusive/api"
    credential="Arbitrary|[email protected]"
/>

Username with domain

<net_Appclusive_PS_Client
    apiBaseUri="http://appclusive/api"
    credential="MyDomain\Arbitrary|[email protected]"
/>

JWT Authentication

<net_Appclusive_PS_Client
    apiBaseUri="http://appclusive/api"
    credential="[email protected]|JWT_HERE"
/>

Usage

Login (Enter-Server)

The Enter-Server Cmdlet performs a login to an Appclusive server. This is the first Cmdlet to be executed and required for all other Cmdlets of this module. It creates service references to the routers of the application. The Enter-Server Cmdlet defines the following parameter sets.

  • plain

    • Required parameters
      • ApiBaseUri
      • Username
      • Password (Use Username = [email protected] for Bearer authentication)
    • Optional parameters
      • TenantId
  • credential

    • Required parameters
      • ApiBaseUri
      • Credential (Use [email protected] as username of the credential for Bearer authentication)
    • Optional parameters
      • TenantId
  • config

    • Required parameters
      • UseModuleContext
    • Optional parameters
      • TenantId

Invoking Enter-Server with the UseModuleContext switch implies that the Cmdlet ApiBaseUri and Credential will be loaded from the config file (C:\Program Files\WindowsPowerShell\Modules\Net.Appclusive.PS.Client\Net.Appclusive.PS.Client.config).

Code Samples

Import-Module Net.Appclusive.PS.Client

$svc = Enter-ApcServer -ApiBaseUri 'http://appclusive/api' -Username Arbitrary -Password [email protected];
$svc = Enter-ApcServer -ApiBaseUri 'http://appclusive/api' -Username "Mydomain\Arbitrary" -Password [email protected];
$svc = Enter-ApcServer -ApiBaseUri 'http://appclusive/api' -Credential Get-Credential;
$svc = Enter-ApcServer -UseModuleContext;

Get Cmdlets

The Get Cmdlets can be used to retrieve available entities of the corresponding entity set or to get specific entities by Id or Name.

Code Samples

Import-Module Net.Appclusive.PS.Client

$svc = Enter-ApcServer -ApiBaseUri 'http://appclusive/api' -Username Arbitrary -Password [email protected];

Get-ApcTenant

Id          : 11111111-1111-1111-1111-111111111111
Name        : SYSTEM_TENANT
Description : SYSTEM_TENANT
MappedId    : 11111111-1111-1111-1111-111111111111
MappedType  : Internal
ParentId    : 11111111-1111-1111-1111-111111111111
Namespace   : Net.Appclusive
CustomerId  : 0
Details     :
Parent      :
Children    : {}

Get-ApcTenant -Id 11111111-1111-1111-1111-111111111111


Id          : 11111111-1111-1111-1111-111111111111
Name        : SYSTEM_TENANT
Description : SYSTEM_TENANT
MappedId    : 11111111-1111-1111-1111-111111111111
MappedType  : Internal
ParentId    : 11111111-1111-1111-1111-111111111111
Namespace   : Net.Appclusive
CustomerId  : 0
Details     :
Parent      :
Children    : {}

Get-ApcTenant -Name SYSTEM_TENANT


Id          : 11111111-1111-1111-1111-111111111111
Name        : SYSTEM_TENANT
Description : SYSTEM_TENANT
MappedId    : 11111111-1111-1111-1111-111111111111
MappedType  : Internal
ParentId    : 11111111-1111-1111-1111-111111111111
Namespace   : Net.Appclusive
CustomerId  : 0
Details     :
Parent      :
Children    : {}

New Cmdlets

The New Cmdlets can be used to create entities of the corresponding entity set.

Code Samples

Import-Module Net.Appclusive.PS.Client

$svc = Enter-ApcServer -ApiBaseUri 'http://appclusive/api' -Username Arbitrary -Password [email protected];

New-ApcAcl -Name ArbitraryAcl -ParentId 1 -Svc $svc;

ParentId      : 1
NoInheritance : False
Id            : 13
Name          : ArbitraryAcl
Description   : ArbitraryAcl
Parent        :
Children      : {}
Aces          : {}
Details       :

Utility Methods

The Net.Appclusive.PS.Client provides some C# utilty methods. These methods are extension methods and are not yet exposed as Cmdlets. The extension methods are there to simplify the usage of the Data Service Context.

Code Samples

Import-Module Net.Appclusive.PS.Client

$svc = Enter-ApcServer -ApiBaseUri 'http://appclusive/api' -Username Arbitrary -Password [email protected];

$filterQuery = "Name eq 'TestUser'";
[Net.Appclusive.Api.DataServiceQueryExtensions]::Filter($svc.Core.Users, $filterQuery);
[Net.Appclusive.Api.DataServiceQueryExtensions]::Id($svc.Core.Users, 1);