0
# Configuration Management
1

2
Hierarchical configuration system with support for literate configuration documents, command-line overrides, and extensible validation. AutoRest Core provides a sophisticated configuration merging system that handles multiple configuration sources and formats.
3

4
## Capabilities
5

6
### ConfigurationView Interface
7

8
Provides access to the merged configuration state with additional metadata and utilities.
9

10
```typescript { .api }
11
/**
12
 * Configuration view providing access to merged configuration state
13
 * Contains resolved configuration values and metadata
14
 */
15
interface ConfigurationView {
16
  /** Array of input file URIs resolved from configuration */
17
  InputFileUris: Array<string>;
18
  
19
  /** Raw configuration object after merging */
20
  Raw: any;
21
  
22
  /** Message emitter for configuration-related messages */
23
  messageEmitter: MessageEmitter;
24
  
25
  /** Cancellation token for operations */
26
  CancellationToken: CancellationToken;
27
  
28
  /** Cancellation token source */
29
  CancellationTokenSource: CancellationTokenSource;
30
  
31
  /**
32
   * Get a specific configuration entry
33
   * @param key - Configuration key to retrieve
34
   * @returns Configuration value or undefined
35
   */
36
  GetEntry(key: string): any;
37
}
38
```
39

40
### AutoRest Configuration Interface
41

42
Comprehensive configuration interface defining all supported AutoRest options.
43

44
```typescript { .api }
45
/**
46
 * AutoRest configuration implementation interface
47
 * Defines all supported configuration options
48
 */
49
interface AutoRestConfigurationImpl {
50
  /** Information or conditional directive */
51
  __info?: string | null;
52
  
53
  /** Allow processing with no input files */
54
  "allow-no-input"?: boolean;
55
  
56
  /** Input OpenAPI specification files */
57
  "input-file"?: string[] | string;
58
  
59
  /** Base folder for relative paths */
60
  "base-folder"?: string;
61
  
62
  /** Processing directives for transformations */
63
  "directive"?: Directive[] | Directive;
64
  
65
  /** Custom directive declarations */
66
  "declare-directive"?: { [name: string]: string };
67
  
68
  /** Output artifacts to generate */
69
  "output-artifact"?: string[] | string;
70
  
71
  /** Message output format */
72
  "message-format"?: "json" | "yaml" | "regular";
73
  
74
  /** Extensions to use during processing */
75
  "use-extension"?: { [extensionName: string]: string };
76
  
77
  /** Required extensions */
78
  "require"?: string[] | string;
79
  
80
  /** Optional extensions */
81
  "try-require"?: string[] | string;
82
  
83
  /** Help information */
84
  "help"?: any;
85
  
86
  /** VS Code specific behavior */
87
  "vscode"?: any;
88
  
89
  /** Override OpenAPI info section */
90
  "override-info"?: any;
91
  
92
  /** Override OpenAPI title */
93
  "title"?: any;
94
  
95
  /** Override OpenAPI description */
96
  "description"?: any;
97
  
98
  /** Enable debug mode */
99
  "debug"?: boolean;
100
  
101
  /** Enable verbose output */
102
  "verbose"?: boolean;
103
  
104
  /** Output file name */
105
  "output-file"?: string;
106
  
107
  /** Output folder path */
108
  "output-folder"?: string;
109
  
110
  /** Client-side validation (language specific) */
111
  "client-side-validation"?: boolean;
112
  
113
  /** Fluent interface generation */
114
  "fluent"?: boolean;
115
  
116
  /** Azure ARM specific settings */
117
  "azure-arm"?: boolean;
118
  
119
  /** Target namespace */
120
  "namespace"?: string;
121
  
122
  /** License header template */
123
  "license-header"?: string;
124
  
125
  /** Add credential parameters */
126
  "add-credentials"?: boolean;
127
  
128
  /** Package name for target language */
129
  "package-name"?: string;
130
  
131
  /** Package version */
132
  "package-version"?: string;
133
  
134
  /** Synchronization method generation */
135
  "sync-methods"?: "all" | "essential" | "none";
136
  
137
  /** Payload flattening threshold */
138
  "payload-flattening-threshold"?: number;
139
  
140
  /** OpenAPI specification type */
141
  "openapi-type"?: string;
142
}
143
```
144

145
### Configuration Merging
146

147
Functions for combining multiple configuration sources with proper precedence handling.
148

149
```typescript { .api }
150
/**
151
 * Merge multiple configurations with proper precedence
152
 * @param configs - Configuration objects to merge (higher index = higher priority)
153
 * @returns Merged configuration object
154
 */
155
function MergeConfigurations(...configs: AutoRestConfigurationImpl[]): AutoRestConfigurationImpl;
156
```
157

158
### Directive System
159

160
Configuration directives provide powerful transformation capabilities.
161

162
```typescript { .api }
163
/**
164
 * Processing directive for transformations
165
 * Defines how to modify OpenAPI specifications during processing
166
 */
167
interface Directive {
168
  /** Conditional guard for directive application */
169
  where?: string;
170
  
171
  /** Reason for the directive */
172
  reason?: string;
173
  
174
  /** JSONPath selector for target elements */
175
  from?: string;
176
  
177
  /** Transformation to apply */
178
  transform?: string;
179
  
180
  /** Set property values */
181
  set?: { [key: string]: any };
182
  
183
  /** Remove elements */
184
  remove?: boolean;
185
  
186
  /** Rename elements */
187
  rename?: { [oldName: string]: string };
188
}
189
```
190

