Frame is a JSON-based, highly configurable CORS manager for Asp.Net Web API

Installing Frame

Frame is available as a nuget package - Frame.CORS. It supports .NET Framework 4.5 and above (till 4.6.2 as of this writing). You can download the latest version from here - https://www.nuget.org/packages/Frame.Cors/ or search "Frame.CORS" from within Nuget Package Manager.

Using Frame

After the installation is finished, you will find a new file created in App_Data folder of your application - frm-cors-config.json. This is a CORS configuration file, and has a JSON array structure like this -

[{
   "controllers": "*",
   "allow-origin": "*",
   "allow-methods": "GET,POST",
   "allow-headers": "*",
   "allow-credentials": false,
   "max-age": 0,
   "expose-headers": "*"
},{
   "controllers": "home",
   "allow-origin": "*",
   "allow-methods": "*",
   "allow-headers": "*",
   "allow-credentials": false,
   "max-age": 0,
   "expose-headers": "*"
}]

Note: If this file is not created due to permission issues or similar, please create it manually and insert the above JSON or download the attached file in the repo and keep it in App_Data folder.

Consider each JSON element in the array as a set of CORS config for controllers mentioned in the "controllers" key of the same element. This and other key-value pairs are explained below -

controllers: (string) Specify controller names (without Controller suffix, like product) or * for all controllers. All the below described fields will apply to this set of controllers
allow-origin: (string) Specify a single origin domain (including scheme, host and port, if applicable, like http://example.com) or * for all origins
allow-methods: (string) Specify access methods allowed in the request
allow-headers: (string) Specify access headers allowed in the request
allow-credentials: (boolean) Specify if credentials are allowed in the request
max-age: (long) Specify max-age in seconds that the response can be cached for by the user agent
expose-headers: (string) Specify which headers are to be exposed to the client in the response

If let's say, there are three controllers (ctrl1, ctrl2, ctrl3) with ctrl1 and ctrl2 having same CORS set, the JSON would look like (example values) -

[{
   "controllers": "*",
   "allow-origin": "*",
   "allow-methods": "GET,POST",
   "allow-headers": "*",
   "allow-credentials": false,
   "max-age": 0,
   "expose-headers": "*"
},{
   "controllers": "ctrl1,ctrl2",
   "allow-origin": "http://example.com",
   "allow-methods": "GET,POST,PUT,DELETE",
   "allow-headers": "Authorization,Content-Type",
   "allow-credentials": true,
   "max-age": 300,
   "expose-headers": "*"
},{
   "controllers": "ctrl3",
   "allow-origin": "http://example.com",
   "allow-methods": "GET,POST",
   "allow-headers": "Cache-Control,Content-Type"
}]

After the configuration is final, you simply need to import Frame.CORS namespace reference in App_Start/WebApiConfig.cs file and register Frame with this piece of code -

config.RegisterFrame([bool runLocalOnly]);

The runLocalOnly flag is optional (default = false). Set it to true only if the API is idle and is being currently used for testing purposes.

Important Points

There are a few important points to note with respect to using the library -

a) As shown in the file above, you can specify a default set of headers for all controllers using "*" as value and then override them by adding another JSON object for a particular controller. Here, the entire new set overrides the default set. and not individual fields. So, if a field like "expose-headers" is to be removed from response, then delete it from the controller's set.
b) You can omit the default set completely and go on to set individual JSON config for all or a subset of controllers.
c) Multiple controllers can be grouped together in a comma-seperated manner and that set will be applicable to all of them.
d) Duplicate controller sets are not allowed. This means that there cannot be two JSON elements having controllers field with same controller name in them. The library will throw a runtime error in such a scenario.
e) The library allows you to test the CORS functionality locally with the use of a flag (described below). When this is the case, CORS can be assumed to be turned off to the outer world and no cross origin requests are allowed to the server.

Note: Please make sure that the config file name and path are not modified after installation.