Context Class

CheckDatabase(..)

Returns: CodeEffects.Rule.Connection.SchemaCheckResult - The version the database is at, the version this library needs, and whether that is enough.

public static SchemaCheckResult CheckDatabase(IDbProvider dbProvider)

Reads the schema version of the rule storage database and compares it with the version that this version of the Rule Repository library needs. Call it once at startup, before the repository serves anything, and act on the answer: stop, or log it and go on.

Parameters

Exceptions

Remarks

The library never calls this method by itself and keeps nothing: each call reads the database once. The update scripts come from the Code Effects portal and you run them, in order. The library never changes the schema. A database that records no schema version answers with a CurrentVersion of null, and IsCurrent is false. A database at a later version than the library needs is current.

When you do not call the method, you are told anyway, later. A statement that fails on a table or column that is not there makes the library read the version, and when the database is behind, the failure carries the control number CE19004 and the same message, in place of the error of the database.

Example

  SchemaCheckResult schema = Context.CheckDatabase(dbProvider);

  if (!schema.IsCurrent)
  	throw new InvalidOperationException(schema.Message);

GetAliasNames(..)

Returns: System.Collections.Generic.IList<System.String> - The alias of every source object stored in the repository.

public static IList<string> GetAliasNames(IDbProvider dbProvider)

Returns the alias name of every source object that is already stored in the repository. Use it to decide which of your source definitions to pass to SyncSources(..), or which source objects to pass to Reindex(..). Passing all of your sources to SyncSources(..) every time is also fine: an unchanged source is read and compared, and nothing is written.

Parameters

Exceptions

Example

  IList<string> aliases = Context.GetAliasNames(dbProvider);
  ReindexResult result = Context.Reindex(dbProvider, aliases.Where(a => a.StartsWith("MyApp.")));

GetDefaultEditorHelpXml()

Returns: System.Xml.XmlDocument - The rule editors' default English Help XML document.

public static XmlDocument GetDefaultEditorHelpXml()

Returns the default Help XML of the rule editors inside the repository: their menus, operators, clauses, flow words and Help String messages, in English. It is the same document the stand-alone Rule Editor's Control.GetDefaultHelpXml() returns. Save it, translate the text between the tags, and set the result on the EditorHelpXml or EditorHelpXmlFile property of your configuration to show the editors in that language. See Help XML and Multilingual Support.

Remarks

Every call returns a new document, so you may change it freely.

Example

  Context.GetDefaultEditorHelpXml().Save(@"C:\Translations\editor.help.xml");

  // After translating it
  var config = new Configuration
  {
  	UiXmlFile = @"C:\Translations\fr\repository.ui.xml",
  	EditorHelpXmlFile = @"C:\Translations\fr\editor.help.xml"
  };

GetDefaultUiXml()

Returns: System.Xml.XmlDocument - The default English user interface document.

public static XmlDocument GetDefaultUiXml()

Returns the default user interface XML document: every piece of static text that the repository browser client shows, in English. Save it to a file, translate the text between the tags without changing anything else, and set the result on the UiXml or UiXmlFile property of your configuration to run the repository in that language.

Remarks

Every call returns a new document, so you may change it freely. The repository checks your document against the default one when it reads it, and refuses a document that lacks a node of the default or declares a node the default does not.

Example

  XmlDocument ui = Context.GetDefaultUiXml();
  ui.Save(@"C:\Translations\repository.ui.xml");

  // After translating the file, load it and give it to the configuration of each request.
  var translated = new XmlDocument();
  translated.Load(@"C:\Translations\repository.ui.fr.xml");

  var config = new Configuration { UiXml = translated };

GetRequestToken(..)

Returns: System.String - The anti-forgery token of the current user.

public static string GetRequestToken(IRepositoryConfiguration config, IDbProvider dbProvider)

Returns an anti-forgery token for the current user, good for 24 hours. It is for a host that builds repository requests on the server instead of in the browser client of the repository: its own tools, its tests. The browser client never needs it, because it receives its token in the answer to its first request.

Parameters

Exceptions

Remarks

