MegaBites-AI/Windows-powershell
0372
1// Copyright (c) Microsoft Corporation.2// Licensed under the MIT License.3 4using System.Collections.ObjectModel;5 6using Dbg = System.Management.Automation.Diagnostics;7 8//using System.Runtime.Serialization;9//using System.ComponentModel;10//using System.Runtime.InteropServices;11//using System.Globalization;12//using System.Management.Automation;13//using System.Reflection;14 15namespace System.Management.Automation.Host16{17 /// <summary>18 /// Provides a description of a field for use by <see cref="System.Management.Automation.Host.PSHostUserInterface.Prompt"/>.19 /// <!--Used by the engine to describe cmdlet parameters.-->20 /// </summary>21 /// <remarks>22 /// It is permitted to subclass <see cref="System.Management.Automation.Host.FieldDescription"/>23 /// but there is no established scenario for doing this, nor has it been tested.24 /// </remarks>25 public class26 FieldDescription27 {28 /// <summary>29 /// Initializes a new instance of FieldDescription and defines the Name value.30 /// </summary>31 /// <param name="name">32 /// The name to identify this field description33 /// </param>34 /// <exception cref="System.Management.Automation.PSArgumentException">35 /// <paramref name="name"/> is null or empty.36 /// </exception>37 public38 FieldDescription(string name)39 {40 // the only required parameter is the name.41 42 if (string.IsNullOrEmpty(name))43 {44 throw PSTraceSource.NewArgumentException(nameof(name), DescriptionsStrings.NullOrEmptyErrorTemplate, "name");45 }46 47 this.name = name;48 }49 50 /// <summary>51 /// Gets the name of the field.52 /// </summary>53 public string Name54 {55 get56 {57 return name;58 }59 }60 61 /// <summary>62 /// Sets the ParameterTypeName, ParameterTypeFullName, and ParameterAssemblyFullName as a single operation.63 /// </summary>64 /// <param name="parameterType">65 /// The Type that sets the properties.66 /// </param>67 /// <exception cref="System.Management.Automation.PSArgumentNullException">68 /// If <paramref name="parameterType"/> is null.69 /// </exception>70 public71 void72 SetParameterType(System.Type parameterType)73 {74 if (parameterType == null)75 {76 throw PSTraceSource.NewArgumentNullException(nameof(parameterType));77 }78 79 SetParameterTypeName(parameterType.Name);80 SetParameterTypeFullName(parameterType.FullName);81 SetParameterAssemblyFullName(parameterType.AssemblyQualifiedName);82 }83 84 /// <summary>85 /// Gets the short name of the parameter's type.86 /// </summary>87 /// <value>88 /// The type name of the parameter89 /// </value>90 /// <remarks>91 /// If not already set by a call to <see cref="System.Management.Automation.Host.FieldDescription.SetParameterType"/>,92 /// <see cref="string"/> will be used as the type.93 /// <!--The value of ParameterTypeName is the string value returned.94 /// by System.Type.Name.-->95 /// </remarks>96 public97 string98 ParameterTypeName99 {100 get101 {102 if (string.IsNullOrEmpty(parameterTypeName))103 {104 // the default if the type name is not specified is 'string'105 106 SetParameterType(typeof(string));107 }108 109 return parameterTypeName;110 }111 }112 113 /// <summary>114 /// Gets the full string name of the parameter's type.115 /// </summary>116 /// <remarks>117 /// If not already set by a call to <see cref="System.Management.Automation.Host.FieldDescription.SetParameterType"/>,118 /// <see cref="string"/> will be used as the type.119 /// <!--The value of ParameterTypeName is the string value returned.120 /// by System.Type.Name.-->121 /// </remarks>122 public123 string124 ParameterTypeFullName125 {126 get127 {128 if (string.IsNullOrEmpty(parameterTypeFullName))129 {130 // the default if the type name is not specified is 'string'131 132 SetParameterType(typeof(string));133 }134 135 return parameterTypeFullName;136 }137 }138 139 /// <summary>140 /// Gets the full name of the assembly containing the type identified by ParameterTypeFullName or ParameterTypeName.141 /// </summary>142 /// <remarks>143 /// If the assembly is not currently loaded in the hosting application's AppDomain, the hosting application needs144 /// to load the containing assembly to access the type information. AssemblyName is used for this purpose.145 ///146 /// If not already set by a call to <see cref="System.Management.Automation.Host.FieldDescription.SetParameterType"/>,147 /// <see cref="string"/> will be used as the type.148 /// </remarks>149 public150 string151 ParameterAssemblyFullName152 {153 get154 {155 if (string.IsNullOrEmpty(parameterAssemblyFullName))156 {157 // the default if the type name is not specified is 'string'158 159 SetParameterType(typeof(string));160 }161 162 return parameterAssemblyFullName;163 }164 }165 166 /// <summary>167 /// A short, human-presentable message to describe and identify the field. If supplied, a typical implementation of168 /// <see cref="System.Management.Automation.Host.PSHostUserInterface.Prompt"/> will use this value instead of169 /// the field name to identify the field to the user.170 /// </summary>171 /// <exception cref="System.Management.Automation.PSArgumentNullException">172 /// set to null.173 /// </exception>174 /// <remarks>175 /// Note that the special character & (ampersand) may be embedded in the label string to identify the next176 /// character in the label as a "hot key" (aka "keyboard accelerator") that the177 /// <see cref="System.Management.Automation.Host.PSHostUserInterface.Prompt"/> implementation may use178 /// to allow the user to quickly set input focus to this field. The implementation of179 /// <see cref="System.Management.Automation.Host.PSHostUserInterface.Prompt"/> is responsible for parsing180 /// the label string for this special character and rendering it accordingly.181 ///182 /// For example, a field named "SSN" might have "&Social Security Number" as it's label.183 ///184 /// If no label is set, then the empty string is returned.185 /// </remarks>186 public187 string188 Label189 {190 get191 {192 Dbg.Assert(label != null, "label should not be null");193 194 return label;195 }196 197 set198 {199 if (value == null)200 {201 throw PSTraceSource.NewArgumentNullException("value");202 }203 204 label = value;205 }206 }207 208 /// <summary>209 /// Gets and sets the help message for this field.210 /// </summary>211 /// <exception cref="System.Management.Automation.PSArgumentNullException">212 /// Set to null.213 /// </exception>214 /// <remarks>215 /// This should be a few sentences to describe the field, suitable for presentation as a tool tip.216 /// Avoid placing including formatting characters such as newline and tab.217 /// </remarks>218 public219 string220 HelpMessage221 {222 get223 {224 Dbg.Assert(helpMessage != null, "helpMessage should not be null");225 226 return helpMessage;227 }228 229 set230 {231 if (value == null)232 {233 throw PSTraceSource.NewArgumentNullException("value");234 }235 236 helpMessage = value;237 }238 }239 240 /// <summary>241 /// Gets and sets whether a value must be supplied for this field.242 /// </summary>243 public244 bool245 IsMandatory246 {247 get248 {249 return isMandatory;250 }251 252 set253 {254 isMandatory = value;255 }256 }257 258 /// <summary>259 /// Gets and sets the default value, if any, for the implementation of <see cref="System.Management.Automation.Host.PSHostUserInterface.Prompt"/>260 /// to pre-populate its UI with. This is a PSObject instance so that the value can be serialized, converted,261 /// manipulated like any pipeline object.262 /// </summary>263 /// <remarks>264 /// It is up to the implementer of <see cref="System.Management.Automation.Host.PSHostUserInterface.Prompt"/> to decide if it265 /// can make use of the object in its presentation of the fields prompt.266 ///267 /// </remarks>268 public269 PSObject270 DefaultValue271 {272 get273 {274 return defaultValue;275 }276 277 set278 {279 // null is allowed.280 281 defaultValue = value;282 }283 }284 285 /// <summary>286 /// Gets the Attribute classes that apply to the field. In the case that <see cref="System.Management.Automation.Host.PSHostUserInterface.Prompt"/>287 /// is being called from the engine, this will contain the set of prompting attributes that are attached to a288 /// cmdlet parameter declaration.289 /// </summary>290 public291 Collection<Attribute>292 Attributes293 {294 get { return metadata ??= new Collection<Attribute>(); }295 }296 297 /// <summary>298 /// For use by remoting serialization.299 /// </summary>300 /// <param name="nameOfType"></param>301 /// <exception cref="System.Management.Automation.PSArgumentException">302 /// If <paramref name="nameOfType"/> is null.303 /// </exception>304 internal305 void306 SetParameterTypeName(string nameOfType)307 {308 if (string.IsNullOrEmpty(nameOfType))309 {310 throw PSTraceSource.NewArgumentException(nameof(nameOfType), DescriptionsStrings.NullOrEmptyErrorTemplate, "nameOfType");311 }312 313 parameterTypeName = nameOfType;314 }315 316 /// <summary>317 /// For use by remoting serialization.318 /// </summary>319 /// <param name="fullNameOfType"></param>320 /// <exception cref="System.Management.Automation.PSArgumentException">321 /// If <paramref name="fullNameOfType"/> is null.322 /// </exception>323 internal324 void325 SetParameterTypeFullName(string fullNameOfType)326 {327 if (string.IsNullOrEmpty(fullNameOfType))328 {329 throw PSTraceSource.NewArgumentException(nameof(fullNameOfType), DescriptionsStrings.NullOrEmptyErrorTemplate, "fullNameOfType");330 }331 332 parameterTypeFullName = fullNameOfType;333 }334 335 /// <summary>336 /// For use by remoting serialization.337 /// </summary>338 /// <param name="fullNameOfAssembly"></param>339 /// <exception cref="System.Management.Automation.PSArgumentException">340 /// If <paramref name="fullNameOfAssembly"/> is null.341 /// </exception>342 internal343 void344 SetParameterAssemblyFullName(string fullNameOfAssembly)345 {346 if (string.IsNullOrEmpty(fullNameOfAssembly))347 {348 throw PSTraceSource.NewArgumentException(nameof(fullNameOfAssembly), DescriptionsStrings.NullOrEmptyErrorTemplate, "fullNameOfAssembly");349 }350 351 parameterAssemblyFullName = fullNameOfAssembly;352 }353 354 /// <summary>355 /// Indicates if this field description was356 /// modified by the remoting protocol layer.357 /// </summary>358 /// <remarks>Used by the console host to359 /// determine if this field description was360 /// modified by the remoting protocol layer361 /// and take appropriate actions</remarks>362 internal bool ModifiedByRemotingProtocol363 {364 get365 {366 return modifiedByRemotingProtocol;367 }368 369 set370 {371 modifiedByRemotingProtocol = value;372 }373 }374 375 /// <summary>376 /// Indicates if this field description377 /// is coming from a remote host.378 /// </summary>379 /// <remarks>Used by the console host to380 /// not cast strings to an arbitrary type,381 /// but let the server-side do the type conversion382 /// </remarks>383 internal bool IsFromRemoteHost384 {385 get386 {387 return isFromRemoteHost;388 }389 390 set391 {392 isFromRemoteHost = value;393 }394 }395 396 #region Helper397 #endregion Helper398 399 #region DO NOT REMOVE OR RENAME THESE FIELDS - it will break remoting compatibility with Windows PowerShell400 401 private readonly string name = null;402 private string label = string.Empty;403 private string parameterTypeName = null;404 private string parameterTypeFullName = null;405 private string parameterAssemblyFullName = null;406 private string helpMessage = string.Empty;407 private bool isMandatory = true;408 409 private PSObject defaultValue = null;410 private Collection<Attribute> metadata = new Collection<Attribute>();411 private bool modifiedByRemotingProtocol = false;412 private bool isFromRemoteHost = false;413 414 #endregion415 }416}417