Attributes.cs 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323
  1. using System;
  2. using System.Collections.Generic;
  3. using System.IO;
  4. using System.Linq;
  5. using BepInEx.Bootstrap;
  6. using Mono.Cecil;
  7. namespace BepInEx
  8. {
  9. #region BaseUnityPlugin
  10. /// <summary>
  11. /// This attribute denotes that a class is a plugin, and specifies the required metadata.
  12. /// </summary>
  13. [AttributeUsage(AttributeTargets.Class, AllowMultiple = false)]
  14. public class BepInPlugin : Attribute
  15. {
  16. /// <summary>
  17. /// The unique identifier of the plugin. Should not change between plugin versions.
  18. /// </summary>
  19. public string GUID { get; protected set; }
  20. /// <summary>
  21. /// The user friendly name of the plugin. Is able to be changed between versions.
  22. /// </summary>
  23. public string Name { get; protected set; }
  24. /// <summary>
  25. /// The specfic version of the plugin.
  26. /// </summary>
  27. public Version Version { get; protected set; }
  28. /// <param name="GUID">The unique identifier of the plugin. Should not change between plugin versions.</param>
  29. /// <param name="Name">The user friendly name of the plugin. Is able to be changed between versions.</param>
  30. /// <param name="Version">The specfic version of the plugin.</param>
  31. public BepInPlugin(string GUID, string Name, string Version)
  32. {
  33. this.GUID = GUID;
  34. this.Name = Name;
  35. try
  36. {
  37. this.Version = new Version(Version);
  38. }
  39. catch
  40. {
  41. this.Version = null;
  42. }
  43. }
  44. internal static BepInPlugin FromCecilType(TypeDefinition td)
  45. {
  46. var attr = MetadataHelper.GetCustomAttributes<BepInPlugin>(td, false).FirstOrDefault();
  47. if (attr == null)
  48. return null;
  49. return new BepInPlugin((string)attr.ConstructorArguments[0].Value, (string)attr.ConstructorArguments[1].Value, (string)attr.ConstructorArguments[2].Value);
  50. }
  51. }
  52. /// <summary>
  53. /// This attribute specifies any dependencies that this plugin has on other plugins.
  54. /// </summary>
  55. [AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
  56. public class BepInDependency : Attribute, ICacheable
  57. {
  58. public enum DependencyFlags
  59. {
  60. /// <summary>
  61. /// The plugin has a hard dependency on the referenced plugin, and will not run without it.
  62. /// </summary>
  63. HardDependency = 1,
  64. /// <summary>
  65. /// This plugin has a soft dependency on the referenced plugin, and is able to run without it.
  66. /// </summary>
  67. SoftDependency = 2,
  68. }
  69. /// <summary>
  70. /// The GUID of the referenced plugin.
  71. /// </summary>
  72. public string DependencyGUID { get; protected set; }
  73. /// <summary>
  74. /// The flags associated with this dependency definition.
  75. /// </summary>
  76. public DependencyFlags Flags { get; protected set; }
  77. /// <summary>
  78. /// The minimum version of the referenced plugin.
  79. /// </summary>
  80. public Version MinimumVersion { get; protected set; }
  81. /// <summary>
  82. /// Marks this <see cref="BaseUnityPlugin"/> as depenant on another plugin. The other plugin will be loaded before this one.
  83. /// If the other plugin doesn't exist, what happens depends on the <see cref="Flags"/> parameter.
  84. /// </summary>
  85. /// <param name="DependencyGUID">The GUID of the referenced plugin.</param>
  86. /// <param name="Flags">The flags associated with this dependency definition.</param>
  87. public BepInDependency(string DependencyGUID, DependencyFlags Flags = DependencyFlags.HardDependency)
  88. {
  89. this.DependencyGUID = DependencyGUID;
  90. this.Flags = Flags;
  91. MinimumVersion = new Version();
  92. }
  93. /// <summary>
  94. /// Marks this <see cref="BaseUnityPlugin"/> as depenant on another plugin. The other plugin will be loaded before this one.
  95. /// If the other plugin doesn't exist or is of a version below <see cref="MinimumDependencyVersion"/>, this plugin will not load and an error will be logged instead.
  96. /// </summary>
  97. /// <param name="DependencyGUID">The GUID of the referenced plugin.</param>
  98. /// <param name="MinimumDependencyVersion">The minimum version of the referenced plugin.</param>
  99. /// <remarks>When version is supplied the dependency is always treated as HardDependency</remarks>
  100. public BepInDependency(string DependencyGUID, string MinimumDependencyVersion) : this(DependencyGUID)
  101. {
  102. MinimumVersion = new Version(MinimumDependencyVersion);
  103. }
  104. internal static IEnumerable<BepInDependency> FromCecilType(TypeDefinition td)
  105. {
  106. var attrs = MetadataHelper.GetCustomAttributes<BepInDependency>(td, true);
  107. return attrs.Select(customAttribute =>
  108. {
  109. var dependencyGuid = (string)customAttribute.ConstructorArguments[0].Value;
  110. var secondArg = customAttribute.ConstructorArguments[1].Value;
  111. if (secondArg is string minVersion) return new BepInDependency(dependencyGuid, minVersion);
  112. return new BepInDependency(dependencyGuid, (DependencyFlags)secondArg);
  113. }).ToList();
  114. }
  115. void ICacheable.Save(BinaryWriter bw)
  116. {
  117. bw.Write(DependencyGUID);
  118. bw.Write((int)Flags);
  119. bw.Write(MinimumVersion.ToString());
  120. }
  121. void ICacheable.Load(BinaryReader br)
  122. {
  123. DependencyGUID = br.ReadString();
  124. Flags = (DependencyFlags)br.ReadInt32();
  125. MinimumVersion = new Version(br.ReadString());
  126. }
  127. }
  128. /// <summary>
  129. /// This attribute specifies other plugins that are incompatible with this plugin.
  130. /// </summary>
  131. [AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
  132. public class BepInIncompatibility : Attribute, ICacheable
  133. {
  134. /// <summary>
  135. /// The GUID of the referenced plugin.
  136. /// </summary>
  137. public string IncompatibilityGUID { get; protected set; }
  138. /// <summary>
  139. /// Marks this <see cref="BaseUnityPlugin"/> as incompatible with another plugin.
  140. /// If the other plugin exists, this plugin will not be loaded and a warning will be shown.
  141. /// </summary>
  142. /// <param name="IncompatibilityGUID">The GUID of the referenced plugin.</param>
  143. public BepInIncompatibility(string IncompatibilityGUID)
  144. {
  145. this.IncompatibilityGUID = IncompatibilityGUID;
  146. }
  147. internal static IEnumerable<BepInIncompatibility> FromCecilType(TypeDefinition td)
  148. {
  149. var attrs = MetadataHelper.GetCustomAttributes<BepInIncompatibility>(td, true);
  150. return attrs.Select(customAttribute =>
  151. {
  152. var dependencyGuid = (string)customAttribute.ConstructorArguments[0].Value;
  153. return new BepInIncompatibility(dependencyGuid);
  154. }).ToList();
  155. }
  156. void ICacheable.Save(BinaryWriter bw)
  157. {
  158. bw.Write(IncompatibilityGUID);
  159. }
  160. void ICacheable.Load(BinaryReader br)
  161. {
  162. IncompatibilityGUID = br.ReadString();
  163. }
  164. }
  165. /// <summary>
  166. /// This attribute specifies which processes this plugin should be run for. Not specifying this attribute will load the plugin under every process.
  167. /// </summary>
  168. [AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
  169. public class BepInProcess : Attribute
  170. {
  171. /// <summary>
  172. /// The name of the process that this plugin will run under.
  173. /// </summary>
  174. public string ProcessName { get; protected set; }
  175. /// <param name="ProcessName">The name of the process that this plugin will run under.</param>
  176. public BepInProcess(string ProcessName)
  177. {
  178. this.ProcessName = ProcessName;
  179. }
  180. internal static List<BepInProcess> FromCecilType(TypeDefinition td)
  181. {
  182. var attrs = MetadataHelper.GetCustomAttributes<BepInProcess>(td, true);
  183. return attrs.Select(customAttribute => new BepInProcess((string)customAttribute.ConstructorArguments[0].Value)).ToList();
  184. }
  185. }
  186. #endregion
  187. #region MetadataHelper
  188. /// <summary>
  189. /// Helper class to use for retrieving metadata about a plugin, defined as attributes.
  190. /// </summary>
  191. public static class MetadataHelper
  192. {
  193. internal static IEnumerable<CustomAttribute> GetCustomAttributes<T>(TypeDefinition td, bool inherit) where T : Attribute
  194. {
  195. var result = new List<CustomAttribute>();
  196. var type = typeof(T);
  197. var currentType = td;
  198. do
  199. {
  200. result.AddRange(currentType.CustomAttributes.Where(ca => ca.AttributeType.FullName == type.FullName));
  201. currentType = currentType.BaseType?.Resolve();
  202. } while (inherit && currentType?.FullName != "System.Object");
  203. return result;
  204. }
  205. /// <summary>
  206. /// Retrieves the BepInPlugin metadata from a plugin type.
  207. /// </summary>
  208. /// <param name="pluginType">The plugin type.</param>
  209. /// <returns>The BepInPlugin metadata of the plugin type.</returns>
  210. public static BepInPlugin GetMetadata(Type pluginType)
  211. {
  212. object[] attributes = pluginType.GetCustomAttributes(typeof(BepInPlugin), false);
  213. if (attributes.Length == 0)
  214. return null;
  215. return (BepInPlugin)attributes[0];
  216. }
  217. /// <summary>
  218. /// Retrieves the BepInPlugin metadata from a plugin instance.
  219. /// </summary>
  220. /// <param name="plugin">The plugin instance.</param>
  221. /// <returns>The BepInPlugin metadata of the plugin instance.</returns>
  222. public static BepInPlugin GetMetadata(object plugin)
  223. => GetMetadata(plugin.GetType());
  224. /// <summary>
  225. /// Gets the specified attributes of a type, if they exist.
  226. /// </summary>
  227. /// <typeparam name="T">The attribute type to retrieve.</typeparam>
  228. /// <param name="pluginType">The plugin type.</param>
  229. /// <returns>The attributes of the type, if existing.</returns>
  230. public static T[] GetAttributes<T>(Type pluginType) where T : Attribute
  231. {
  232. return (T[])pluginType.GetCustomAttributes(typeof(T), true);
  233. }
  234. /// <summary>
  235. /// Gets the specified attributes of an instance, if they exist.
  236. /// </summary>
  237. /// <typeparam name="T">The attribute type to retrieve.</typeparam>
  238. /// <param name="plugin">The plugin instance.</param>
  239. /// <returns>The attributes of the instance, if existing.</returns>
  240. public static IEnumerable<T> GetAttributes<T>(object plugin) where T : Attribute
  241. => GetAttributes<T>(plugin.GetType());
  242. /// <summary>
  243. /// Retrieves the dependencies of the specified plugin type.
  244. /// </summary>
  245. /// <param name="Plugin">The plugin type.</param>
  246. /// <returns>A list of all plugin types that the specified plugin type depends upon.</returns>
  247. public static IEnumerable<BepInDependency> GetDependencies(Type plugin)
  248. {
  249. return plugin.GetCustomAttributes(typeof(BepInDependency), true).Cast<BepInDependency>();
  250. }
  251. }
  252. /// <summary>
  253. /// An exception which is thrown when a plugin's dependencies cannot be found.
  254. /// </summary>
  255. [Obsolete]
  256. public class MissingDependencyException : Exception
  257. {
  258. public MissingDependencyException(string message) : base(message) { }
  259. }
  260. #endregion
  261. #region Build configuration
  262. /// <summary>
  263. /// This class is appended to AssemblyInfo.cs when BepInEx is built via a CI pipeline.
  264. /// It is mainly intended to signify that the current build is not a release build and is special, like for instance a bleeding edge build.
  265. /// </summary>
  266. internal class BuildInfoAttribute : Attribute
  267. {
  268. public string Info { get; }
  269. public BuildInfoAttribute(string info)
  270. {
  271. Info = info;
  272. }
  273. }
  274. #endregion
  275. }