### Minimal Configuration Example

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/configuration.md

A basic configuration setup for the EngItemService, including authentication and a simple search query.

```csharp
var passport = new UserPassport("https://auth.example.com");
await passport.CASLogin("user", "pass", rememberMe: true);

var service = new EngItemService(
    "https://3dspace.example.com/api",
    passport);

var items = await service.Search<IEngItemDefaultMask>(
    new SearchQuery("*"));
```

--------------------------------

### Perform GET Request with Manual Query Parameters

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/configuration.md

Illustrates how to construct and send a GET request with custom query parameters, overriding or specifying parameters like $mask, $skip, $top, and $fields.

```csharp
var queryParams = new Dictionary<string, string>
{
    { "$mask", "dskern:Mask.Default" },
    { "$skip", "100" },
    { "$top", "50" },
    { "$fields", "attribute.hasConfiguredInstance" }
};
var response = await service.GetAsync(endpoint, queryParams);
```

--------------------------------

### Basic GET Request with Query Parameters

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EnoviaBaseService.md

Demonstrates a basic GET request using EngItemService, including setting security context, tenant, and custom query parameters like $mask, $skip, and $top.

```csharp
var service = new EngItemService("https://3dspace.example.com/api", passport);
service.SecurityContext = "default";
service.Tenant = "myTenant";

var queryParams = new Dictionary<string, string>
{
    { "$mask", "dskern:Mask.Default" },
    { "$skip", "0" },
    { "$top", "50" }
};

var response = await service.GetAsync("/resources/v1/modeler/dseng/dseng:EngItem", queryParams);
var content = await response.Content.ReadAsStringAsync();
```

--------------------------------

### SearchQuery Example Usage

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/types.md

Demonstrates how to instantiate a SearchQuery, add filter conditions, and obtain the final search string.

```csharp
var query = new SearchQuery("*");
query.AddFilter("attribute.title", "Bracket*");
query.AddFilter("attribute.type", "VPMReference");
string searchStr = query.GetSearchString();
```

--------------------------------

### Enterprise Configuration Example

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/configuration.md

An advanced configuration for EngItemService and UserInfoService, setting security context, tenant, and user-specific preferences.

```csharp
var passport = new UserPassport("https://auth.example.com");
await passport.CASLogin("user", "pass", rememberMe: true);

var service = new EngItemService(
    "https://3dspace.example.com/api",
    passport);

service.SecurityContext = "enterprise";
service.Tenant = "myCompany";

var userService = new UserInfoService(
    "https://3dspace.example.com/api",
    passport,
    _tenant: "myCompany");

userService.IncludeCollaborativeSpaces = true;
userService.IncludePreferredCredentials = true;

var currentUser = await userService.GetCurrentUserInfoAsync();
```

--------------------------------

### GetAsync Request Example

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EnoviaBaseService.md

Executes an HTTP GET request to a specified endpoint with optional query parameters and headers. Use this for retrieving data from Enovia services.

```csharp
var queryParams = new Dictionary<string, string> 
{
    { "$mask", "dskern:Mask.Default" },
    { "$skip", "0" },
    { "$top", "100" }
};
HttpResponseMessage response = await service.GetAsync("/resources/v1/modeler/dseng/dseng:EngItem/ITEM123", queryParams);
```

--------------------------------

### SearchInstances Example

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngInstanceService.md

Searches for instances matching specific criteria using a SearchQuery object. Supports pagination with skip and top parameters.

```csharp
var query = new SearchQuery("*");
query.AddFilter("attribute.type", "VPMInstance");

var instances = await service.SearchInstances<IEngInstanceDefaultMask>(
    query,
    skip: 0,
    top: 50);

Console.WriteLine($"Found {instances.Count} instances");
```

--------------------------------

### GetCSRFToken Usage Example

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EnoviaBaseService.md

Example of how to retrieve a CSRF token and use it for subsequent mutation requests.

```csharp
string csrfToken = await service.GetCSRFToken();
// Use for mutation requests
```

--------------------------------

### EngInstancePatch Implementation

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/SharedUtilities.md

An example implementation of IItemPatch for patching an engineering instance. Shows how to define properties and implement change tracking.

```csharp
public class EngInstancePatch : IItemPatch
{
    public string title { get; set; }
    public string description { get; set; }
    
    // ITrackPropertyChanging implementation
    public string[] GetChangedProperties() { /* ... */ }
    public bool IsPropertyChanged(string name) { /* ... */ }
}
```

--------------------------------

### Example Implementation of GetSearchResource

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/SearchService.md

Provides a concrete implementation for the abstract GetSearchResource method, returning the relative path to the search endpoint.

```csharp
protected override string GetSearchResource()
{
    return "/resources/v1/modeler/dseng/dseng:EngItem/search";
}
```

--------------------------------

### EngInstancePatch Example Usage

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/types.md

Shows how to create an EngInstancePatch object to specify partial updates for an engineering instance and then apply it using the UpdateInstance method.

```csharp
var patch = new EngInstancePatch 
{
    title = "New Title",
    description = "Updated Description"
};

await service.UpdateInstance<T>(itemId, instanceId, patch);
```

--------------------------------

### GetConfiguredInstances Example

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngInstanceService.md

Retrieves configured variant instances under a specific configuration. Use this to fetch variants based on a base instance and a configuration ID.

```csharp
var configured = await service.GetConfiguredInstances<IEngInstanceDefaultMask>(
    "BASE_INSTANCE",
    "CONFIG_ID");

foreach (var variant in configured)
{
    Console.WriteLine($"Variant: {variant.title}");
}
```

--------------------------------

### Tenant Property Setting

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EnoviaBaseService.md

Example of setting the Tenant property to automatically include tenant information in requests.

```csharp
service.Tenant = "myTenant";
```

--------------------------------

### UpdateInstance Example

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngInstanceService.md

Updates instance attributes with new data. Provide the instance ID and a patch object containing the attributes to modify.

