IntelECSClientLibrary 1.2.990

Intel® Endpoint Cloud Services Library Usage

Notices

Intel Confidential

Legal Notices and Disclaimers

All information provided here is subject to change without notice. Contact your Intel representative to obtain the latest Intel product specifications and roadmaps. Intel technologies’ features and benefits depend on system configuration and may require enabled hardware, software or service activation. Performance varies depending on system configuration. No computer system can be absolutely secure. Check with your system manufacturer or retailer or learn more at intel.com. No license (express or implied, by estoppel or otherwise) to any intellectual property rights is granted by this document. The products described may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request. Intel disclaims all express and implied warranties, including without limitation, the implied warranties of merchantability, fitness for a particular purpose, and non-infringement, as well as any warranty arising from course of performance, course of dealing, or usage in trade. Intel, the Intel logo, Intel Unite, Intel vPro, and Intel Core are trademarks of Intel Corporation in the United States and/or other countries. *Other names and brands may be claimed as the property of others © Intel Corporation.

About

This library is a .NET Standard class library that provides common cloud service APIs for Intel® Endpoint Cloud Service. This library can be integrated into a software agent and allows the execution of Intel® Endpoint Cloud Service modules.

Requirements

• The agent application must be executed with elevated privileges.
• The platform setting for the agent solution must be configured as x64.

Installation

Client

1. Add nuget the IntelECSClientLibrary package from nuget.org to your project.

Modules

The Intel® Device Health and Chip to Cloud modules have been conveniently bundled within the primary NuGet package. Upon integrating this package into your main project, these modules will be seamlessly linked and copied into the project directory during the build process.

Below is an illustrative example of the expected output directory structure.

Chip to Cloud

. targetdir
├─ Modules                                       
│  └─ c2c
│     ├─ Intel.C2C.Client.Module.dll
│     └─ rpc.dll

Intel® Device Health

. targetdir
├─ Modules                                       
│  └─ idh
│     ├─ Intel.Idh.Ccss.Interface.Lib.dll

The Intel® Device Health module requires some assemblies to be co-located with the agent's main executable.

. targetdir
├─ ...
├─ applicationprovider.dll
├─ CCHWAPIExt.sys
├─ collector.dll
├─ Collector.Net.Lib.dll
├─ cpuprovider.dll
├─ csmeprovider.dll
├─ driverprovider.dll
├─ firmwareversionprovider.dll
├─ LibCSMEInterface.dll
├─ osprovider.dll
├─ serviceprovider.dll
├─ systeminfoprovider.dll
├─ ...
└─ agent.exe

How to use it

Create an instance of the client.

var client = ClientFactory.Create();

Optionally, a logger instance can be used.

class CustomLogger : ILogger
{
  public void LogMessage(...); // Method body ommited on purpose for simplicity
  public void LogException(...); // Method body ommited on purpose for simplicity
}

var logger = new CustomLogger();
var client = ClientFactory.Create(logger); // This instance will use LogLevel.information as default value

Optionally, a logger instance with a specific LogLevel

class CustomLogger : ILogger
{
  public void LogMessage(...); // Method body ommited on purpose for simplicity
  public void LogException(...); // Method body ommited on purpose for simplicity
}

var logger = new CustomLogger();
// This instance will modify the log level for the modules
var client = ClientFactory.Create(logger, (clientOptions) => {
    clientOptions.LogLevel = LogLevel.Debug;
});

Provisioning

The first time the client library is used on the device, a provisioning call should be performed. The credential information is obtained when the device is created in the registry service.

var args = new ProvisioningParameters
{
    ClientId = "", // The clientId of the credential for the current device
    UserName = "", // The username of the credential for the current device
    Password = "", // The password of the credential for the current device
    DeviceId = "", // The id of the current device
    ApiUrl   = ""  // The cloud services endpoint: Default: https://endpointcloudservices.intel.com
};
await client.ProvisionAsync(args);

Subsequent calls will override the previous information.

Executing modules

The client library executes all modules in the Modules directory.

// Option 1: Execute all modules
await client.ExecuteAsync();

// Option 2: Execute all modules and pass some properties to some of them
var moduleProperties = new ModuleExecutionProperties
{
    { "amt_password", "password_value" },
    { "json_sample", "{{ \"key\": \"value\" }}" }
};
//The executeParameter allow 
var executeParameters = new ExecuteParameters
{
    // There are two ways to pass properties to the modules by module id or module name 
    { Guid.Parse("09DEF649-E133-4E97-A2A5-B40C208913A0"), moduleProperties },
    { "SampleModule", moduleProperties },
};

ExecutionResult results = await client.ExecuteAsync(executeParameters);
foreach (var moduleResult in results.ModuleExecutionResults)
{
    Console.WriteLine($"Result: {moduleResult.Success}. Module Id: {moduleResult.ModuleId}. Details: {moduleResult.ResultDetails}");
}

Forcing module execution

For non-scheduled executions, the ForceExecuteAsync can be used. A list of the modules to be executed must be passed.

// Option 1: Execute only the modules provided
var modules = client.GetModules();
var modulesToBeExecuted = new List<IModuleInfo>();
await client.ForceExecuteAsync(modulesToBeExecuted);

// Option 2: Execute only the modules provided and pass properties to them
var moduleProperties = new ModuleExecutionProperties
{
    { "amt_password", "password_value" },
    { "json_sample", "{{ \"key\": \"value\" }}" }
};

//
var forceExecuteParameters = new ForceExecuteParameters
{
    // There are two ways to pass properties to the modules by module id or module name 
    { Guid.Parse("09DEF649-E133-4E97-A2A5-B40C208913A0"), moduleProperties },
    { "SampleModule", moduleProperties },
};

ExecutionResult results = await client.ForceExecuteAsync(forceExecuteParameters);

foreach (var moduleResult in results.ModuleExecutionResults)
{
    Console.WriteLine($"Result: {moduleResult.Success}. Module Id: {moduleResult.ModuleId}. Details: {moduleResult.ResultDetails}");
}

Unprovisioning

In the case of uninstalling the agent, an unprovisioning call should be performed

await client.UnprovisionAsync();

This will delete all cached data used by the client from the device

Troubleshooting

Module execution in .NetCore

When working with .NET Core, there is an additional step required to execute Intel® Device Health module. After you have successfully built your project, follow these instructions:

• Navigate to your project's build folder.
• Search for a file named < project Name >.runtimeconfig.json.
• Inside this JSON file, you'll need to add the following configuration properties within the runtimeOptions section:

{
  "runtimeOptions": {
    // other options
    "configProperties": {
      "System.Reflection.Metadata.MetadataUpdater.IsSupported": false,
      "Microsoft.NETCore.DotNetHostPolicy.SetAppPaths": true
    }
  }
}

This configuration step is essential to ensure the proper execution of your module in the .NET Core environment.