Attributes.cs 9.8 KB

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