```csharp
var update = new EngInstancePatch 
{
    title = "New Instance Title",
    description = "Updated description"
};

var updated = await service.UpdateInstance<IEngInstanceDetailsMask>(
    "INSTANCE123",
    update);
```

--------------------------------

### IEngInstanceBulkUpdateItem Array Example

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/types.md

Illustrates how to construct an array of IEngInstanceBulkUpdateItem objects for performing bulk updates on engineering instances, specifying IDs and updatable fields for each item.

```csharp
var updates = new IEngInstanceBulkUpdateItem[] 
{
    new { id = "ID1", title = "New Title 1" },
    new { id = "ID2", title = "New Title 2" }
};

await service.AddInstanceBulkUpdate<T>(itemId, updates);
```

--------------------------------

### DeleteInstance Example

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngInstanceService.md

Deletes a specific instance by its ID. An optional change authoring context can be provided.

```csharp
await service.DeleteInstance("INSTANCE123");
Console.WriteLine("Instance deleted");
```

--------------------------------

### BulkUpdateInstances Example

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngInstanceService.md

Updates multiple instances in a single operation, with a maximum of 50 updates. Each update item specifies the instance ID and attributes to change.

```csharp
var updates = new IEngInstanceBulkUpdateItem[]
{
    new { id = "INST001", title = "Updated Title 1" },
    new { id = "INST002", title = "Updated Title 2" },
    new { id = "INST003", title = "Updated Title 3" }
};

var results = await service.BulkUpdateInstances<IEngInstanceDetailsMask>(
    updates);

Console.WriteLine($"Updated {results.Count()} instances");
```

--------------------------------

### SearchCollection: Full Results Example

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/SearchService.md

Demonstrates how to search for all matching items across all pages using SearchCollection. It specifies the JSON property for the results and a SearchQuery object.

```csharp
var searchQuery = new SearchQuery("*");
searchQuery.AddFilter("attribute.title", "Product*");

IList<IEngItemDefaultMask> results = await service.SearchCollection<IEngItemDefaultMask>(
    "member", 
    searchQuery);

foreach (var item in results)
{
    Console.WriteLine($"Found: {item.Title}");
}
```

--------------------------------

### Error Handling with HttpResponseException

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EnoviaBaseService.md

Example demonstrating how to catch HttpResponseException to access HTTP response details from an error.

```csharp
try 
{
    var response = await service.GetAsync("/endpoint");
}
catch (HttpResponseException ex) 
{
    // ex.Response contains the HttpResponseMessage
}
```

--------------------------------

### BulkDeleteInstances Example

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngInstanceService.md

Deletes multiple instances in a single operation, with a maximum of 50 instance IDs. An optional change authoring context can be provided.

```csharp
var toDelete = new[] { "INST001", "INST002", "INST003" };

await service.BulkDeleteInstances(toDelete);

Console.WriteLine($"Deleted {toDelete.Length} instances");
```

--------------------------------

### Simple Full-Text Search Example

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/SearchService.md

Performs a basic full-text search for all items using the SearchCollection method. Requires an initialized EngItemService with URL and passport credentials.

```csharp
var service = new EngItemService(url, passport);
var query = new SearchQuery("*");
var allItems = await service.SearchCollection<IEngItemDefaultMask>("member", query);
```

--------------------------------

### Configure Batch Service Passport with Environment Variables

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/configuration.md

This example shows how to configure the Batch Service Passport using environment variables for client ID and secret, which is useful for security in production environments.

```csharp
var passport = new BatchServicePassport(
    clientId: Environment.GetEnvironmentVariable("BATCH_CLIENT_ID"),
    clientSecret: Environment.GetEnvironmentVariable("BATCH_CLIENT_SECRET"),
    tokenUrl: "https://auth.example.com/oauth/token");

var service = new EngItemService(enoviaUrl, passport);
var items = await service.Search<IEngItemDefaultMask>(query);
```

--------------------------------

### Handling AuthenticationException

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/errors.md

Shows how to catch an AuthenticationException, typically thrown when CAS login or authentication processes fail. The example logs the failure and the HTTP status code from the response.

```csharp
var passport = new UserPassport("https://auth.example.com");

try 
{
    bool success = await passport.CASLogin("user", "wrongpassword", rememberMe: true);
}
catch (AuthenticationException ex)
{
    Console.WriteLine("Login failed: incorrect credentials or CAS server error");
    Console.WriteLine($"Status: {ex.Response.StatusCode}");
}
```

--------------------------------

### UserPassport CASLogin Method Example

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/Authentication.md

Demonstrates how to perform user authentication using the CAS (Central Authentication Service) login. This method is used to establish a session with the CAS server and obtain authentication credentials.

```csharp
var passport = new UserPassport("https://auth.example.com");
bool success = await passport.CASLogin("john.doe", "password123", rememberMe: true);
if (success)
{
    var service = new EngItemService(enoviaUrl, passport);
}
```

--------------------------------

### Get User with All Details

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/UserInfoService.md

Retrieves a user's profile including collaborative spaces and preferred credentials by enabling the respective service properties.

```csharp
var service = new UserInfoService(enoviaUrl, passport);
service.IncludeCollaborativeSpaces = true;
service.IncludePreferredCredentials = true;

var user = await service.GetCurrentUserInfoAsync();

Console.WriteLine($"User: {user.name}");
Console.WriteLine($"Collaboration Spaces:");
foreach (var space in user.collabspaces ?? new List<CollaborativeSpaceAccess>()) 
{
    Console.WriteLine($"  {space.name} (Role: {space.role})");
}
```

--------------------------------

### SearchCollection: Paginated Results Example

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/SearchService.md

Shows how to retrieve a single page of search results using explicit skip and top parameters. This is useful for manual pagination.

```csharp
var searchQuery = new SearchQuery("*");
IList<IEngItemDefaultMask> page1 = await service.SearchCollection<IEngItemDefaultMask>(
    "member", 
    searchQuery, 
    skip: 0, 
    top: 100);

IList<IEngItemDefaultMask> page2 = await service.SearchCollection<IEngItemDefaultMask>(
    "member", 
    searchQuery, 
    skip: 100, 
    top: 100);

Console.WriteLine($"Page 1: {page1.Count} items");
Console.WriteLine($"Page 2: {page2.Count} items");
```