191
**Usage Examples:**
192

193
```typescript
194
import { AutoRest } from "@microsoft.azure/autorest-core";
195

196
// Basic configuration
197
const autorest = new AutoRest();
198

199
autorest.AddConfiguration({
200
  "input-file": "swagger.json",
201
  "output-folder": "./generated",
202
  "namespace": "MyApi.Client",
203
  "client-name": "MyApiClient"
204
});
205

206
// Advanced configuration with directives
207
autorest.AddConfiguration({
208
  "directive": [
209
    {
210
      "where": "$.paths..operationId",
211
      "transform": "return $.replace(/([a-z])([A-Z])/g, '$1_$2').toLowerCase()"
212
    },
213
    {
214
      "where": "$.definitions.Pet",
215
      "set": {
216
        "description": "Updated pet description"
217
      }
218
    }
219
  ]
220
});
221

222
// Multiple input files
223
autorest.AddConfiguration({
224
  "input-file": [
225
    "api1.json",
226
    "api2.json",
227
    "common-definitions.json"
228
  ],
229
  "base-folder": "./specs"
230
});
231

232
// Language-specific settings
233
autorest.AddConfiguration({
234
  "output-folder": "./src/generated",
235
  "namespace": "MyCompany.ApiClient",
236
  "package-name": "my-api-client",
237
  "package-version": "1.0.0",
238
  "client-side-validation": true,
239
  "sync-methods": "essential"
240
});
241
```
242

243
### Configuration Access
244

245
```typescript
246
// Access configuration after merging
247
const configView = await autorest.view;
248

249
// Get specific values
250
const inputFiles = configView.InputFileUris;
251
const outputFolder = configView.GetEntry("output-folder");
252
const debugMode = configView.GetEntry("debug");
253
const namespace = configView.GetEntry("namespace");
254

255
// Access raw merged configuration
256
const rawConfig = configView.Raw;
257
console.log("Full configuration:", rawConfig);
258

259
// Check for conditional configurations
260
if (configView.GetEntry("azure-arm")) {
261
  console.log("Azure ARM mode enabled");
262
}
263
```
264

265
### Literate Configuration
266

267
```typescript { .api }
268
/**
269
 * Functions for working with literate configuration documents
270
 */
271

272
/** Check if content is a configuration document */
273
function IsConfigurationDocument(content: string): Promise<boolean>;
274

275
/** Check if file extension indicates configuration */
276
function IsConfigurationExtension(extension: string): Promise<boolean>;
277
```
278

279
**Example literate configuration:**
280

281
```markdown
282
# API Client Configuration
283

284
This configuration generates a TypeScript client for the Pet Store API.
285

286
> see https://aka.ms/autorest
287

288
``` yaml
289
input-file: petstore.json
290
output-folder: ./generated
291
namespace: PetStore.Client
292
client-name: PetStoreClient
293
```
294

295
## Advanced Options
296

297
``` yaml
298
directive:
299
  - where: $.paths..operationId
300
    transform: return $.replace(/([a-z])([A-Z])/g, '$1_$2').toLowerCase()
301
  
302
  - where: $.definitions.Pet.properties.status
303
    set:
304
      enum: ["available", "pending", "sold"]
305
```
306
```
307
308
### Configuration Validation
309

310
```typescript
311
// Validate configuration before processing
312
const autorest = new AutoRest(new RealFileSystem());
313

314
autorest.AddConfiguration({
315
  "input-file": "nonexistent.json",
316
  "output-folder": "./generated"
317
});
318

319
// Configuration validation happens during view creation
320
try {
321
  const config = await autorest.view;
322
  console.log("Configuration is valid");
323
} catch (error) {
324
  console.error("Configuration error:", error.message);
325
}
326

327
// Handle validation messages
328
autorest.Message.Subscribe((_, message) => {
329
  if (message.Channel === "error" && message.Text.includes("configuration")) {
330
    console.error("Configuration validation error:", message.Text);
331
  }
332
});
333
```
334

335
### Configuration Reset
336

337
```typescript
338
// Reset all configurations
339
await autorest.ResetConfiguration();
340

341
// Add new configuration
342
autorest.AddConfiguration({
343
  "input-file": "new-swagger.json",
344
  "output-folder": "./new-generated"
345
});
346

347
// Force regeneration of configuration view
348
const freshConfig = await autorest.RegenerateView(true);
349
```
350

351
### Extension Configuration
352

353
```typescript
354
// Configure extensions
355
autorest.AddConfiguration({
356
  "use-extension": {
357
    "@microsoft.azure/autorest.typescript": "latest",
358
    "@microsoft.azure/autorest.csharp": "^3.0.0"
359
  },
360
  "require": [
361
    "@microsoft.azure/autorest.modeler"
362
  ],
363
  "try-require": [
364
    "@microsoft.azure/autorest.validator"
365
  ]
366
});
367
```