Create new sharing reason from APEX

Question

Is there a way to create a new sharing reason via APEX? Or this is only possible via the Metadata api?

Sharing reasons documentation

And if not -- is it possible to specify the 'Reason' when creating a new manual share via an sObject__share insert?? Even if that rule doesn't explicitly exist in the org?

Update

We have discovered that we can package sharing rules and successfully install into a Group Test Org without an issue, so it's possible we can package our sharing rule and not touch it unless sharing is available and turned on! We'll see.

Answer 1

Sharing Reason/RowCause can only be created from the UI or through Metadata API.

It's not really a picklist on the sObject__share record, it's more like an enumerated value(enum), so you can't plug in a new value on the fly. Here is a typical construction of a Share record (if the sObject is really called "sObject". Your object is probably called something more descriptive.).

sObject__Share sh = new sObject__Share(
    ParentId = [objectId],
    UserOrGroupId = [userId],
    AccessLevel = 'Edit',
    RowCause = Schema.sObject__Share.RowCause.Custom_Sharing_Reason__c);

If the enum value has not already been created, it can't be specified as the value for the field. However, you can create a Share record with RowCause = Schema.sObject__Share.RowCause.Manual or with no RowCause, which will just default to Manual.