RoleEnvironment Class

 

Provides information about the configuration, endpoints, and status of running role instances.

Namespace:   Microsoft.WindowsAzure.ServiceRuntime
Assembly:  Microsoft.WindowsAzure.ServiceRuntime (in Microsoft.WindowsAzure.ServiceRuntime.dll)

Inheritance Hierarchy

System.Object
  Microsoft.WindowsAzure.ServiceRuntime.RoleEnvironment

Syntax

[WindowsAzureHostingPermissionAttribute(SecurityAction.LinkDemand, 
    Unrestricted = true)]
public sealed class RoleEnvironment
[WindowsAzureHostingPermissionAttribute(SecurityAction::LinkDemand, 
    Unrestricted = true)]
public ref class RoleEnvironment sealed 
[<Sealed>]
[<WindowsAzureHostingPermissionAttribute(SecurityAction.LinkDemand,
    Unrestricted = true)>]
type RoleEnvironment = class end
<WindowsAzureHostingPermissionAttribute(SecurityAction.LinkDemand,
    Unrestricted := True)>
Public NotInheritable Class RoleEnvironment

Properties

Name Description
System_CAPS_pubpropertySystem_CAPS_static CurrentRoleInstance

Gets a RoleInstance object that represents the role instance in which the code is currently running.

System_CAPS_pubpropertySystem_CAPS_static DeploymentId

Gets the unique identifier of the deployment in which the role instance is running.

System_CAPS_pubpropertySystem_CAPS_static IsAvailable

Indicates whether the role instance is running in the Windows Azure environment.

System_CAPS_pubpropertySystem_CAPS_static IsEmulated

Indicates whether the role instance is running in the Microsoft Azure compute emulator.

System_CAPS_pubpropertySystem_CAPS_static Roles

Gets the set of Role objects defined for the hosted service.

Methods

Name Description
System_CAPS_pubmethod Equals(Object)

(Inherited from Object.)

System_CAPS_pubmethodSystem_CAPS_static GetConfigurationSettingValue(String)

Retrieves the value of a setting in the service configuration file.

System_CAPS_pubmethod GetHashCode()

(Inherited from Object.)

System_CAPS_pubmethodSystem_CAPS_static GetLocalResource(String)

Retrieves a specified local storage resource.

System_CAPS_pubmethod GetType()

(Inherited from Object.)

System_CAPS_pubmethodSystem_CAPS_static RequestRecycle()

Requests that the current role instance be stopped and restarted.

System_CAPS_pubmethod ToString()

(Inherited from Object.)

Fields

Name Description
System_CAPS_pubfieldSystem_CAPS_static TraceSource

Events

Name Description
System_CAPS_pubeventSystem_CAPS_static Changed

Occurs after a change to the service configuration is applied to the running instances of a role.

System_CAPS_pubeventSystem_CAPS_static Changing

Occurs before a change to the service configuration is applied to the running instances of a role.

System_CAPS_pubeventSystem_CAPS_static SimultaneousChanged

Occurs after a simultaneous change to the service configuration has been applied to the running instances of a role. A simultaneous change affects all role instances at the same time.

System_CAPS_pubeventSystem_CAPS_static SimultaneousChanging

Occurs before a simultaneous change to the service configuration is applied to the running instances of a role. A simultaneous change affects all role instances at the same time.

System_CAPS_pubeventSystem_CAPS_static StatusCheck

Occurs at a regular interval to indicate the status of a role instance.

System_CAPS_pubeventSystem_CAPS_static Stopping

Occurs when a role instance is about to be stopped.

Remarks

You use the RoleEnvironment class to obtain configuration settings, local storage resources, and endpoint information for a specified role instance. The class also provides events that allow the role instance to react to configuration changes and receive notification when the role instance is about to be stopped.

Note

Windows Azure 1.3 and later reserves for its own use any environment variables that begin with the letters "RD", for example "RdRoleID". If your application creates environment variables that begin with "RD", in certain circumstances, the IsAvailable property will return false, and other methods and properties of the RoleEnvironment class will result in the error message "role discovery data is unavailable." To correct this, use environment variables that do not begin with the letters "RD".

Note

The RoleEnvironment class can be used on standalone components in an Azure VM outside of an Azure role. These components can be programs that can be run by, for example, remoting into the role instance and starting the component from the command line. These processes must be run with elevated privileges to access the RoleEnvironment class.

The following code example shows how to get and write out the value for a configuration setting called MySetting by using the GetConfigurationSettingValue method:

var settingValue = RoleEnvironment.GetConfigurationSettingValue("MySetting"); 
Trace.WriteLine("The setting value is: " + settingValue, "Information");

For more information about defining and configuring settings, see Windows Azure Service Configuration Schema and Windows Azure Service Definition Schema.

The following code example shows how to retrieve a local storage resource and write a text file to it:

// Retrieve an object that points to the local storage resource
LocalResource localResource = RoleEnvironment.GetLocalResource("localStoreTwo");

//Define the file name and path
string[] paths = { localResource.RootPath, "MyStorageTest.txt"};
String filePath = Path.Combine(paths);

using (FileStream writeStream = File.Create(filePath))
{
   Byte[] textToWrite = new UTF8Encoding(true).GetBytes("Testing Web role storage");
   writeStream.Write(textToWrite, 0, textToWrite.Length);
}

The following code example shows how to retrieve endpoint information for the current role instance:

var roleInstance = RoleEnvironment.CurrentRoleInstance; 
foreach (RoleInstanceEndpoint instanceEndpoint in roleInstance.InstanceEndpoints.Values) 
{  
   Trace.WriteLine("Instance endpoint address and port: " + instanceEndpoint.IPEndpoint, "Information");
   Trace.WriteLine("Protocol for the endpoint: " + , instanceEndpoint.Protocol, "Information");
}

The following code example shows how to retrieve the configuration changes that have been made to a role instance:

public override bool OnStart()
{
   RoleEnvironment.Changed += RoleEnvironmentChanged;

   return base.OnStart();
}

private void RoleEnvironmentChanged(object sender, RoleEnvironmentChangedEventArgs e)
{
   // Get the list of configuration changes
   var settingChanges = e.Changes.OfType<RoleEnvironmentConfigurationSettingChange>();

   foreach (var settingChange in settingChanges) 
   {
      var message = "Setting: " + settingChange.ConfigurationSettingName;
      Trace.WriteLine(message, "Information");
   }
}

The events are only raised if an internal endpoint is defined for the role in the ServiceDefinition.csdef file. For more information about defining endpoints, see .3c806d3f-e335-4b1e-8a03-115bae2b3aab

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

See Also

RoleEnvironmentChangedEventArgs
RoleEnvironmentConfigurationSettingChange
RoleEnvironmentChangingEventArgs
RoleInstanceStatusCheckEventArgs
RoleEnvironmentStoppingEventArgs
Microsoft.WindowsAzure.ServiceRuntime Namespace

Return to top