--------------------------------

### Search Items with Default Mask

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/configuration.md

Example of searching for items using the default mask, which automatically includes standard query parameters like $mask and $mva.

```csharp
// Automatic from mask type
var items = await service.Search<IEngItemDefaultMask>(query);
// Adds: $mask=dskern:Mask.Default&$mva=true
```

--------------------------------

### GetAsync

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EnoviaBaseService.md

Executes an HTTP GET request to the specified endpoint with optional query parameters, headers, and CSRF token handling.

```APIDOC
## GET [ENDPOINT]

### Description
Executes an HTTP GET request to the specified endpoint.

### Method
GET

### Endpoint
[ENDPOINT]

### Parameters
#### Path Parameters
None

#### Query Parameters
- **_queryParameters** (IDictionary<string, string>) - Optional - Query string parameters to append to the request.
- **_headers** (IDictionary<string, string>) - Optional - Custom HTTP headers to include in the request.
- **_requiresCsrfToken** (bool) - Optional - Whether the request requires a CSRF token. Defaults to false.
- **_useCsrfCache** (bool) - Optional - Whether to use cached CSRF token or fetch a new one. Defaults to true.

#### Request Body
None

### Request Example
```csharp
var queryParams = new Dictionary<string, string> 
{
    { "$mask", "dskern:Mask.Default" },
    { "$skip", "0" },
    { "$top", "100" }
};
HttpResponseMessage response = await service.GetAsync("/resources/v1/modeler/dseng/dseng:EngItem/ITEM123", queryParams);
```

### Response
#### Success Response (200)
- **HttpResponseMessage** - HTTP response from the server
```

--------------------------------

### Handling UserInfoException

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/errors.md

Demonstrates catching a UserInfoException, which occurs during user information retrieval. The example checks for specific HTTP status codes like Unauthorized and NotFound to provide tailored messages.

```csharp
try 
{
    var user = await userService.GetCurrentUserInfoAsync();
}
catch (UserInfoException ex)
{
    if (ex.Response.StatusCode == System.Net.HttpStatusCode.Unauthorized)
    {
        Console.WriteLine("Session expired, please authenticate again");
    }
    else if (ex.Response.StatusCode == System.Net.HttpStatusCode.NotFound)
    {
        Console.WriteLine("User not found");
    }
}
```

--------------------------------

### Get Instance Details

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngInstanceService.md

Retrieves detailed information for a specific engineering item instance using its ID. Specify the desired mask for the returned details.

```csharp
public async Task<T> GetInstanceDetails<T>(
    string instanceId,
    string itemId = null)
```

```csharp
var service = new EngInstanceService(url, passport);
var details = await service.GetInstanceDetails<IEngInstanceDetailsMask>("INSTANCE123");

Console.WriteLine($"Instance: {details.title}");
Console.WriteLine($"Type: {details.type}");
```

--------------------------------

### Get Current User Info with Options

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/UserInfoService.md

Retrieves information for the currently authenticated user, with options to include collaboration spaces and preferred credentials. Ensure the UserInfoService is properly initialized and configured.

```csharp
var userService = new UserInfoService(
    "https://3dspace.example.com/api", 
    passport);

userService.IncludeCollaborativeSpaces = true;
userService.IncludePreferredCredentials = false;

UserInfo currentUser = await userService.GetCurrentUserInfoAsync();

Console.WriteLine($"User: {currentUser.name}");
Console.WriteLine($"Email: {currentUser.email}");
Console.WriteLine($"PID: {currentUser.pid}");

if (currentUser.collabspaces?.Count > 0)
{
    Console.WriteLine($"Collaboration Spaces: {currentUser.collabspaces.Count}");
}
```

--------------------------------

### Get CSRF Token with Cache Control

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/configuration.md

Demonstrates how to retrieve a CSRF token, with options to use the cached token or fetch a fresh one, bypassing the cache.

```csharp
// Use cached token (if valid)
string token = await service.GetCSRFToken(useCache: true);

// Get fresh token (bypass cache)
string freshToken = await service.GetCSRFToken(useCache: false);
```

--------------------------------

### Handling Instance Not Found (404 Not Found)

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/errors.md

Example of catching an HttpResponseException with a 404 status code, which signifies that a referenced ID does not exist. The catch block verifies the item and instance IDs.

```csharp
try 
{
    var instance = await service.GetInstance<T>(itemId, "INVALID_ID");
}
catch (HttpResponseException ex) when (ex.Response.StatusCode == System.Net.HttpStatusCode.NotFound)
{
    // Verify itemId and instance ID exist
    Console.WriteLine($"Instance not found. Check IDs: {itemId}, instance");
}
```

--------------------------------

### Configure HttpClient Timeout

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/configuration.md

Access the underlying HttpClient handler to configure advanced settings like request timeouts. This example sets a 30-second timeout.

```csharp
var service = new EngItemService(enoviaUrl, passport);

// Access underlying HttpClient for advanced configuration
var handler = service.BaseClientHandler;

// Configure timeout (inherited HttpClient)
var httpClient = new HttpClient(handler) 
{
    Timeout = TimeSpan.FromSeconds(30)
};
```

--------------------------------

### Handling Search Syntax Error (400 Bad Request)

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/errors.md

Example of handling a SearchResponseException with a 400 status code, indicating a malformed search query. It shows the expected error response format.

```csharp
// WRONG
var query = new SearchQuery("*");
query.AddFilter("invalid::syntax", "value");

// CORRECT - proper field paths
var query = new SearchQuery("*");
query.AddFilter("attribute.title", "MyProduct*");
```

--------------------------------

### Initialize UserInfoService

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/UserInfoService.md

Demonstrates how to instantiate the UserInfoService with the Enovia service URL and an authentication provider. Optional tenant can be specified.

