This is an automated email from the ASF dual-hosted git repository.
dmagda pushed a commit to branch IGNITE-7595
in repository https://gitbox.apache.org/repos/asf/ignite.git
The following commit(s) were added to refs/heads/IGNITE-7595 by this push:
new ba6fbe2 ported .NET-specific documentation pages - configuration,
deployment and standalone nodes.
ba6fbe2 is described below
commit ba6fbe25e1825e2a34f70e8f5f56826157d7cde6
Author: Denis Magda <dma...@gridgain.com>
AuthorDate: Mon Sep 28 16:26:01 2020 -0700
ported .NET-specific documentation pages - configuration, deployment and
standalone nodes.
---
docs/_data/toc.yaml | 28 ++++
docs/_docs/net-specific/configuration-options.adoc | 176 +++++++++++++++++++++
docs/_docs/net-specific/deployment-options.adoc | 138 ++++++++++++++++
docs/_docs/net-specific/standalone-nodes.adoc | 116 ++++++++++++++
4 files changed, 458 insertions(+)
diff --git a/docs/_data/toc.yaml b/docs/_data/toc.yaml
index 2616397..8db5154 100644
--- a/docs/_data/toc.yaml
+++ b/docs/_data/toc.yaml
@@ -421,6 +421,34 @@
url: extensions-and-integrations/streaming/zeromq-streamer
- title: Twitter Streamer
url: extensions-and-integrations/streaming/twitter-streamer
+- title: C# and .NET Specific
+ items:
+ - title: Configuration Options
+ url: net-specific/configuration-options
+ - title: Deployment Options
+ url: net-specific/deployment-options
+ - title: Standalone Nodes
+ url: net-specific/standalone-nodes
+ - title: Logging
+ url: net-specific/logging
+ - title: LINQ
+ url: net-specific/linq
+ - title: Java Services Execution
+ url: net-specific/java-services-execution
+ - title: Plugins
+ url: net-specific/plugins
+ - title: Serialization
+ url: net-specific/serialization
+ - title: Cross-Platform Support
+ url: net-specific/cross-platform-support
+ - title: Platform Interoperability
+ url: net-specific/platform-interoperability
+ - title: Remote Assembly Loading
+ url: net-specific/remote-assembly-loading
+ - title: Troubleshooting
+ url: net-specific/troubleshooting
+ - title: Integrations
+ url: net-specific/integrations
- title: Plugins
url: plugins
- title: SQL Reference
diff --git a/docs/_docs/net-specific/configuration-options.adoc
b/docs/_docs/net-specific/configuration-options.adoc
new file mode 100644
index 0000000..518c83e
--- /dev/null
+++ b/docs/_docs/net-specific/configuration-options.adoc
@@ -0,0 +1,176 @@
+= Ignite.NET Configuration Options
+
+== Overview
+
+Ignite.NET nodes can be configured in a variety of ways and then started via
configuration-specific `Ignition.Start*` methods.
+
+== Configure Programmatically in C#
+
+Use the `Ignition.Start(IgniteConfiguration)` method to configure an
Ignite.NET node from your C# application.
+
+[tabs]
+--
+tab:Sample C# Configuration[]
+[source,csharp]
+----
+Ignition.Start(new IgniteConfiguration
+{
+ DiscoverySpi = new TcpDiscoverySpi
+ {
+ IpFinder = new TcpDiscoveryStaticIpFinder
+ {
+ Endpoints = new[] {"127.0.0.1:47500..47509"}
+ },
+ SocketTimeout = TimeSpan.FromSeconds(0.3)
+ },
+ IncludedEventTypes = EventType.CacheAll,
+ JvmOptions = new[] { "-Xms1024m", "-Xmx1024m" }
+});
+----
+--
+
+== Configure With Application or Web Config Files
+
+`Ignition.StartFromApplicationConfiguration` methods read configuration from
`Apache.Ignite.Core.IgniteConfigurationSection`
+of the app.config or web.config files.
+
+The `IgniteConfigurationSection.xsd` schema file can be found next to
Apache.Ignite.Core.dll in the binary distribution,
+and in `Apache.Ignite.Schema` NuGet package. Include it in your project with
`None` build action to enable IntelliSense
+in Visual Studio while editing `IgniteConfigurationSection` in the config
files.
+
+[tabs]
+--
+tab:Configure in app.config[]
+[source,xml]
+----
+<configuration>
+ <configSections>
+ <section name="igniteConfiguration"
type="Apache.Ignite.Core.IgniteConfigurationSection, Apache.Ignite.Core" />
+ </configSections>
+
+ <runtime>
+ <gcServer enabled="true"/>
+ </runtime>
+
+ <igniteConfiguration
xmlns="http://ignite.apache.org/schema/dotnet/IgniteConfigurationSection";
gridName="myGrid1">
+ <discoverySpi type="TcpDiscoverySpi">
+ <ipFinder type="TcpDiscoveryStaticIpFinder">
+ <endpoints>
+ <string>127.0.0.1:47500..47509</string>
+ </endpoints>
+ </ipFinder>
+ </discoverySpi>
+
+ <cacheConfiguration>
+ <cacheConfiguration cacheMode='Replicated' readThrough='true'
writeThrough='true' />
+ <cacheConfiguration name='secondCache' />
+ </cacheConfiguration>
+
+ <includedEventTypes>
+ <int>42</int>
+ <int>TaskFailed</int>
+ <int>JobFinished</int>
+ </includedEventTypes>
+
+ <userAttributes>
+ <pair key='myNode' value='true' />
+ </userAttributes>
+
+ <JvmOptions>
+ <string>-Xms1024m</string>
+ <string>-Xmx1024m</string>
+ </JvmOptions>
+ </igniteConfiguration>
+</configuration>
+----
+tab:Use in C#[]
+[source,csharp]
+----
+var ignite = Ignition.StartFromApplicationConfiguration("igniteConfiguration");
+----
+--
+
+[NOTE]
+====
+[discrete]
+To add the `IgniteConfigurationSection.xsd` schema file to a Visual Studio
project go to `Projects` menu and click on
+`Add Existing Item...` menu item. After that locate
`IgniteConfigurationSection.xsd` inside of the Apache Ignite distribution
+and pick it up. Alternatively, install NuGet package: `Install-Package
Apache.Ignite.Schema`. This will add an xsd file to
+the project automatically. To improve editing, make sure that `Statement
Completion` options are enabled in
+`Tools - Options - Text Editor - XML`.
+====
+
+=== Ignite Configuration Section Syntax
+
+The configuration section maps directly to `IgniteConfiguration` class:
+
+* Simple properties (strings, primitives, enums) map to XML attributes
(attribute name = camelCased C# property name).
+* Complex properties map to nested XML elements (element name = camelCased C#
property name).
+* When a complex property is an interface or abstract class, `type` attribute
is used to specify the type, using *assembly-qualified name*. For built-in
types (like TcpDiscoverySpi in the code sample above) assembly name and
namespace can be omitted.
+* When in doubt, consult the schema in `IgniteConfigurationSection.xsd`.
+
+== Configure With Spring XML
+
+Spring XML enables the native java-based Ignite configuration method. A Spring
config file can be provided via
+the `Ignition.Start(string)` method or the
`IgniteConfiguration.SpringConfigUrl` property. This configuration method
+is useful when some Java property is not natively supported by Ignite.NET.
+
+When the `IgniteConfiguration.SpringConfigUrl` property is used, the Spring
config is loaded first, and other
+`IgniteConfiguration` properties are applied on top of it.
+
+[tabs]
+--
+tab:Configure With Spring XML[]
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+
+<beans xmlns="http://www.springframework.org/schema/beans";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xmlns:util="http://www.springframework.org/schema/util";
+ xsi:schemaLocation="http://www.springframework.org/schema/beans
+
http://www.springframework.org/schema/beans/spring-beans.xsd
+ http://www.springframework.org/schema/util
+
http://www.springframework.org/schema/util/spring-util.xsd";>
+ <bean id="grid.cfg"
class="org.apache.ignite.configuration.IgniteConfiguration">
+ <property name="localHost" value="127.0.0.1"/>
+ <property name="gridName" value="grid1"/>
+ <property name="userAttributes">
+ <map>
+ <entry key="my_attr" value="value1"/>
+ </map>
+ </property>
+
+ <property name="cacheConfiguration">
+ <list>
+ <bean
class="org.apache.ignite.configuration.CacheConfiguration">
+ <property name="name" value="cache1"/>
+ <property name="startSize" value="10"/>
+ </bean>
+ </list>
+ </property>
+
+ <property name="discoverySpi">
+ <bean class="org.apache.ignite.spi.discovery.tcp.TcpDiscoverySpi">
+ <property name="ipFinder">
+ <bean
class="org.apache.ignite.spi.discovery.tcp.ipfinder.vm.TcpDiscoveryVmIpFinder">
+ <property name="addresses">
+ <list>
+ <value>127.0.0.1:47500..47509</value>
+ </list>
+ </property>
+ </bean>
+ </property>
+ <property name="socketTimeout" value="300" />
+ </bean>
+ </property>
+ </bean>
+</beans>
+----
+tab:Use in C#[]
+[source,csharp]
+----
+var ignite = Ignition.Start("spring-config.xml");
+----
+--
+
diff --git a/docs/_docs/net-specific/deployment-options.adoc
b/docs/_docs/net-specific/deployment-options.adoc
new file mode 100644
index 0000000..05813e7
--- /dev/null
+++ b/docs/_docs/net-specific/deployment-options.adoc
@@ -0,0 +1,138 @@
+= Application Deployment Options
+
+== Overview
+
+Apache Ignite.NET consists of .NET assemblies and Java jar files. The .NET
assemblies are referenced by your project and
+are copied to an output folder during the build automatically. The JAR files
should be copied manually.
+Ignite.NET discovers them via the `IgniteHome` or `JvmClasspath` settings.
+
+This page introduces several most-commonly used deployment options of
Ignite.NET nodes.
+
+== Full Binary Package Deployment
+
+* Copy the https://ignite.apache.org[whole Ignite distribution package,
window=_blank] along with your application
+* Set the `IGNITE_HOME` environment variable or
`IgniteConfiguration.IgniteHome` setting to point to that folder
+
+== NuGet Deployment
+
+The post-build event is updated automatically during the Ignite.NET NuGet
package installation to copy jar files to
+`Libs` folder in the output directory (see link:quick-start/dotnet[Getting
Started]).
+Make sure to include that `Libs` folder when distributing your binaries.
+
+Make sure `IGNITE_HOME` is not set globally. Normally you don't need to set
`IGNITE_HOME` with NuGet, except for
+ASP.NET deployments (see below).
+
+[tabs]
+--
+tab:Post-Build Event[]
+[source,shell]
+----
+if not exist "$(TargetDir)Libs" md "$(TargetDir)Libs"
+xcopy /s /y "$(SolutionDir)packages\Apache.Ignite.1.6.0\Libs\*.*"
"$(TargetDir)Libs"
+----
+--
+
+== Custom Deployment
+
+The JAR files are located in the `libs` folder of the binary distribution and
NuGet package.
+The minimum set of jars for Ignite.NET is:
+
+* `ignite-core-{VER}.jar`
+* `cache-api-1.0.0.jar`
+* `ignite-indexing` folder (if SQL queries are used)
+* `ignite-spring` folder (if a Spring XML configuration is used)
+
+=== Deploying JARs to a default location:
+
+* Copy the JAR files to the `Libs` folder next to Apache.Ignite.Core.dll
+* Do not set the `IgniteConfiguration.JvmClasspath`,
`IgniteConfiguration.IgniteHome` properties and `IGNITE_HOME` environment
variable
+
+=== Deploying jar files to an arbitrary location:
+
+* Copy the JAR files somewhere
+* Set the `IgniteConfiguration.JvmClasspath` property to a semicolon-separated
string of paths for each jar file
+* Do not set the `IGNITE_HOME` environment variable and
`IgniteConfiguration.IgniteHome` property
+
+[tabs]
+--
+tab:IgniteConfiguration.JvmClasspath Example[]
+[source,shell]
+----
+c:\ignite-jars\ignite-core-1.5.0.final.jar;c:\ignite-jars\cache-api-1.0.0.jar
+----
+--
+
+== ASP.NET Deployment
+
+`JvmClasspath` or `IgniteHome` have to be explicitly set when using Ignite in
a web environment (IIS and IIS Express),
+because DDL files are copied to temporary folders, and Ignite can not locate
JAR files automatically.
+
+You can set `IgniteHome` like this in ASP.NET environment:
+
+[tabs]
+--
+tab:C#[]
+[source,csharp]
+----
+Ignition.Start(new IgniteConfiguration
+{
+ IgniteHome = HttpContext.Current.Server.MapPath(@"~\bin\")
+});
+----
+--
+
+Alternatively, `IGNITE_HOME` can be set globally. Add this line at the top of
the `Application_Start` method in `Global.asax.cs`:
+
+[tabs]
+--
+tab:C#[]
+[source,csharp]
+----
+Environment.SetEnvironmentVariable("IGNITE_HOME",
HttpContext.Current.Server.MapPath(@"~\bin\"));
+----
+--
+
+Finally, you can use the following method to populate `JvmClasspath`:
+[tabs]
+--
+tab:C#[]
+[source,csharp]
+----
+static string GetDefaultWebClasspath()
+{
+ var dir = HttpContext.Current.Server.MapPath(@"~\bin\libs");
+
+ return string.Join(";", Directory.GetFiles(dir, "*.jar"));
+}
+----
+--
+
+== IIS Application Pool Lifecycle, AppDomains, and Ignite.NET
+
+There is a known problem with IIS. When a web application is restarted due to
code changes or a manual restart,
+the application pool process remains alive, while AppDomain gets recycled.
+
+Ignite.NET automatically stops when AppDomain is unloaded. However, a new
domain may be started when old one is still
+unloading. So the node from the old domain can have an
`IgniteConfiguration.IgniteInstanceName` conflict with a node from the new
domain.
+
+To fix this issue make sure to either assign a unique `IgniteInstanceName`, or
set
+`IgniteConfiguration.AutoGenerateIgniteInstanceName` property to `true`.
+
+[tabs]
+--
+tab:Use in C#[]
+[source,csharp]
+----
+var cfg = new IgniteConfiguration { AutoGenerateIgniteInstanceName = true };
+----
+tab:web.config[]
+[source,xml]
+----
+<igniteConfiguration autoGenerateIgniteInstanceName="true">
+ ...
+</igniteConfiguration>
+----
+--
+
+Refer to the
http://stackoverflow.com/questions/42961879/how-do-i-retrieve-a-started-ignite-instance-when-a-website-restart-occurs-in-iis/[following
StackOverflow discussion, window=_blank]
+for more details.
diff --git a/docs/_docs/net-specific/standalone-nodes.adoc
b/docs/_docs/net-specific/standalone-nodes.adoc
new file mode 100644
index 0000000..d5030ab
--- /dev/null
+++ b/docs/_docs/net-specific/standalone-nodes.adoc
@@ -0,0 +1,116 @@
+= Ignite.NET Standalone Nodes
+
+== Overview
+
+An Ignite.NET node can be started within the code of a .NET application by
using `Ignition.Start()` or as a separate
+process with `Apache.Ignite.exe` executable located under
`{apache_ignite_release}\platforms\dotnet\bin` folder.
+Internally `Apache.Ignite.exe` references `Apache.Ignite.Core.dll` and uses
`Ignition.Start()` as you would normally do,
+and can be configured with command line arguments, listed below, by passing
them as command line options or setting directly
+in `Apache.Ignite.exe.config` file.
+
+Usually, you start server nodes in the standalone mode. An Ignite cluster is a
group of server nodes interconnected
+together in order to provide shared resources like RAM and CPU to your
applications.
+
+== Configure Standalone Node via Command Line
+
+Below you can see basic Ignite parameters that can be passed as command line
arguments when a node is started with
+`Apache.Ignite.exe` executable:
+
+[width="100%",cols="1,3",opts="header"]
+|===
+|Command Line Argument |Description
+|`-IgniteHome`| A path to Ignite installation directory (if not provided, the
`IGNITE_HOME` environment variable is used)
+|`-ConfigFileName`| A path to the app.config file (if not provided,
`Apache.Ignite.exe.config` is used).
+|`-ConfigSectionName`| The name of the `IgniteConfigurationSection` from a
configuration file.
+|`-SpringConfigUrl`| A path to a Spring configuration file.
+|`-JvmDllPath`| A path to JVM library `jvm.dll` (if not provided, `JAVA_HOME`
environment variable is used).
+|`-JvmClasspath`| The classpath to pass to JVM started by Ignite.NET
internally (use to enlist additional JAR files).
+|`-SuppressWarnings`| Whether or not to print warnings.
+|`-J<javaOption>`| Additional JVM options to be used during the initialization
of the JVM.
+|`-Assembly`| Additional .NET assemblies to be loaded.
+|`-JvmInitialMemoryMB`| Initial Java heap size, in megabytes. Maps to the
`-Xms` Java parameter.
+|`-JvmMaxMemoryMB`| Maximum Java heap size, in megabytes. Maps to the `-Xmx`
Java parameter.
+|`/install`| Installs Ignite Windows service with provided options.
+|`/uninstall`| Uninstalls Ignite Windows service.
+|===
+
+
+[tabs]
+--
+tab:Example[]
+[source,shell]
+----
+Apache.Ignite.exe -ConfigFileName=c:\ignite\my-config.xml
-ConfigSectionName=igniteConfiguration -Assembly=c:\ignite\my-code.dll
-J-Xms1024m -J-Xmx2048m
+----
+--
+
+== Configure Standalone Node via XML Files
+
+A standalone node can be configured with app.config XML or Spring XML (or
both). Every command line argument, listed above,
+can also be used in `Apache.Ignite.exe.config` under `appSettings` section:
+
+[tabs]
+--
+tab:Apache.Ignite.exe.config[]
+[source,xml]
+----
+<configuration>
+ <configSections>
+ <section name="igniteConfiguration"
type="Apache.Ignite.Core.IgniteConfigurationSection, Apache.Ignite.Core" />
+ </configSections>
+
+ <igniteConfiguration springConfigUrl="c:\ignite\spring.xml">
+ <cacheConfiguration name="myCache" cacheMode="Replicated" />
+ </igniteConfiguration>
+
+ <appSettings>
+ <add key="Ignite.Assembly.1" value="my-assembly.dll"/>
+ <add key="Ignite.Assembly.2" value="my-assembly2.dll"/>
+ <add key="Ignite.ConfigSectionName" value="igniteConfiguration" />
+ </appSettings>
+</configuration>
+----
+--
+
+This example defines the `igniteConfiguration` section and uses it to start
Ignite via the `Ignite.ConfigSectionName` setting.
+It also references the Spring XML configuration file, whose settings will be
added to the specified configuration.
+
+== Load User Assemblies
+
+Some Ignite APIs involve remote code execution and require you to load
assemblies with your code into `Apache.Ignite.exe`
+via `-Assembly` command line argument or `Ignite.Assembly` app setting.
+
+The following functionality requires a corresponding assembly to be loaded on
all nodes:
+
+* ICompute (supports automatic loading, see
link:net-specific/remote-assembly-loading[Remote Assembly Loading])
+* Scan Queries with filter
+* Continuous Queries with filter
+* ICache.Invoke methods
+* ICache.LoadCache with filter
+* IServices
+* IMessaging.RemoteListen
+* IEvents.RemoteQuery
+
+[NOTE]
+====
+[discrete]
+=== Missing User Assemblies
+If a user assembly cannot be located a `Could not load file or assembly
'MyAssembly'` or one of its dependencies
+exception will be thrown.
+
+Note, that it is also necessary to add any dependencies of the user assembly
to the list.
+====
+
+== Ignite.NET as Windows Service
+
+`Apache.Ignite.exe` can be installed as a Windows Service so it is started
automatically via `/install` command line argument.
+All other command line arguments will be preserved and used each time the
service starts. Use `/uninstall` to uninstall the service.
+
+[tabs]
+--
+tab:Example[]
+[source,shell]
+----
+Apache.Ignite.exe /install -J-Xms513m -J-Xmx555m
-ConfigSectionName=igniteConfiguration
+----
+--
