or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mdindex.mdoperations.mdpipeline.mdpolicies.mdserialization.mdservice-client.md
tile.json

index.mddocs/

Azure Core Client

Azure Core Client is a foundational HTTP client library for building Azure SDK client libraries generated by AutoRest. It provides the essential building blocks for Azure service communication including ServiceClient base class, HTTP pipeline management, comprehensive serialization/deserialization infrastructure, and standardized patterns for Azure service interaction.

Package Information

  • Package Name: @azure/core-client
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @azure/core-client

Core Imports

import { 
  ServiceClient, 
  createClientPipeline, 
  createSerializer,
  type ServiceClientOptions,
  type OperationSpec,
  type OperationArguments
} from "@azure/core-client";

For CommonJS:

const { 
  ServiceClient, 
  createClientPipeline, 
  createSerializer 
} = require("@azure/core-client");

Basic Usage

import { ServiceClient, createClientPipeline } from "@azure/core-client";
import type { TokenCredential } from "@azure/core-auth";

// Create a service client for an Azure service
class MyAzureClient extends ServiceClient {
  constructor(endpoint: string, credential: TokenCredential) {
    const pipeline = createClientPipeline({
      credentialOptions: {
        credential,
        credentialScopes: ["https://management.azure.com/.default"]
      }
    });

    super({
      endpoint,
      pipeline
    });
  }

  async listResources(): Promise<any> {
    const operationSpec: OperationSpec = {
      httpMethod: "GET",
      path: "/subscriptions/{subscriptionId}/resources",
      serializer: createSerializer(),
      responses: {
        200: {
          bodyMapper: {
            type: { name: "Composite" },
            serializedName: "ResourceList"
          }
        }
      }
    };

    return this.sendOperationRequest({}, operationSpec);
  }
}

Architecture

Azure Core Client is built around several key components:

  • ServiceClient: Base class providing sendRequest and sendOperationRequest methods for HTTP operations
  • HTTP Pipeline: Customizable request/response processing pipeline with policies for serialization, authentication, and more
  • Serialization System: Mapper-based framework for transforming data between JavaScript objects and HTTP payloads
  • Operation Specifications: Structured definitions of HTTP operations derived from OpenAPI/Swagger specifications
  • Authentication: Support for OAuth bearer tokens with challenge handling for Azure services
  • Type System: Comprehensive TypeScript definitions for all aspects of HTTP operations and data modeling

Capabilities

Service Client

Core HTTP client class that provides the foundation for all Azure SDK clients. Handles request/response lifecycle with operation specifications and HTTP pipeline integration.

class ServiceClient {
  constructor(options?: ServiceClientOptions);
  sendRequest(request: PipelineRequest): Promise<PipelineResponse>;
  sendOperationRequest<T>(operationArguments: OperationArguments, operationSpec: OperationSpec): Promise<T>;
  readonly pipeline: Pipeline;
}

interface ServiceClientOptions extends CommonClientOptions {
  baseUri?: string; // deprecated
  endpoint?: string;
  credentialScopes?: string | string[];
  requestContentType?: string;
  credential?: TokenCredential;
  pipeline?: Pipeline;
}

Service Client

HTTP Pipeline Management

Pipeline creation and configuration for HTTP request/response processing with built-in policies for serialization, deserialization, and authentication.

function createClientPipeline(options?: InternalClientPipelineOptions): Pipeline;

interface InternalClientPipelineOptions extends InternalPipelineOptions {
  credentialOptions?: {
    credentialScopes: string | string[];
    credential: TokenCredential;
  };
  deserializationOptions?: DeserializationPolicyOptions;
  serializationOptions?: SerializationPolicyOptions;
}

Pipeline Management

Serialization Framework

Comprehensive mapper-based system for transforming data between user-friendly JavaScript objects and HTTP request/response payloads based on OpenAPI specifications.

function createSerializer(modelMappers?: { [key: string]: any }, isXML?: boolean): Serializer;

interface Serializer {
  serialize(mapper: Mapper, object: any, objectName?: string, options?: SerializerOptions): any;
  deserialize(mapper: Mapper, responseBody: any, objectName: string, options?: SerializerOptions): any;
  validateConstraints(mapper: Mapper, value: any, objectName: string): void; // deprecated
  readonly modelMappers: { [key: string]: any };
  readonly isXML: boolean;
}

Serialization

Operation Specifications

Structured definitions of HTTP operations derived from OpenAPI/Swagger specifications, including parameter mappings, response handling, and serialization instructions.

interface OperationSpec {
  serializer: Serializer;
  httpMethod: HttpMethods;
  baseUrl?: string;
  path?: string;
  contentType?: string;
  requestBody?: OperationParameter;
  urlParameters?: ReadonlyArray<OperationURLParameter>;
  queryParameters?: ReadonlyArray<OperationQueryParameter>;
  headerParameters?: ReadonlyArray<OperationParameter>;
  responses: { [responseCode: string]: OperationResponseMap };
}

interface OperationArguments {
  [parameterName: string]: unknown;
  options?: OperationOptions;
}

Operation Specifications

Authentication Support

Built-in support for OAuth bearer token authentication with challenge handling for Continuous Access Evaluation (CAE) and tenant-specific scenarios.

async function authorizeRequestOnClaimChallenge(
  onChallengeOptions: AuthorizeRequestOnChallengeOptions
): Promise<boolean>;

const authorizeRequestOnTenantChallenge: (
  challengeOptions: AuthorizeRequestOnChallengeOptions
) => Promise<boolean>;

Authentication

Pipeline Policies

Extensible policy system for HTTP request/response processing, including built-in serialization and deserialization policies.

function serializationPolicy(options?: SerializationPolicyOptions): PipelinePolicy;
function deserializationPolicy(options?: DeserializationPolicyOptions): PipelinePolicy;

const serializationPolicyName: string;
const deserializationPolicyName: string;

Pipeline Policies

Types

Core Types

// Common client options
interface CommonClientOptions extends PipelineOptions {
  httpClient?: HttpClient;
  allowInsecureConnection?: boolean;
  additionalPolicies?: AdditionalPolicyConfig[];
}

// Operation options
interface OperationOptions {
  abortSignal?: AbortSignalLike;
  requestOptions?: OperationRequestOptions;
  tracingOptions?: OperationTracingOptions;
  serializerOptions?: SerializerOptions;
  onResponse?: RawResponseCallback;
}

// Response handling
interface FullOperationResponse extends PipelineResponse {
  parsedHeaders?: { [key: string]: unknown };
  parsedBody?: unknown;
  request: OperationRequest;
}

type RawResponseCallback = (
  rawResponse: FullOperationResponse,
  flatResponse: unknown,
  error?: unknown
) => void;

Utility Types

// XML processing
const XML_ATTRKEY: string;
const XML_CHARKEY: string;

interface XmlOptions {
  rootName?: string;
  includeRoot?: boolean;
  xmlCharKey?: string;
}

// Query parameter formatting
type QueryCollectionFormat = "CSV" | "SSV" | "TSV" | "Pipes" | "Multi";

// Parameter path specification
type ParameterPath = string | string[] | { [propertyName: string]: ParameterPath };

// Serialization options
interface SerializerOptions {
  xml: XmlOptions;
  ignoreUnknownProperties?: boolean;
}