```csharp
public UserInfoService(
    string _enoviaService, 
    IPassportAuthentication _auth, 
    string _tenant = null)
```

--------------------------------

### Custom JSON Serialization Options

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/configuration.md

Create custom JsonSerializerOptions for deserializing JSON content. This example sets case insensitivity, camel case naming policy, and indentation.

```csharp
var options = new JsonSerializerOptions
{
    PropertyNameCaseInsensitive = true,
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    WriteIndented = true
};

var user = JsonSerializer.Deserialize<UserInfo>(jsonContent, options);
```

--------------------------------

### Initialize EngItemService with Configuration

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/README.md

Initialize the EngItemService with a URL and passport, then set security context and tenant.

```csharp
var service = new EngItemService(enoviaUrl, passport);
service.SecurityContext = "default";
service.Tenant = "myTenant";
```

--------------------------------

### HTTP GET Operation

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/README.md

Performs an asynchronous GET request to a specified endpoint. Supports query parameters, custom headers, and CSRF token handling.

```csharp
public async Task<HttpResponseMessage> GetAsync(
    string endpoint,
    IDictionary<string, string> queryParameters = null,
    IDictionary<string, string> headers = null,
    bool requiresCsrfToken = false,
    bool useCsrfCache = true)
```

--------------------------------

### Work with Configurations

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngInstanceService.md

Retrieves a base instance and then lists its configured variants based on a specific evolution configuration.

```csharp
var service = new EngInstanceService(url, passport);

// Get base instance
var baseInstance = await service.GetInstanceDetails<IEngInstanceDefaultMask>(
    "BASE_INSTANCE");

Console.WriteLine($
```

--------------------------------

### Get Current User Profile

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/UserInfoService.md

Retrieves the profile information for the currently authenticated user.

```csharp
var service = new UserInfoService(enoviaUrl, passport);
var me = await service.GetCurrentUserInfoAsync();

Console.WriteLine($"Welcome, {me.firstname} {me.lastname}");
Console.WriteLine($"Email: {me.email}");
```

--------------------------------

### SearchQuery Initialization and Filtering

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/SearchService.md

Demonstrates how to create a SearchQuery object to specify search criteria. Use '*' for a full-text search matching all items, and AddFilter to apply specific attribute-based filters.

```csharp
var query = new SearchQuery("*");  // Match all items
query.AddFilter("attribute.title", "MyProduct*");  // Add filter
```

--------------------------------

### Work with Configurations

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngInstanceService.md

Retrieves instance details and configured variants based on a base instance and a specific configuration.

```APIDOC
## GetConfiguredInstances

### Description
Retrieves instances that are configured based on a specified base instance and configuration ID.

### Method
`GetConfiguredInstances<TMask>(string baseInstanceId, string configurationId)`

### Parameters
#### Path Parameters
- **baseInstanceId** (string) - Required - The ID of the base instance.
- **configurationId** (string) - Required - The ID of the configuration to apply.

#### Generic Type Parameters
- **TMask** - Specifies the level of detail for the returned configured instances (e.g., `IEngInstanceDefaultMask`).

### Response
#### Success Response (200)
- Returns a collection of configured instances, each conforming to the specified `TMask` interface.
```

--------------------------------

### Get CSRF Token

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/README.md

Retrieve a Cross-Site Request Forgery (CSRF) token, with an option to disable caching.

```csharp
// CSRF control
string token = await service.GetCSRFToken(useCache: false);
```

--------------------------------

### Initialize EnoviaBaseService

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/configuration.md

Configure the base Enovia service with its URL and an authentication provider. Runtime properties like SecurityContext and Tenant can be set per instance.

```csharp
protected EnoviaBaseService(string enoviaService, IPassportAuthentication _passport)
```

```csharp
var service = new EngItemService(
    "https://3dspace.example.com/api", 
    passport);

service.SecurityContext = "default";
service.Tenant = "myCompanyTenant";
```

--------------------------------

### Get Cookie Container

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/Authentication.md

Retrieves the cookie container that holds session cookies established after a successful CAS login.

```csharp
public CookieContainer GetCookieContainer()
```

--------------------------------

### Initialize UserInfoService

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/configuration.md

Configure the UserInfoService with Enovia service URL, authentication, and an optional tenant. Runtime properties control data inclusion for user queries.

```csharp
public UserInfoService(
    string _enoviaService, 
    IPassportAuthentication _auth, 
    string _tenant = null)
```

```csharp
var userService = new UserInfoService(
    "https://3dspace.example.com/api",
    passport,
    _tenant: "myTenant");

userService.IncludeCollaborativeSpaces = true;
userService.IncludePreferredCredentials = false;

var user = await userService.GetCurrentUserInfoAsync();
```

--------------------------------

### ItemSet JSON Deserialization

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/SharedUtilities.md

Example of deserializing a JSON string into an ItemSet object. Demonstrates how to parse paginated collection data.

```csharp
var json = @"{
    'totalItems': 100,
    'member': [
        { 'id': '1', 'title': 'Item 1' },
        { 'id': '2', 'title': 'Item 2' }
    ]
}";

var itemSet = JsonSerializer.Deserialize<ItemSet<IEngItemDefaultMask>>(json);
```

--------------------------------

### Handling GetLoginTicketException

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/errors.md

Example of catching a GetLoginTicketException during the CAS login process. This demonstrates how to access the response status code for debugging.

```csharp
try 
{
    bool success = await passport.CASLogin("user", "password", rememberMe: true);
}
catch (GetLoginTicketException ex)
{
    // Thrown during step 1: obtaining login ticket
    Console.WriteLine("Cannot obtain login ticket from CAS server");
    Console.WriteLine($"CAS server returned: {ex.Response.StatusCode}");
}
catch (AuthenticationException ex)
{
    // Thrown during step 2: login request fails
    Console.WriteLine("Login failed with valid ticket");
}
```

--------------------------------

### Initialize EngItemService

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngItemService.md

