Export (0) Print
Expand All

How to: Creating a Mac Add-in

Updated: October 9, 2012

Applies To: Windows Home Server 2011, Windows Server 2012 Essentials, Windows Small Business Server 2011 Essentials, Windows Storage Server 2008 R2 Essentials

Creating a Macintosh add-in is very similar to creating a standard computer (PC) add-in. Therefore, this topic covers only the differences that exist when you are creating a Macintosh add-in. For more information about how to create a standard computer add-in, see the following topic: How to: Create the Add-In Package.

WarningWarning
Add-ins that are not compliant with the requirements detailed in this topic may install on the server, but will cannot be installed on the Macintosh.

Installation and Deployment Requirements

The following list details the basic installation and deployment requirements of all Macintosh add-ins:

  • All files must be packaged into a CAB file and renamed with an extension of WSSX.

  • Add-ins are deployed by using the Launchpad after installation on the Macintosh. There is currently no means of deploying the add-in from a server.

  • Add-in bundles are installed to the users\Application Support\Microsoft\Launchpad\Data folder as a bundle on the Macintosh.

  • All Add-in Macintosh executable code is run in the context of the Launchpad user and is not elevated.

DMG File Notes and Sample

  • On the Macintosh, A DMG file is used instead of an MSI file.

  • The DMG application bundle must contain an info.plist file.

  • Macintosh binaries are listed in the <OtherBinaries> section of the AddIn.XML.

  • A single DMG file should be created for both the x86 and x64 processor operating systems. Any executable code must be compiled for Mac OS version 10.5 or 10.6 with the processor architecture set to x86_x64.

The following code example shows how to author an XML file that has a valid Macintosh DMG Reference.

<?xml version="1.0" encoding="utf-8"?>
<Package xmlns="http://schemas.microsoft.com/WindowsServerSolutions/2010/03/Addins" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Id>969033D5-6895-4EA8-AF0F-623D337BD606</Id>
  <Version>1.2.3.4</Version>
  <Name>MS Test Sample Apple Mac</Name>
  <Allow32BitOn64BitClients>false</Allow32BitOn64BitClients>
  <ServerBinary>
    <File>
      <ProductCode>0671756f-92c8-42b0-8d8d-7412391d7d90</ProductCode>
      <Version>1.2.3.4</Version>
      <Name>Server.msi</Name>
    </File>
  </ServerBinary>
  <SupportUrl>http://www.bing.com/</SupportUrl>
  <PrivacyStatement>http://www.bing.com/</PrivacyStatement>
  <OtherBinaries>
    <Item>
      <Target>Mac</Target>
      <FileName>LaunchpadAddinSample.dmg</FileName>
    </Item>
  </OtherBinaries>
</Package>

Info.plist File Notes and Sample

The Info.plist file is required to have the following sections:

  • Add-in GUID - This GUID must match the GUID in the Addin.XML file at the <Package <ID>> level.

  • Bundle version - This value must match the version in the Addin.XML file <package><Version>.

  • Bundle name.

  • Bundle display name.

The following code example shows how to author an Info.plist file.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Add-in GUID</key>
    <string>BC02CB47-8363-426c-9CA0-C75D39490301</string>
    <key>CFBundleDevelopmentRegion</key>
    <string>English</string>
    <key>CFBundleExecutable</key>
    <string>LaunchpadAddin</string>
    <key>CFBundleName</key>
    <string>LaunchpadAddin</string>
    <key>CFBundleIconFile</key>
    <string></string>
    <key>CFBundleIdentifier</key>
    <string>com.microsoft.launchpad.SampleAddin</string>
    <key>CFBundleInfoDictionaryVersion</key>
    <string>6.0</string>
    <key>CFBundlePackageType</key>
    <string>BNDL</string>
    <key>CFBundleSignature</key>
    <string>????</string>
    <key>CFBundleVersion</key>
    <string>1.2.3.4</string>
    <key>CFBundleDisplayName</key>
    <string>Addin Sample Upgraded Version</string>
    <key>CFBundleShortVersionString</key>
    <string>1.0</string>
    <key>CFPlugInDynamicRegisterFunction</key>
    <string></string>
    <key>CFPlugInDynamicRegistration</key>
    <string>NO</string>
    <key>CFPlugInFactories</key>
    <dict>
      <key>00000000-0000-0000-0000-000000000000</key>
      <string>MyFactoryFunction</string>
    </dict>
    <key>CFPlugInTypes</key>
    <dict>
      <key>00000000-0000-0000-0000-000000000000</key>
      <array>
        <string>00000000-0000-0000-0000-000000000000</string>
      </array>
    </dict>
    <key>CFPlugInUnloadFunction</key>
    <string></string>
  </dict>