The token is signed with a key of the repository. The key is kept in the rule storage database and is created the first time it is needed. The token is good only for the CurrentUserId of the configuration. Never hand a token to a browser in any way other than the first answer of the repository.

Example

  string token = Context.GetRequestToken(config, dbProvider);

GetResponse(..)

Returns: System.String - The response JSON: the data that was asked for, or a warning that the user should see.

public static string GetResponse(IRepositoryConfiguration config, IDbProvider dbProvider, string requestJson)
public static Response GetResponse(IRepositoryConfiguration config, IDbProvider dbProvider, Request request)

Answers one request of the repository browser client. The first overload is the whole body of your repository endpoint: pass it the JSON that the client posted, exactly as it arrived, and return what it gives you. The second overload is for a host that has already deserialized the request into the request model of the repository. It returns the response model and throws the same exceptions. Those two models are an internal contract between the client and the repository, so use the string overload.

Parameters

Exceptions

Remarks

The method handles a request in this order: it refuses a request that is longer than the RequestLength of the limits of the configuration, reads the JSON, checks the anti-forgery token (every request except the first request of the client and its test request must carry one), checks the request against the permissions of the user before any other work, and then does the work. A request that fails on a deadlock or a dropped connection is run once more.

Warnings are answers, not failures. A record that someone else has changed, a validation that failed, and an expired page are returned in the response and are never thrown. The one refusal that is thrown is a missing permission.

A set of permissions that is not complete fails every request, the first one included, so that you see it on the first page load. Test your roles with ValidatePermissions(..).

Example

  try
  {
  	return Context.GetResponse(config, dbProvider, requestJson);
  }
  catch (RepositoryPermissionException ex)
  {
  	logger.LogWarning("Refused {Action}: {Message}", ex.Action, ex.Message);
  	return ex.ResponseJson;
  }
  catch (RepositoryException ex)
  {
  	logger.LogError(ex, "Request failed: {ControlNumber}", ex.ControlNumber);
  	return ex.ResponseJson;
  }

GetRules(..)

Returns: CodeEffects.Rule.Repository.LoadedRuleset - The ruleset of the live rules the query names.

public static LoadedRuleset GetRules(IDbProvider dbProvider, RuleQuery query)

Loads the live versions of the rules that a RuleQuery names, and the live versions of every rule that they call, in one ruleset for the Rules Engine. It is the method for an application that evaluates its rules without the Audit library. An application that has the Audit library loads its rules through AuditRecorder.GetRules(..) instead, so that its evaluations are recorded.

Parameters

Exceptions

Remarks

Only live versions are loaded: a rule version is evaluated once someone makes it live. The ruleset holds the called rules as well, so the engine finds them without a rule resolver. The method reads the database every time it is called. Keep the evaluator that you build from the ruleset for as long as the ruleset is current, and call the method again to pick up newer versions. See LoadedRuleset for how to use the result.

Example

  LoadedRuleset ruleset = Context.GetRules(dbProvider, RuleQuery.BySource("MyApp.Orders.Order"));

  var evaluator = new Evaluator<Order>(ruleset.Xml, new EvaluationParameters());

  bool approved = evaluator.Evaluate(order, ruleset.Rule("Approve large orders").Id);

Reindex(..)

Returns: CodeEffects.Rule.Repository.ReindexResult - What was done, with one entry for each source object.

public static ReindexResult Reindex(IDbProvider dbProvider, IEnumerable<string> aliases = null)

Rebuilds the member usage index of source objects that are already in the repository: the catalog of members that every version of each source object declares, and the members and reusable rules that every version of every rule bound to it uses.

Parameters

Exceptions

Remarks

SyncSources(..) and the saving of rules keep the index current as they write. This method is for what was stored before: a repository that was upgraded, rules that were migrated in from outside the repository, and a release that changes how the index is computed. You decide when to run it, and over which source objects. Nothing in the repository runs it by itself. The AliasesToReindex property of the result of SyncSources(..) lists every source object that needs it.