Constructor for the EngItemService, requiring the Enovia service URL and an authentication provider.

```csharp
public EngItemService(string enoviaService, IPassportAuthentication passport)
    : base(enoviaService, passport)
```

--------------------------------

### Build User Directory

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/UserInfoService.md

Constructs a dictionary of user information by iterating through a list of user IDs and fetching each user's details, handling potential UserInfoExceptions.

```csharp
var service = new UserInfoService(enoviaUrl, passport);

var userIds = new[] { "john.doe", "jane.smith", "bob.johnson" };
var users = new Dictionary<string, UserInfo>();

foreach (var userId in userIds)
{
    try
    {
        users[userId] = await service.GetUserInfoByIdAsync(userId);
    }
    catch (UserInfoException)
    {
        Console.WriteLine($"Could not fetch user: {userId}");
    }
}
```

--------------------------------

### Get Instance Parents

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngInstanceService.md

Retrieves the parent engineering items that contain the specified instance. Returns a collection of parent items.

```csharp
public async Task<IEnumerable<T>> GetInstanceParents<T>(string instanceId)
```

```csharp
var parents = await service.GetInstanceParents<IEngItemDefaultMask>(
    "INSTANCE123");

foreach (var parent in parents)
{
    Console.WriteLine($"Parent: {parent.title} ({parent.id})");
}
```

--------------------------------

### Configure UserInfoService for Multi-Tenant

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/UserInfoService.md

Instantiate UserInfoService with a specific tenant ID for multi-tenant deployments.

```csharp
var userService = new UserInfoService(
    "https://3dspace.example.com/api",
    passport,
    _tenant: "myTenant");

var user = await userService.GetCurrentUserInfoAsync();
```

--------------------------------

### Get Instance Attributes

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngInstanceService.md

Retrieves all attributes associated with a given instance ID. The type parameter T represents the interface for the attribute.

```csharp
public async Task<IEnumerable<T>> GetInstanceAttributes<T>(string instanceId)
```

--------------------------------

### EngInstanceService Constructor

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngInstanceService.md

Initializes the EngInstanceService with the Enovia service URL and authentication provider.

```csharp
public EngInstanceService(string enoviaService, IPassportAuthentication passport)
    : base(enoviaService, passport)
```

--------------------------------

### IPropertyUpdate Interface

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/SharedUtilities.md

Represents a single property change for update operations, providing methods to get the property name and its new value.

```APIDOC
## Interface: IPropertyUpdate

### Description
Represents a single property change for update operations.

### Methods
#### GetPropertyName
- **Returns**: string
- **Description**: Property identifier.

#### GetPropertyValue
- **Returns**: object
- **Description**: New value.
```

--------------------------------

### Get Instance Position

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngInstanceService.md

Retrieves the 3D position and orientation of an instance using its ID. The type parameter T must support IEngInstancePositionMask.

```csharp
public async Task<T> GetInstancePosition<T>(string instanceId)
```

```csharp
var position = await service.GetInstancePosition<IEngInstancePositionMask>(
    "INSTANCE123");

Console.WriteLine($"Position: X={position.x}, Y={position.y}, Z={position.z}");
Console.WriteLine($"Orientation: {position.orientation}");
```

--------------------------------

### Create and Configure EngItemService Instance

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/README.md

Instantiates the EngItemService with the API endpoint and passport. Optional security context and tenant can be set.

```csharp
var service = new EngItemService(
    "https://3dspace.example.com/api",
    passport);

// Optional configuration
service.SecurityContext = "default";
service.Tenant = "myCompany";
```

--------------------------------

### Resolving Search Constraint Violation

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/errors.md

Provides a code example showing the incorrect and correct usage of the Search method with respect to type constraints.

```csharp
// WRONG
var results = await service.Search<ICustomType>(query);

// CORRECT
var results = await service.Search<IEngItemDefaultMask>(query);
```

--------------------------------

### POST Request with JSON Body and CSRF Token

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EnoviaBaseService.md

Example of a POST request including a JSON-formatted body and explicitly requiring a CSRF token.

```csharp
var body = JsonSerializer.Serialize(new { title = "New Item" });
var response = await service.PostAsync(
    "/resources/v1/modeler/dseng/dseng:EngItem",
    _body: body,
    _requiresCsrfToken: true);
```

--------------------------------

### Configure Batch Service Passport and Service

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/configuration.md

Set up the BatchServicePassport with client credentials and token URL, then initialize the EngItemService. This is used for processing large result sets in batch operations.

```csharp
var passport = new BatchServicePassport(
    clientId: Environment.GetEnvironmentVariable("BATCH_ID"),
    clientSecret: Environment.GetEnvironmentVariable("BATCH_SECRET"),
    tokenUrl: "https://auth.example.com/oauth/token");

var service = new EngItemService(
    "https://3dspace.example.com/api",
    passport);

service.Tenant = "myCompany";

// Process large result sets
var allItems = await service.Search<IEngItemDefaultMask>(
    new SearchQuery("*"));

foreach (var item in allItems)
{
    // Process each item
}
```

--------------------------------

### Get User Info by ID

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/README.md

Retrieves information for a specific user identified by their user ID. Useful for accessing details of other users in the system.

```csharp
// Get specific user by ID
public async Task<UserInfo> GetUserInfoByIdAsync(string userId)
```

--------------------------------

### Get Current Authenticated User Info

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/README.md

Retrieves information for the currently authenticated user. This includes details like name, email, and roles.

```csharp
// Get current authenticated user
public async Task<UserInfo> GetCurrentUserInfoAsync()
```

--------------------------------

### Load Configuration from File

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/configuration.md

Load application settings from an 'appsettings.json' file using ConfigurationBuilder. This is useful for managing service URLs, authentication details, and other settings.

```csharp
// Using configuration file
var config = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .Build();

var enoviaUrl = config["Enovia:ServiceUrl"];
var passportUrl = config["Enovia:PassportUrl"];
var username = config["Enovia:Username"];
var password = config["Enovia:Password"];
```

--------------------------------