</plist>

Health Alerts

Health Alerts are customized Macintosh side Add-ins. For the Macintosh Add-in, you must define two definition files, add these to the Add-in bundle, and implement a defined interface and protocol on the assembly for the alerts.

The format of these files is the same as standard computer case alerts as defined in the SDK.

  • Definition.xml

    • Defines the alerts in the bundle

    • Defines the assembly and entry points - You cannot use Assembly!Namespace#Key format; instead, use the following:

      <Assembly>MayAgents.bundle</Assembly>

      <Class>MyAgentBundle</Class>

    • Defines Class, Critical, Warning and Informational

    • Trouble shooting steps

  • Definition.xml.config (Defines configuration like timing)

Strings loaded

  • <Feature> Title

  • <Feature> Name

  • <HealthDefinition> Name

  • <HealthDefinition> Title

  • <HealthDefinition><Troubleshooting>< steps>.

Interface/Protocol

The following code example shows the point of entry called from the engine for you to process the alert. It passes back the information that is required to raise the alert on the server.

Add this code to a header file and inherit your class from it.

//-----------------------------------------------------------------------------
//Protocolheader
//-----------------------------------------------------------------------------
#import <Cocoa/Cocoa.h>

///@brief The protocol defines health engine plug-in architecture.
@protocol HealthAgent

/// @brief Agent's evaluation method. In this method, the agent performs the evaluation of its designated
///         health condition and return to the caller result that indicates whether the alert was raised, cleared 
///         or no alert happen. 
///
/// @param arguments the dictionary holds agent arguments as defined in definition.xml. 
///                     The dictionary is keyed by argument name.    
/// @param wasRaised on return indicates whether the alert was raised
///
/// @param wasCleared on return indicates whether the alert was cleared 
///
/// @param alertDetails on return holds the details of the alert
///
/// @param error an error object that describes the reason for failure 
///
/// @return YES on success, NO otherwise
-(BOOL)evaluateAlertWithArguments: (NSDictionary*) arguments
                        wasRaised: (BOOL*)wasRaised 
                       wasCleared: (BOOL*)wasCleared 
                     alertDetails: (NSString**)alertDetails 
                            error: (NSError**)error;

/// @brief the method is called by the host of the agent to indicate that is should cancel its evaluation. The 
///         call is executed on a separate thread. It is up to the agent implementation to flag canceled state and 
///         consider it in the evaluateAlertWithArguments.
-(BOOL) cancel;

@end

Alert Definition Header

#import <Cocoa/Cocoa.h>
#import "Protocolheader.h"

/// @brief Determines the health of the client's software update system. Raises or clears software update alerts.
@interface MyAlertAgentBase : NSObject<HealthAgent> 
{
}
@end

Alert Definition Code

@implementation MyAlertAgentBase

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @brief Evaluates the alert if the agent is not canceled. Agents must override this message.
-(BOOL)evaluateAlertWithArguments: (NSDictionary*) arguments
                        wasRaised: (BOOL*)wasRaised 
                       wasCleared: (BOOL*)wasCleared 
                     alertDetails: (NSString**)alertDetails 
                            error:(NSError**)error;
{
 
//Implement Alert Code here …   
    return NO;
}
@end

Show:
© 2014 Microsoft