It can run while the repository is in use. A rule save and the reindex of its source object take the same lock first, so a save waits while its source object is reindexed, and the reindex waits while a save finishes. A source sync takes that lock later in its transaction, so a sync and a reindex of the same source object can deadlock. Both retry once. A large repository is best reindexed at a quiet time.

Each source object is reindexed in its own transaction. One that fails is rolled back and the others go on. A use that a rule version makes and that resolves to nothing is not stored and does not fail anything. It is listed in the Unresolved property of that source object's entry in the result. A source object that is reindexed successfully is recorded as current, and drops out of AliasesToReindex until a release changes how the index is computed.

Anything that writes rule versions around the repository's own saves, a migration that inserts rows directly for example, leaves their references unwritten and should be followed by a reindex of the source objects it touched.

Example

  SyncResult sync = Context.SyncSources(dbProvider, settings);

  if (sync.AliasesToReindex.Count > 0)
  	Context.Reindex(dbProvider, sync.AliasesToReindex);

SyncSources(..)

Returns: CodeEffects.Rule.Repository.SyncResult - What was done, with one entry for each source definition you passed.

public static SyncResult SyncSources(IDbProvider dbProvider, SourceSettings settings)

Checks a set of source definitions into rule storage. It stores the ones it has not seen, and creates a new version of the ones that have changed. A source definition can be a Source XML document, a .NET type, or an Adaptive Source provider.

Parameters

Exceptions

Remarks

This is a feature of its own, not a step that the rest of the repository waits on. Nothing else in the repository calls it, and the repository runs without it, but there would be no source objects to write rules against. Call it whenever it suits your application: at startup, from an administration screen, on a schedule, or from a deployment step. Call it at least once before anyone writes a rule, and after that whenever the evaluated types may have changed. It takes no configuration, because it is your own call, made on the server, with no user session behind it. To credit a person or a service with the work, set UserId on the settings.

Calling it repeatedly is safe and cheap. A definition that matches what is stored writes nothing. One that differs only in its labels updates the stored copy in place. Only a real change creates a version. What is not safe is passing several definitions of the same source object in one call: see SourceSettings.

The method keeps the member usage index of what it writes current, but it does not rebuild the index of what was stored before. That is Reindex(..), and you decide when to run it. The AliasesToReindex property of the result lists every source object that needs it. The result also lists the source objects whose embedded types have drifted from their own source objects in SourcesOutOfSync.

Example

  var settings = new SourceSettings();
  settings.SourceTypes.Add(typeof(Order));

  try
  {
  	SyncResult sync = Context.SyncSources(dbProvider, settings);
  }
  catch (RepositoryException ex)
  {
  	foreach (var source in ex.SyncResult?.Sources ?? new List<SourceResult>())
  		if (source.Outcome == SourceOutcome.Failed)
  			logger.LogError(source.Error, "{Alias} {Number} {Message}", source.AliasName, source.ControlNumber, source.Message);

  	throw;
  }

ValidatePermissions(..)

Returns: System.Collections.Generic.IList<System.String> - One English sentence for each problem, or an empty list when the set is complete.

public static IList<string> ValidatePermissions(IRepositoryConfiguration config)

Says what is wrong with the set of permissions that a configuration gives, one sentence for each problem. For the tests of your own role mappings. A set that is not complete fails every request with a RepositoryException that carries the control number CE10218, and this method reports the same problems without any request.

Parameters

Exceptions

Remarks

A set is complete when every permission that it grants has the permissions it requires granted too. DraftUpdate needs DraftView, and DraftConvert needs DraftView and either RuleCreate or RuleVersionCreate. A Configuration with AccessMode set to AllowAllExcept is always complete, because it withholds whatever depends on what it withholds. The method reads nothing from the database, and it asks CanPerform of your own implementation once for each permission.

Example

  var support = new Configuration
  {
  	AccessMode = ActionPermissionMode.AllowOnly,
  	ActionList = new HashSet<ActionPermissionType> { ActionPermissionType.DraftUpdate }
  };

  // Prints: DraftUpdate (52) requires DraftView (50).
  foreach (string problem in Context.ValidatePermissions(support))
  	Console.WriteLine(problem);