### Get Instance Children

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngInstanceService.md

Retrieves child instances that are contained within a specified parent instance. Supports pagination with skip and top parameters.

```csharp
public async Task<IEnumerable<T>> GetInstanceChildren<T>(
    string instanceId,
    int skip = 0,
    int top = 100)
```

```csharp
var children = await service.GetInstanceChildren<IEngInstanceDefaultMask>(
    "PARENT_INSTANCE");

Console.WriteLine($"Contains {children.Count()} child instances");
```

--------------------------------

### EnoviaBaseService Constructor

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EnoviaBaseService.md

Initializes the EnoviaBaseService with the Enovia service URL and an authentication provider. The constructor sets up the HttpClient and cookie management.

```csharp
protected EnoviaBaseService(string enoviaService, IPassportAuthentication _passport)
```

--------------------------------

### Configure Batch Service Passport with Client Credentials

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/configuration.md

Use this snippet to authenticate services using client credentials. It requires the client ID, client secret, and token URL.

```csharp
var passport = new BatchServicePassport(
    clientId: "service_client_id",
    clientSecret: "service_client_secret",
    tokenUrl: "https://auth.example.com/oauth/token");

var service = new EngItemService(enoviaUrl, passport);
```

--------------------------------

### Create Instance with Change Context

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngItemService.md

Creates a new instance of an item under a specific change action context. This is useful for versioning and managing changes to items.

```csharp
var createReq = new ICreateEngInstances { title = "New Instance" };

// Create instance under a change action
var instances = await service.AddInstance<IEngInstanceDefaultMask>(
    "ITEM123",
    createReq,
    changeAuthoringContext: "CHANGE_ACTION_ID");
```

--------------------------------

### Constructor for SearchService

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/SearchService.md

Initializes the SearchService with the Enovia service URL and an authentication provider. This is a protected constructor intended for derived classes.

```csharp
protected SearchService(string _enoviaService, IPassportAuthentication passport) 
    : base(_enoviaService, passport)
```

--------------------------------

### Manual Pagination with Skip and Top

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/configuration.md

Manually paginate through results by specifying the skip (offset) and top (limit) parameters. This is useful for fetching data in chunks.

```csharp
// Page 1
var page1 = await service.GetInstances<T>(
    itemId,
    skip: 0,
    top: 100);

// Page 2
var page2 = await service.GetInstances<T>(
    itemId,
    skip: 100,
    top: 100);

// Page 3
var page3 = await service.GetInstances<T>(
    itemId,
    skip: 200,
    top: 100);
```

--------------------------------

### Process Instances in Bulk

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngInstanceService.md

Performs bulk updates on multiple instances. First, search for instances, then prepare an array of update items, and finally apply the updates.

```csharp
var service = new EngInstanceService(url, passport);

// Find instances to update
var instances = await service.SearchInstances<IEngInstanceDefaultMask>(
    new SearchQuery("*"),
    top: 50);

// Prepare bulk update
var updates = instances
    .Select(i => new EngInstanceBulkUpdateItem 
    { 
        id = i.id, 
        title = $"Updated_{i.title}"
    })
    .ToArray();

// Apply updates
var results = await service.BulkUpdateInstances<IEngInstanceDetailsMask>(
    updates);

Console.WriteLine($
```

--------------------------------

### Manage Instance Hierarchy

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngInstanceService.md

Retrieves parent items for an instance and then lists its siblings (other children of the same parent).

```csharp
var service = new EngInstanceService(url, passport);

// Get parent items
var parents = await service.GetInstanceParents<IEngItemDefaultMask>(
    "INSTANCE123");

foreach (var parent in parents)
{
    Console.WriteLine($
```

--------------------------------

### Example Implementation of SearchConstraintTypes

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/SearchService.md

Defines the valid mask interface types for search queries, used for runtime constraint validation. This implementation returns types for EngItem.

```csharp
protected override IEnumerable<Type> SearchConstraintTypes()
{
    return new List<Type>() 
    { 
        typeof(IEngItemDefaultMask), 
        typeof(IEngItemCommonMask), 
        typeof(IEngItemDetailsMask) 
    };
}
```

--------------------------------

### Load Configuration from Environment Variables

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/configuration.md

Retrieve configuration values directly from environment variables. This method is suitable for sensitive information like passwords or dynamic service URLs.

```csharp
// Or environment variables
var enoviaUrl = Environment.GetEnvironmentVariable("ENOVIA_URL");
var password = Environment.GetEnvironmentVariable("ENOVIA_PASSWORD");
```

--------------------------------

### Retrieve Instance Details

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngInstanceService.md

Fetches detailed information about a specific instance using its ID. Requires the instance ID and a mask to specify the desired attributes.

```csharp
var service = new EngInstanceService(url, passport);

var instance = await service.GetInstanceDetails<IEngInstanceDetailsMask>(
    "INSTANCE123");

Console.WriteLine($
```

--------------------------------

### ITrackPropertyChanging Interface

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/types.md

Interface for tracking property modifications in objects intended for partial updates. Provides methods to get changed properties and check if a specific property was modified.

```csharp
public interface ITrackPropertyChanging
{
}

// Methods:
// - GetChangedProperties() — Returns list of modified property names
// - IsPropertyChanged(string propertyName) — Checks if specific property was modified
```

--------------------------------

### Get User Info by ID

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/UserInfoService.md

Retrieves information for a specific user using their unique identifier. The user ID is automatically URL-encoded for safe transmission. Ensure the UserInfoService is initialized.

```csharp
var userService = new UserInfoService(
    "https://3dspace.example.com/api", 
    passport);

UserInfo user = await userService.GetUserInfoByIdAsync("john.doe@company.com");

Console.WriteLine($"User: {user.firstname} {user.lastname}");
Console.WriteLine($"Email: {user.email}");
Console.WriteLine($"Company: {user.company?.name}");

foreach (var space in user.collabspaces)
{
    Console.WriteLine($"  - {space.name}");
}
```

--------------------------------

### Manage Hierarchy

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngInstanceService.md

Allows retrieval of parent and child instances, enabling navigation and understanding of the instance hierarchy.

```APIDOC
## GetInstanceParents

### Description
Retrieves the parent items of a given instance.

### Method
`GetInstanceParents<TMask>(string instanceId)`

### Parameters
#### Path Parameters
- **instanceId** (string) - Required - The unique identifier of the instance whose parents are to be retrieved.

#### Generic Type Parameters
- **TMask** - Specifies the level of detail for the returned parent items (e.g., `IEngItemDefaultMask`).

### Response
#### Success Response (200)
- Returns a collection of parent items, each conforming to the specified `TMask` interface.

## GetInstanceChildren

### Description
Retrieves the child instances of a given parent item.

### Method
`GetInstanceChildren<TMask>(string parentItemId)`

### Parameters
#### Path Parameters
- **parentItemId** (string) - Required - The unique identifier of the parent item whose children are to be retrieved.

#### Generic Type Parameters
- **TMask** - Specifies the level of detail for the returned child instances (e.g., `IEngInstanceDefaultMask`).

### Response
#### Success Response (200)
- Returns a collection of child instances, each conforming to the specified `TMask` interface.
```

--------------------------------

### IConfigurationContext Interface

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/SharedUtilities.md

Represents a configuration or evolution context. Use this interface to define objects that hold context identifiers, names, and types.

```csharp
public interface IConfigurationContext
{
    string id { get; set; }
    string name { get; set; }
    string type { get; set; }
}
```

--------------------------------

### Create Item Instance with Change Context

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngItemService.md

Creates a new item instance under a specified change context, such as a change action. This allows for version-controlled creation of instances.

```APIDOC
## AddInstance

### Description
Creates a new item instance for a given item. This operation can be performed under a specific change context, such as a change action, to manage the lifecycle of the instance.

### Method
`await service.AddInstance<T>(string itemId, ICreateEngInstances createReq, string changeAuthoringContext)`

### Parameters
#### Path Parameters
- **itemId** (string) - Required - The ID of the item for which to create an instance.

#### Request Body
- **createReq** (ICreateEngInstances) - Required - An object containing the details for the new instance, such as its title.

#### Query Parameters
- **changeAuthoringContext** (string) - Optional - The ID of the change context (e.g., change action) under which to create the instance.

#### Type Parameters
- **T** (Mask Interface) - Required - Specifies the mask interface to use for the returned instance details (e.g., `IEngInstanceDefaultMask`).

### Request Example
```json
{
  "title": "New Instance Title"
}
```

### Response Example
```json
{
  "id": "new_instance_id",
  "title": "New Instance Title"
}
```
```

--------------------------------

### GetInstances

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngItemService.md

Retrieves all engineering item instances (parts) for a parent item with pagination and configuration options.

```APIDOC
## GET /resources/v1/modeler/dseng/dseng:EngItem/{ID}/dseng:EngInstance

### Description
Retrieves all engineering item instances (parts) for a parent item. Supports pagination and an option to include configured instances.

### Method
GET

### Endpoint
`/resources/v1/modeler/dseng/dseng:EngItem/{ID}/dseng:EngInstance`

### Parameters
#### Path Parameters
- **ID** (string) - Required - The ID of the parent engineering item.

#### Query Parameters
- **skip** (int) - Optional - Default: 0 - Pagination offset.
- **top** (int) - Optional - Default: 100 - Maximum items to return (max 2000).
- **withConfiguredInstances** (bool) - Optional - Default: true - Include `hasConfiguredInstance` attribute in results.

### Response
#### Success Response (200)
- **T** (IEnumerable<T>) - Collection of instances for the given page. `T` must be one of: `IEngInstanceFilterableMask`, `IEngInstancePositionMask`, `IEngInstanceDetailsMask`, `IEngInstanceDefaultMask`.
```

--------------------------------

### Initialize Batch Service Passport for OAuth Authentication

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/README.md

Creates a BatchServicePassport for OAuth authentication. Use this for service-to-service authentication.

```csharp
// Or batch service authentication
var passport = new BatchServicePassport(clientId, clientSecret, tokenUrl);
```

--------------------------------

### HTTP Operations

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/README.md

Provides methods for performing common HTTP operations like GET, POST, PATCH, DELETE, and PUT. These methods abstract the underlying HTTP communication, allowing for easier integration with services.

```APIDOC
## HTTP Operations

All HTTP operations (GET, POST, PATCH, DELETE, PUT) are defined in `EnoviaBaseService`.

### GET Operation

Performs an HTTP GET request.

- **Method**: GET
- **Endpoint**: `endpoint` (string)
- **Parameters**:
  - `endpoint` (string) - Required - The API endpoint to call.
  - `queryParameters` (IDictionary<string, string>) - Optional - Key-value pairs for query parameters.
  - `headers` (IDictionary<string, string>) - Optional - Key-value pairs for request headers.
  - `requiresCsrfToken` (bool) - Optional - Whether a CSRF token is required.
  - `useCsrfCache` (bool) - Optional - Whether to use the CSRF token cache.

### POST Operation

Performs an HTTP POST request.

- **Method**: POST
- **Endpoint**: `endpoint` (string)
- **Parameters**:
  - `endpoint` (string) - Required - The API endpoint to call.
  - `queryParameters` (IDictionary<string, string>) - Optional - Key-value pairs for query parameters.
  - `headers` (IDictionary<string, string>) - Optional - Key-value pairs for request headers.
  - `body` (string) - Optional - The request body content.
  - `bodyIsJson` (bool) - Optional - Indicates if the body is JSON formatted.
  - `requiresCsrfToken` (bool) - Optional - Whether a CSRF token is required.
  - `useCsrfCache` (bool) - Optional - Whether to use the CSRF token cache.

*Note: PATCH, DELETE, and PUT operations follow similar patterns to POST.*
```

--------------------------------

### Retrieve and Update Item Instances

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngItemService.md

Retrieves the first 10 instances of an item and updates their titles. Requires an initialized EngItemService with URL and passport.

```csharp
var service = new EngItemService(url, passport);
string itemId = "ITEM123";

// Get first 10 instances
var instances = await service.GetInstances<IEngInstanceDetailsMask>(
    itemId, 
    skip: 0, 
    top: 10);

// Update each instance
foreach (var instance in instances)
{
    var patch = new EngInstancePatch 
    { 
        title = $"Updated_{instance.title}" 
    };

    var updated = await service.UpdateInstance<IEngInstanceDetailsMask>(
        itemId,
        instance.id,
        patch);

    Console.WriteLine($"Updated: {updated.title}");
}
```

--------------------------------

### Reading Exception Response Content

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/errors.md

When an HttpResponseException occurs, read the response content to get detailed error information, such as a JSON payload. This is crucial for diagnosing issues related to invalid requests or resource problems.

```csharp
catch (HttpResponseException ex)
{
    var content = await ex.Response.Content.ReadAsStringAsync();
    var mediaType = ex.Response.Content.Headers.ContentType?.MediaType;
    
    if (mediaType == "application/json")
    {
        // Parse JSON error response
        var errorJson = JsonSerializer.Deserialize<JsonElement>(content);
    }
}
```

--------------------------------

### IPassportAuthentication Interface Definition

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/Authentication.md

Defines the contract for passport-based authentication mechanisms. It includes methods for authenticating requests, checking authentication type, retrieving cookies, getting identity, and validating the current authentication state.

```csharp
public interface IPassportAuthentication
{
    bool AuthenticateRequest(HttpRequestMessage request, bool refreshAutomatically = true);
    bool IsCookieAuthentication();
    CookieContainer GetCookieContainer();
    string GetIdentity();
    bool IsValid();
}
```

--------------------------------

### Deserialize Items using Service Helper

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/configuration.md

Demonstrates using a service helper method to deserialize JSON content into a collection of items, specifying the item set and item types.

```csharp
// Or using response helper
var items = service.DeserializeItems<ItemSet<T>, T>(jsonContent);
```

--------------------------------

### IConfigurationContext Interface

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/SharedUtilities.md

Represents a configuration or evolution context, defining an identifier, name, and type.

```APIDOC
## Interface: IConfigurationContext

### Description
Represents a configuration/evolution context.

### Properties
- **id** (string) - Configuration identifier
- **name** (string) - Configuration name
- **type** (string) - Configuration type
```

--------------------------------

### Set Tenant for Service Requests

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/configuration.md

Configure the tenant for a service instance. The tenant is automatically included in request headers, query parameters, and resource paths.

```csharp
var service = new EngItemService(enoviaUrl, passport);
service.Tenant = "myCompanyTenant";

// Tenant automatically included in requests
var items = await service.Search<IEngItemDefaultMask>(query);
```

--------------------------------

### Construct Error Response with Details

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/SharedUtilities.md

Demonstrates how to create a GenericResponse object that includes specific error information. This includes setting the error code, message, and detailed field-specific errors.

```csharp
var response = new GenericResponse<T>();
response.data = /* ... */;
response.error = new ErrorInfo 
{
    code = "VALIDATION_ERROR",
    message = "Invalid input",
    details = new Dictionary<string, string>
    {
        { "field", "title" },
        { "reason", "Required field missing" }
    }
};
```

--------------------------------

### Batch Service Passport Authentication (OAuth 2.0)

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/README.md

Initialize a Batch Service Passport for OAuth 2.0 authentication.

```csharp
var passport = new BatchServicePassport(clientId, clientSecret, tokenUrl);
```

--------------------------------

### Handle API Errors with Try-Catch

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngItemService.md

Demonstrates error handling for API calls, specifically catching `SearchResponseException` for search failures and `HttpResponseException` for general HTTP errors. This pattern is crucial for robust API integration.

```csharp
try
{
    var items = await service.Search<IEngItemDefaultMask>(query);
}
catch (SearchResponseException ex)
{
    Console.WriteLine($"Search failed: {ex.Response.StatusCode}");
}
catch (HttpResponseException ex)
{
    Console.WriteLine($"HTTP error: {ex.Response.StatusCode}");
}
```

--------------------------------

### AddInstance

Source: https://github.com/3ds-cpe-emed/ws3dx-dotnet/blob/dev/net8/main_oc_2025x_ga/_autodocs/api-reference/EngItemService.md

Creates a new engineering item instance. It allows specifying parent item ID, instance creation data, and optional change or configuration contexts.

```APIDOC
## POST /resources/v1/modeler/dseng/dseng:EngItem/{ID}/dseng:EngInstance

### Description
Creates a new engineering item instance.

### Method
POST

### Endpoint
/resources/v1/modeler/dseng/dseng:EngItem/{ID}/dseng:EngInstance

### Parameters
#### Path Parameters
- **ID** (string) - Required - The ID of the parent engineering item.

#### Query Parameters
None

#### Request Body
- **request** (ICreateEngInstances) - Required - Instance creation data.
- **changeAuthoringContext** (string) - Optional - Optional change action ID.
- **configurationAuthoringContext** (string) - Optional - Optional configuration/evolution context.

### Headers
- `DS-Change-Authoring-Context`: Set if `changeAuthoringContext` provided
- `DS-Configuration-Authoring-Context`: Set if `configurationAuthoringContext` provided

### Response
#### Success Response (200)
- **T** (IEnumerable<T>) - Newly created instance(s). `T` can be one of: `IEngInstanceFilterableMask`, `IEngInstancePositionMask`, `IEngInstanceDetailsMask`, `IEngInstanceDefaultMask`.

### Request Example
```csharp
var createReq = new ICreateEngInstances 
{
    title = "New Part Instance",
    type = "VPMInstance"
};

var created = await service.AddInstance<IEngInstanceDefaultMask>(
    "ITEM123",
    createReq);

foreach (var instance in created)
{
    Console.WriteLine($"Created: {instance.id}");
}
```
```